From 3518552b5b91a6d6c38552fac1ba8b5f76fbe409 Mon Sep 17 00:00:00 2001 From: GitHub Workshop Bot Date: Fri, 8 May 2026 11:23:15 -0700 Subject: [PATCH 1/2] Update GIT Going with Github content for upcoming seminar - Restructure docs and classroom content - Add .gitattributes to enforce LF line endings across all text files - Remove deprecated podcast bundles, scripts, and transcripts - Remove old HTML file mappings replaced by updated structure - Update admin, docs, html, and learning-room content --- .gitattributes | 40 + .github/ISSUE_TEMPLATE/challenge-hub.md | 86 - .github/ISSUE_TEMPLATE/config.yml | 6 +- .../pull_request_template.md | 50 - .github/internal/challenge-hub-template.md | 97 + .../challenge-doc-consistency.test.js | 80 +- .github/workflows/registration.yml | 88 + .gitignore | 2 + .vscode/tasks.json | 11 + BATCH.md | 119 + GO-LIVE-QA-GUIDE.md | 368 + README.md | 29 +- REGISTER.md | 39 + admin/ANNOUNCEMENT.md | 13 +- admin/DAY1_AGENDA.md | 79 +- admin/DAY2_AGENDA.md | 74 +- admin/DAY2_QUICK_START.md | 2 +- .../FACILITATOR_CLASSROOM_TROUBLESHOOTING.md | 537 + admin/FACILITATOR_GUIDE.md | 828 +- admin/FACILITATOR_OPERATIONS.md | 579 + admin/FACILITATOR_RESOURCES.md | 291 + admin/PODCASTS.md | 44702 ++++++++++++++-- admin/PROGRESS_TRACKER.md | 78 +- admin/README.md | 177 + admin/REGISTER.md | 67 +- admin/REGISTRATION-QUICKSTART.md | 79 + admin/VALIDATION_AUDIT.md | 6 +- admin/classroom admin access.md | 1 + admin/classroom/README.md | 35 + admin/classroom/autograding-setup.md | 211 + admin/classroom/day1-assignment-copy-paste.md | 90 + admin/classroom/day2-assignment-copy-paste.md | 91 + admin/classroom/live-facilitation-flow.md | 96 + admin/classroom/seeding-ops.md | 54 + build-rss-feed.bat | 38 + classroom/README.md | 19 +- classroom/assignment-day1-you-belong-here.md | 30 +- .../assignment-day2-you-can-build-this.md | 34 +- .../assignment-issue-template.md | 37 +- classroom/autograding-day2.json | 12 +- classroom/challenge-content-review.md | 302 +- classroom/grading-guide.md | 2 +- classroom/student-progression.yml | 16 +- docs/00-pre-workshop-setup.md | 6 +- docs/01-choose-your-tools.md | 2 +- docs/02-understanding-github.md | 4 +- docs/03-navigating-repositories.md | 10 +- docs/04-the-learning-room.md | 22 +- docs/05-working-with-issues.md | 26 +- docs/06-working-with-pull-requests.md | 10 +- docs/07-merge-conflicts.md | 6 +- docs/08-open-source-culture.md | 6 +- docs/09-labels-milestones-projects.md | 7 +- docs/10-notifications-and-day-1-close.md | 4 +- docs/11-vscode-interface.md | 18 +- docs/12-vscode-accessibility.md | 2 +- docs/14-git-in-practice.md | 28 +- docs/15-code-review.md | 50 +- docs/16-github-copilot.md | 34 +- docs/17-issue-templates.md | 36 +- docs/19-accessibility-agents.md | 46 +- docs/CHALLENGES.md | 261 +- docs/appendix-a-glossary.md | 2 +- docs/appendix-b-screen-reader-cheatsheet.md | 4 +- docs/appendix-c-markdown-reference.md | 8 +- docs/appendix-d-git-authentication.md | 2 +- docs/appendix-e-advanced-git.md | 4 +- docs/appendix-f-git-security.md | 16 +- docs/appendix-g-vscode-reference.md | 4 +- docs/appendix-h-github-desktop.md | 34 +- docs/appendix-j-cloud-editors.md | 2 +- docs/appendix-k-copilot-reference.md | 12 +- docs/appendix-l-agents-reference.md | 6 +- docs/appendix-m-accessibility-standards.md | 2 +- docs/appendix-n-advanced-search.md | 2 +- docs/appendix-o-branch-protection.md | 2 +- docs/appendix-p-security-features.md | 4 +- docs/appendix-q-actions-workflows.md | 2 +- docs/appendix-r-projects-deep-dive.md | 2 +- docs/appendix-s-releases-tags-insights.md | 2 +- docs/appendix-t-community-and-social.md | 4 +- docs/appendix-u-discussions-and-gists.md | 4 +- docs/appendix-v-github-mobile.md | 2 +- docs/appendix-w-github-pages.md | 2 +- docs/appendix-x-resources.md | 2 +- docs/appendix-y-workshop-materials.md | 2 +- docs/appendix-z-github-skills.md | 2 +- docs/course-guide.md | 33 +- docs/get-going.md | 135 + docs/images/learning-room-tree.svg | 12 +- facilitator/FACILITATOR_GUIDE.md | 307 - generate-audio.bat | 69 + generate-transcripts.bat | 62 + html/ACCESSIBILITY_TESTING.html | 401 - html/BATCH.html | 200 + html/BUILD.html | 3 +- html/CODE_OF_CONDUCT.html | 3 +- html/COMING_SOON.html | 3 +- html/COMPREHENSIVE_VALIDATION_AUDIT.html | 1516 - html/CONTRIBUTING.html | 3 +- html/DAY1_AGENDA.html | 929 - html/DAY2_AGENDA.html | 714 - html/FACILITATOR.html | 1107 - html/FACILITATOR_ASSESSMENT.html | 313 - html/FAQ.html | 869 - html/GITHUB_PROPOSAL.html | 856 - html/GO-LIVE-QA-GUIDE.html | 458 + html/PODCASTS.html | 4578 -- html/PROGRESS_TRACKER.html | 579 - html/QUICK_REFERENCE.html | 486 - html/README.html | 33 +- html/REGISTER.html | 152 +- html/REGISTRATION-ADMIN.html | 149 - html/REPOSITORY_SECURITY.html | 3 +- html/SECURITY.html | 3 +- html/TROUBLESHOOTING.html | 1039 - html/admin/ACCESSIBILITY_TESTING.html | 209 +- html/admin/ANNOUNCEMENT.html | 15 +- html/admin/COHORT_PROVISIONING.html | 3 +- html/admin/DAY1_AGENDA.html | 162 +- html/admin/DAY2_AGENDA.html | 112 +- html/admin/DAY2_QUICK_START.html | 17 +- html/admin/FACILITATOR_ASSESSMENT.html | 3 +- html/admin/FACILITATOR_CHALLENGES.html | 19 +- ...FACILITATOR_CLASSROOM_TROUBLESHOOTING.html | 634 + html/admin/FACILITATOR_GUIDE.html | 839 +- html/admin/FACILITATOR_OPERATIONS.html | 654 + html/admin/FACILITATOR_RESOURCES.html | 378 + html/admin/FAQ.html | 5 +- html/admin/GITHUB_PROPOSAL.html | 59 +- html/admin/PODCASTS.html | 26320 +++++++-- html/admin/PROGRESS_TRACKER.html | 307 +- html/admin/QUICK_REFERENCE.html | 17 +- html/admin/REGISTER.html | 84 +- html/admin/REGISTRATION-ADMIN.html | 76 +- html/admin/REGISTRATION-QUICKSTART.html | 165 + html/admin/STUDENT_MANAGEMENT.html | 3 +- html/admin/STUDENT_ONBOARDING_EMAIL.html | 3 +- html/admin/TROUBLESHOOTING.html | 3 +- html/admin/VALIDATION_AUDIT.html | 58 +- html/admin/classroom admin access.html | 70 + html/admin/classroom/autograding-setup.html | 258 + .../classroom/day1-assignment-copy-paste.html | 153 + .../classroom/day2-assignment-copy-paste.html | 154 + html/admin/classroom/index.html | 100 + .../classroom/live-facilitation-flow.html | 150 + html/admin/classroom/seeding-ops.html | 107 + html/admin/index.html | 307 + .../IMAGE-ALT-TEXT-DOCS.html | 3 +- .../agents/image-alt-text.agent.html | 3 +- .../agents/image-analyzer.agent.html | 3 +- .../agents/image-cataloger.agent.html | 3 +- .../agents/tag-builder.agent.html | 3 +- .../image-dimensions.instructions.html | 3 +- .../prompts/image-analyzer.prompt.html | 3 +- .../prompts/image-cataloger.prompt.html | 3 +- .../prompts/tag-builder.prompt.html | 3 +- html/classroom/HUMAN_TEST_MATRIX.html | 3 +- .../assignment-day1-you-belong-here.html | 31 +- .../assignment-day2-you-can-build-this.html | 37 +- html/classroom/assignment-issue-template.html | 185 + html/classroom/challenge-content-review.html | 353 +- html/classroom/grading-guide.html | 5 +- html/classroom/index.html | 72 +- html/classroom/teardown-checklist.html | 39 +- html/docs/00-pre-workshop-setup.html | 10 +- html/docs/01-choose-your-tools.html | 5 +- ...01-understanding-github-web-structure.html | 667 - html/docs/02-navigating-repositories.html | 752 - html/docs/02-understanding-github.html | 7 +- html/docs/03-navigating-repositories.html | 13 +- html/docs/03-the-learning-room.html | 772 - html/docs/04-the-learning-room.html | 25 +- html/docs/04-working-with-issues.html | 1149 - html/docs/05-vscode-accessibility.html | 2902 - html/docs/05-working-with-issues.html | 30 +- html/docs/05-working-with-pull-requests.html | 1124 - html/docs/06-merge-conflicts.html | 544 - html/docs/06-working-with-pull-requests.html | 14 +- html/docs/07-culture-etiquette.html | 594 - html/docs/07-merge-conflicts.html | 19 +- html/docs/08-culture-etiquette.html | 724 - html/docs/08-labels-milestones-projects.html | 577 - html/docs/08-open-source-culture.html | 9 +- html/docs/09-labels-milestones-projects.html | 9 +- html/docs/09-notifications.html | 616 - .../10-notifications-and-day-1-close.html | 7 +- html/docs/10-notifications.html | 625 - html/docs/10-vscode-basics.html | 951 - html/docs/11-git-source-control.html | 1964 - html/docs/11-vscode-interface.html | 21 +- .../12-github-pull-requests-extension.html | 878 - html/docs/12-vscode-accessibility.html | 5 +- html/docs/13-github-copilot.html | 1538 - html/docs/13-how-git-works.html | 5 +- html/docs/14-accessible-code-review.html | 1604 - html/docs/14-git-in-practice.html | 33 +- html/docs/15-code-review.html | 131 +- html/docs/15-issue-templates.html | 2182 - html/docs/16-accessibility-agents.html | 2245 - html/docs/16-github-copilot.html | 51 +- html/docs/17-issue-templates.html | 73 +- html/docs/18-fork-and-contribute.html | 23 +- html/docs/19-accessibility-agents.html | 81 +- html/docs/20-build-your-agent.html | 33 +- html/docs/21-next-steps.html | 3 +- html/docs/CHALLENGES.html | 233 +- html/docs/appendix-a-glossary.html | 7 +- html/docs/appendix-aa-advanced-git.html | 919 - html/docs/appendix-ab-github-desktop.html | 571 - html/docs/appendix-ac-github-cli.html | 757 - html/docs/appendix-ad-git-security.html | 490 - html/docs/appendix-ae-github-social.html | 522 - .../appendix-b-screen-reader-cheatsheet.html | 7 +- .../appendix-c-accessibility-standards.html | 586 - html/docs/appendix-c-markdown-reference.html | 79 +- html/docs/appendix-d-git-authentication.html | 5 +- html/docs/appendix-e-advanced-git.html | 7 +- .../appendix-e-github-flavored-markdown.html | 2374 - html/docs/appendix-f-git-security.html | 47 +- html/docs/appendix-f-github-gists.html | 315 - html/docs/appendix-g-github-discussions.html | 279 - html/docs/appendix-g-vscode-reference.html | 7 +- html/docs/appendix-h-github-desktop.html | 37 +- .../appendix-h-releases-tags-insights.html | 538 - html/docs/appendix-i-github-cli.html | 3 +- html/docs/appendix-i-github-projects.html | 468 - html/docs/appendix-j-advanced-search.html | 424 - html/docs/appendix-j-cloud-editors.html | 5 +- ...appendix-k-branch-protection-rulesets.html | 401 - html/docs/appendix-k-copilot-reference.html | 15 +- html/docs/appendix-l-agents-reference.html | 9 +- .../appendix-l-github-security-features.html | 348 - .../appendix-m-accessibility-standards.html | 5 +- ...ndix-m-vscode-accessibility-reference.html | 1786 - html/docs/appendix-n-advanced-search.html | 5 +- html/docs/appendix-n-github-codespaces.html | 424 - html/docs/appendix-o-branch-protection.html | 5 +- html/docs/appendix-o-github-mobile.html | 371 - html/docs/appendix-p-github-pages.html | 381 - html/docs/appendix-p-security-features.html | 13 +- html/docs/appendix-q-actions-workflows.html | 5 +- .../appendix-q-github-actions-workflows.html | 621 - ...endix-r-github-profile-sponsors-wikis.html | 221 - html/docs/appendix-r-projects-deep-dive.html | 5 +- ...ndix-s-github-organizations-templates.html | 213 - .../appendix-s-releases-tags-insights.html | 5 +- .../docs/appendix-t-community-and-social.html | 7 +- ...ppendix-t-contributing-to-open-source.html | 213 - .../appendix-u-discussions-and-gists.html | 7 +- html/docs/appendix-u-resources.html | 1455 - ...ndix-v-accessibility-agents-reference.html | 1927 - html/docs/appendix-v-github-mobile.html | 5 +- .../appendix-w-github-copilot-reference.html | 1673 - html/docs/appendix-w-github-pages.html | 5 +- html/docs/appendix-x-copilot-models.html | 570 - html/docs/appendix-x-resources.html | 5 +- ...pendix-y-accessing-workshop-materials.html | 273 - html/docs/appendix-y-workshop-materials.html | 5 +- .../appendix-z-github-skills-catalog.html | 755 - html/docs/appendix-z-github-skills.html | 5 +- html/docs/course-guide.html | 39 +- html/docs/get-going.html | 181 + .../solutions/solution-01-scavenger-hunt.html | 3 +- .../solutions/solution-02-first-issue.html | 3 +- .../solutions/solution-03-conversation.html | 3 +- .../solutions/solution-04-branch-out.html | 3 +- .../solutions/solution-05-make-your-mark.html | 3 +- html/docs/solutions/solution-06-first-pr.html | 3 +- .../solutions/solution-07-merge-conflict.html | 7 +- html/docs/solutions/solution-08-culture.html | 3 +- .../docs/solutions/solution-09-merge-day.html | 3 +- html/docs/solutions/solution-10-go-local.html | 3 +- html/docs/solutions/solution-11-day2-pr.html | 3 +- html/docs/solutions/solution-12-review.html | 3 +- html/docs/solutions/solution-13-copilot.html | 3 +- html/docs/solutions/solution-14-template.html | 3 +- html/docs/solutions/solution-15-agents.html | 3 +- html/docs/solutions/solution-16-capstone.html | 3 +- html/docs/solutions/solution-bonus-a.html | 3 +- html/docs/solutions/solution-bonus-b.html | 3 +- html/docs/solutions/solution-bonus-c.html | 3 +- html/docs/solutions/solution-bonus-d.html | 3 +- html/docs/solutions/solution-bonus-e.html | 3 +- html/docs/student-onboarding.html | 3 +- html/facilitator/FACILITATOR_GUIDE.html | 392 - html/index.html | 393 - html/learning-room/docs/CHALLENGES.html | 1022 - html/learning-room/docs/course-roadmap.html | 148 + .../docs/keyboard-shortcuts.html | 3 +- .../docs/samples/agent-file-template.html | 3 +- .../chapter-6-conflict-practice-sample.html | 5 +- .../samples/copilot-improvement-before.html | 3 +- .../docs/samples/fork-workflow-checklist.html | 83 +- html/learning-room/docs/setup-guide.html | 16 +- .../docs/skills-bonus-scenarios.html | 141 + html/learning-room/docs/solutions/index.html | 182 + html/learning-room/docs/welcome.html | 6 +- html/learning-room/index.html | 22 +- html/podcasts/REGENERATION.html | 257 + html/podcasts/bundles/ep00-welcome.html | 1421 - .../bundles/ep01-pre-workshop-setup.html | 1205 - .../bundles/ep02-github-web-structure.html | 2281 - .../bundles/ep03-navigating-repositories.html | 1414 - .../bundles/ep04-the-learning-room.html | 716 - .../bundles/ep05-working-with-issues.html | 1474 - .../ep06-working-with-pull-requests.html | 2184 - .../bundles/ep07-merge-conflicts.html | 528 - .../bundles/ep08-culture-and-etiquette.html | 767 - .../ep09-labels-milestones-projects.html | 1089 - html/podcasts/bundles/ep10-notifications.html | 618 - html/podcasts/bundles/ep11-vscode-basics.html | 2684 - .../bundles/ep12-git-source-control.html | 1436 - .../bundles/ep13-github-prs-extension.html | 1745 - .../podcasts/bundles/ep14-github-copilot.html | 3209 -- .../bundles/ep15-accessible-code-review.html | 2828 - .../bundles/ep16-issue-templates.html | 2063 - .../bundles/ep17-accessibility-agents.html | 3940 -- html/podcasts/bundles/ep18-glossary.html | 836 - .../ep19-screen-reader-cheatsheet.html | 1636 - .../bundles/ep20-accessibility-standards.html | 629 - .../bundles/ep21-git-authentication.html | 353 - .../ep22-github-flavored-markdown.html | 605 - html/podcasts/bundles/ep23-github-gists.html | 360 - .../bundles/ep24-github-discussions.html | 325 - .../bundles/ep25-releases-tags-insights.html | 587 - .../bundles/ep26-github-projects.html | 603 - .../bundles/ep27-advanced-search.html | 471 - .../bundles/ep28-branch-protection.html | 449 - .../bundles/ep29-security-features.html | 395 - .../ep30-vscode-accessibility-reference.html | 1842 - .../bundles/ep31-github-codespaces.html | 470 - html/podcasts/bundles/ep32-github-mobile.html | 417 - html/podcasts/bundles/ep33-github-pages.html | 428 - .../podcasts/bundles/ep34-github-actions.html | 677 - .../bundles/ep35-profile-sponsors-wikis.html | 266 - .../bundles/ep36-organizations-templates.html | 259 - .../ep37-contributing-to-open-source.html | 955 - html/podcasts/bundles/ep38-resources.html | 1497 - .../ep39-accessibility-agents-reference.html | 1976 - .../bundles/ep40-copilot-reference.html | 1723 - .../podcasts/bundles/ep41-copilot-models.html | 614 - .../ep42-accessing-workshop-materials.html | 315 - .../bundles/ep43-github-skills-catalog.html | 801 - html/podcasts/index.html | 146 +- html/podcasts/tts/index.html | 144 + html/scripts/vibevoice/index.html | 214 + html/search-index.json | 776 +- html/search.html | 2 +- html/wxpython-specialist-original.html | 869 - learning-room/README.md | 8 +- learning-room/docs/setup-guide.md | 4 +- learning-room/docs/welcome.md | 2 + learning-room/package.json | 4 +- package.json | 25 +- podcasts/README.md | 220 +- podcasts/REGENERATION.md | 209 + podcasts/build-bundles.js | 291 +- podcasts/build-challenge-bundles.js | 142 + podcasts/bundles/ep00-welcome.md | 898 - podcasts/bundles/ep01-pre-workshop-setup.md | 1180 - podcasts/bundles/ep02-github-web-structure.md | 1242 - .../bundles/ep03-navigating-repositories.md | 1247 - podcasts/bundles/ep04-the-learning-room.md | 643 - podcasts/bundles/ep05-working-with-issues.md | 1395 - .../ep06-working-with-pull-requests.md | 2221 - podcasts/bundles/ep07-merge-conflicts.md | 554 - .../bundles/ep08-culture-and-etiquette.md | 792 - .../ep09-labels-milestones-projects.md | 1023 - podcasts/bundles/ep10-notifications.md | 449 - podcasts/bundles/ep11-vscode-basics.md | 1402 - podcasts/bundles/ep12-git-source-control.md | 1500 - podcasts/bundles/ep13-github-prs-extension.md | 1727 - podcasts/bundles/ep14-github-copilot.md | 2142 - .../bundles/ep15-accessible-code-review.md | 1992 - podcasts/bundles/ep16-issue-templates.md | 2061 - podcasts/bundles/ep17-accessibility-agents.md | 3194 -- podcasts/bundles/ep18-glossary.md | 659 - .../bundles/ep19-screen-reader-cheatsheet.md | 717 - .../bundles/ep20-accessibility-standards.md | 314 - podcasts/bundles/ep21-git-authentication.md | 386 - .../bundles/ep22-github-flavored-markdown.md | 507 - podcasts/bundles/ep23-github-gists.md | 281 - podcasts/bundles/ep24-github-discussions.md | 297 - .../bundles/ep25-releases-tags-insights.md | 555 - podcasts/bundles/ep26-github-projects.md | 544 - podcasts/bundles/ep27-advanced-search.md | 338 - podcasts/bundles/ep28-branch-protection.md | 366 - podcasts/bundles/ep29-security-features.md | 405 - .../ep30-vscode-accessibility-reference.md | 828 - podcasts/bundles/ep31-github-codespaces.md | 319 - podcasts/bundles/ep32-github-mobile.md | 271 - podcasts/bundles/ep33-github-pages.md | 406 - podcasts/bundles/ep34-github-actions.md | 553 - .../bundles/ep35-profile-sponsors-wikis.md | 232 - .../bundles/ep36-organizations-templates.md | 186 - .../ep37-contributing-to-open-source.md | 509 - podcasts/bundles/ep38-resources.md | 856 - .../ep39-accessibility-agents-reference.md | 1219 - podcasts/bundles/ep40-copilot-reference.md | 1084 - podcasts/bundles/ep41-copilot-models.md | 262 - .../ep42-accessing-workshop-materials.md | 238 - .../bundles/ep43-github-skills-catalog.md | 343 - podcasts/feed.xml | 30540 ++++++++--- .../generate-draft-transcripts-extraction.js | 440 + podcasts/generate-draft-transcripts-old.js | 446 + podcasts/generate-draft-transcripts.js | 995 + podcasts/generate-site.js | 464 +- podcasts/generate_all_episodes_with_piper.py | 9 +- podcasts/listening-order.json | 88 + podcasts/logs/audio_inventory_report.json | 1173 + podcasts/logs/kokoro_samples.log | 166 + podcasts/logs/kokoro_voice_manifest.json | 90 + podcasts/logs/kokoro_voices_all.txt | 54 + .../kokoro_voices_english_high_quality.txt | 28 + podcasts/logs/piper_samples.log | 6 + podcasts/logs/piper_voices_current.txt | 158 + podcasts/manifest.json | 303 +- .../reorganize_scripts_and_transcripts.py | 182 + podcasts/scripts/appendices/ep18-glossary.txt | 509 + .../ep19-screen-reader-cheatsheet.txt | 310 + .../ep20-accessibility-standards.txt | 153 + .../appendices/ep21-git-authentication.txt | 399 + .../ep22-github-flavored-markdown.txt | 1180 + .../scripts/appendices/ep23-github-gists.txt | 451 + .../appendices/ep24-github-discussions.txt | 451 + .../ep25-releases-tags-insights.txt | 399 + .../appendices/ep26-github-projects.txt | 449 + .../appendices/ep27-advanced-search.txt | 104 + .../appendices/ep28-branch-protection.txt | 268 + .../appendices/ep29-security-features.txt | 263 + .../ep30-vscode-accessibility-reference.txt | 292 + .../appendices/ep31-github-codespaces.txt | 275 + .../scripts/appendices/ep32-github-mobile.txt | 237 + .../scripts/appendices/ep33-github-pages.txt | 277 + .../appendices/ep34-github-actions.txt | 360 + .../ep35-profile-sponsors-wikis.txt | 779 + .../ep36-organizations-templates.txt | 779 + .../scripts/appendices/ep38-resources.txt | 504 + .../ep39-accessibility-agents-reference.txt | 532 + .../appendices/ep40-copilot-reference.txt | 678 + .../appendices/ep41-copilot-models.txt | 678 + .../ep42-accessing-workshop-materials.txt | 209 + .../appendices/ep43-github-skills-catalog.txt | 162 + .../ep50-advanced-git-operations.txt | 606 + .../ep51-git-security-for-contributors.txt | 312 + .../appendices/ep52-github-desktop.txt | 481 + .../appendices/ep53-github-cli-reference.txt | 392 + .../challenges/cc-01-find-your-way-around.txt | 1417 + .../cc-02-file-your-first-issue.txt | 803 + .../cc-03-join-the-conversation.txt | 1649 + .../scripts/challenges/cc-04-branch-out.txt | 1446 + .../challenges/cc-05-make-your-mark.txt | 1423 + .../challenges/cc-06-open-your-first-pr.txt | 909 + .../cc-07-survive-a-merge-conflict.txt | 487 + .../challenges/cc-08-open-source-culture.txt | 1252 + .../scripts/challenges/cc-09-merge-day.txt | 1241 + .../scripts/challenges/cc-10-go-local.txt | 1909 + .../challenges/cc-11-day-2-pull-request.txt | 3449 ++ .../scripts/challenges/cc-12-code-review.txt | 2780 + .../cc-13-copilot-as-collaborator.txt | 1115 + .../cc-14-design-an-issue-template.txt | 1252 + .../cc-15-discover-accessibility-agents.txt | 1600 + .../challenges/cc-16-build-your-own-agent.txt | 1446 + .../challenges/cc-bonus-a-improve-agent.txt | 1402 + .../cc-bonus-b-document-your-journey.txt | 2025 + .../challenges/cc-bonus-c-group-challenge.txt | 2774 + .../challenges/cc-bonus-d-notifications.txt | 466 + .../challenges/cc-bonus-e-git-history.txt | 950 + podcasts/scripts/chapters/ep00-welcome.txt | 217 + .../chapters/ep01-pre-workshop-setup.txt | 765 + .../chapters/ep02-github-web-structure.txt | 314 + .../chapters/ep03-navigating-repositories.txt | 540 + .../chapters/ep04-the-learning-room.txt | 593 + .../chapters/ep05-working-with-issues.txt | 746 + .../ep06-working-with-pull-requests.txt | 820 + .../scripts/chapters/ep07-merge-conflicts.txt | 412 + .../chapters/ep08-culture-and-etiquette.txt | 864 + .../ep09-labels-milestones-projects.txt | 384 + .../scripts/chapters/ep10-notifications.txt | 391 + .../scripts/chapters/ep11-vscode-basics.txt | 627 + .../chapters/ep12-git-source-control.txt | 1565 + .../chapters/ep13-github-prs-extension.txt | 1897 + .../scripts/chapters/ep14-github-copilot.txt | 1047 + .../chapters/ep15-accessible-code-review.txt | 1897 + .../scripts/chapters/ep16-issue-templates.txt | 1194 + .../chapters/ep17-accessibility-agents.txt | 1042 + .../ep37-contributing-to-open-source.txt | 864 + .../chapters/ep44-choose-your-tools.txt | 339 + .../ep45-vscode-accessibility-deep-dive.txt | 491 + .../scripts/chapters/ep46-how-git-works.txt | 295 + .../chapters/ep47-fork-and-contribute.txt | 511 + .../ep48-build-your-agent-capstone.txt | 356 + podcasts/scripts/chapters/ep49-next-steps.txt | 231 + podcasts/scripts/ep00-welcome.txt | 172 - podcasts/scripts/ep01-pre-workshop-setup.txt | 271 - .../scripts/ep02-github-web-structure.txt | 294 - .../scripts/ep03-navigating-repositories.txt | 216 - podcasts/scripts/ep04-the-learning-room.txt | 302 - podcasts/scripts/ep05-working-with-issues.txt | 326 - .../ep06-working-with-pull-requests.txt | 303 - podcasts/scripts/ep07-merge-conflicts.txt | 250 - .../scripts/ep08-culture-and-etiquette.txt | 201 - .../ep09-labels-milestones-projects.txt | 229 - podcasts/scripts/ep10-notifications.txt | 283 - podcasts/scripts/ep11-vscode-basics.txt | 274 - podcasts/scripts/ep12-git-source-control.txt | 389 - .../scripts/ep13-github-prs-extension.txt | 333 - podcasts/scripts/ep14-github-copilot.txt | 311 - .../scripts/ep15-accessible-code-review.txt | 303 - podcasts/scripts/ep16-issue-templates.txt | 275 - .../scripts/ep17-accessibility-agents.txt | 291 - podcasts/scripts/ep18-glossary.txt | 216 - .../scripts/ep19-screen-reader-cheatsheet.txt | 208 - .../scripts/ep20-accessibility-standards.txt | 311 - podcasts/scripts/ep21-git-authentication.txt | 293 - .../scripts/ep22-github-flavored-markdown.txt | 286 - podcasts/scripts/ep23-github-gists.txt | 284 - podcasts/scripts/ep24-github-discussions.txt | 130 - .../scripts/ep25-releases-tags-insights.txt | 258 - podcasts/scripts/ep26-github-projects.txt | 314 - podcasts/scripts/ep27-advanced-search.txt | 271 - podcasts/scripts/ep28-branch-protection.txt | 269 - podcasts/scripts/ep29-security-features.txt | 322 - .../ep30-vscode-accessibility-reference.txt | 318 - podcasts/scripts/ep31-github-codespaces.txt | 296 - podcasts/scripts/ep32-github-mobile.txt | 305 - podcasts/scripts/ep33-github-pages.txt | 320 - podcasts/scripts/ep34-github-actions.txt | 306 - .../scripts/ep35-profile-sponsors-wikis.txt | 206 - .../scripts/ep36-organizations-templates.txt | 248 - .../ep37-contributing-to-open-source.txt | 244 - podcasts/scripts/ep38-resources.txt | 243 - .../ep39-accessibility-agents-reference.txt | 276 - podcasts/scripts/ep40-copilot-reference.txt | 239 - podcasts/scripts/ep41-copilot-models.txt | 206 - .../ep42-accessing-workshop-materials.txt | 265 - .../scripts/ep43-github-skills-catalog.txt | 246 - podcasts/tag-audio-metadata.py | 600 + .../appendices/ep18-glossary-segments.json | 714 + ...p19-screen-reader-cheatsheet-segments.json | 438 + ...ep20-accessibility-standards-segments.json | 218 + .../ep21-git-authentication-segments.json | 558 + ...p22-github-flavored-markdown-segments.json | 1654 + .../ep23-github-gists-segments.json | 630 + .../ep24-github-discussions-segments.json | 630 + .../ep25-releases-tags-insights-segments.json | 558 + .../ep26-github-projects-segments.json | 626 + .../ep27-advanced-search-segments.json | 150 + .../ep28-branch-protection-segments.json | 378 + .../ep29-security-features-segments.json | 370 + ...code-accessibility-reference-segments.json | 410 + .../ep31-github-codespaces-segments.json | 386 + .../ep32-github-mobile-segments.json | 334 + .../ep33-github-pages-segments.json | 390 + .../ep34-github-actions-segments.json | 506 + .../ep35-profile-sponsors-wikis-segments.json | 1086 + ...ep36-organizations-templates-segments.json | 1086 + .../appendices/ep38-resources-segments.json | 706 + ...cessibility-agents-reference-segments.json | 746 + .../ep40-copilot-reference-segments.json | 950 + .../ep41-copilot-models-segments.json | 950 + ...accessing-workshop-materials-segments.json | 294 + .../ep43-github-skills-catalog-segments.json | 230 + ...ep50-advanced-git-operations-segments.json | 846 + ...it-security-for-contributors-segments.json | 438 + .../ep52-github-desktop-segments.json | 670 + .../ep53-github-cli-reference-segments.json | 546 + .../cc-01-find-your-way-around-segments.json | 1970 + .../cc-02-file-your-first-issue-segments.json | 1114 + .../cc-03-join-the-conversation-segments.json | 2290 + .../challenges/cc-04-branch-out-segments.json | 2002 + .../cc-05-make-your-mark-segments.json | 1970 + .../cc-06-open-your-first-pr-segments.json | 1258 + ...-07-survive-a-merge-conflict-segments.json | 678 + .../cc-08-open-source-culture-segments.json | 1742 + .../challenges/cc-09-merge-day-segments.json | 1718 + .../challenges/cc-10-go-local-segments.json | 2638 + .../cc-11-day-2-pull-request-segments.json | 4754 ++ .../cc-12-code-review-segments.json | 3846 ++ ...c-13-copilot-as-collaborator-segments.json | 1550 + ...-14-design-an-issue-template-segments.json | 1726 + ...iscover-accessibility-agents-segments.json | 2230 + .../cc-16-build-your-own-agent-segments.json | 2010 + .../cc-bonus-a-improve-agent-segments.json | 1950 + ...onus-b-document-your-journey-segments.json | 2830 + .../cc-bonus-c-group-challenge-segments.json | 3838 ++ .../cc-bonus-d-notifications-segments.json | 650 + .../cc-bonus-e-git-history-segments.json | 1326 + .../chapters/ep00-welcome-segments.json | 306 + .../ep01-pre-workshop-setup-segments.json | 1062 + .../ep02-github-web-structure-segments.json | 442 + ...ep03-navigating-repositories-segments.json | 750 + .../ep04-the-learning-room-segments.json | 826 + .../ep05-working-with-issues-segments.json | 1034 + ...6-working-with-pull-requests-segments.json | 1134 + .../ep07-merge-conflicts-segments.json | 574 + .../ep08-culture-and-etiquette-segments.json | 1206 + ...9-labels-milestones-projects-segments.json | 534 + .../chapters/ep10-notifications-segments.json | 546 + .../chapters/ep11-vscode-basics-segments.json | 874 + .../ep12-git-source-control-segments.json | 2158 + .../ep13-github-prs-extension-segments.json | 2618 + .../ep14-github-copilot-segments.json | 1454 + .../ep15-accessible-code-review-segments.json | 2618 + .../ep16-issue-templates-segments.json | 1646 + .../ep17-accessibility-agents-segments.json | 1450 + ...-contributing-to-open-source-segments.json | 1206 + .../ep44-choose-your-tools-segments.json | 478 + ...code-accessibility-deep-dive-segments.json | 690 + .../chapters/ep46-how-git-works-segments.json | 418 + .../ep47-fork-and-contribute-segments.json | 710 + ...48-build-your-agent-capstone-segments.json | 498 + .../chapters/ep49-next-steps-segments.json | 326 + .../transcripts/ep00-welcome-segments.json | 314 - .../ep01-pre-workshop-setup-segments.json | 422 - .../ep02-github-web-structure-segments.json | 418 - ...ep03-navigating-repositories-segments.json | 314 - .../ep04-the-learning-room-segments.json | 426 - .../ep05-working-with-issues-segments.json | 450 - ...6-working-with-pull-requests-segments.json | 418 - .../ep07-merge-conflicts-segments.json | 378 - .../ep08-culture-and-etiquette-segments.json | 338 - ...9-labels-milestones-projects-segments.json | 350 - .../ep10-notifications-segments.json | 414 - .../ep11-vscode-basics-segments.json | 398 - .../ep12-git-source-control-segments.json | 550 - .../ep13-github-prs-extension-segments.json | 454 - .../ep14-github-copilot-segments.json | 442 - .../ep15-accessible-code-review-segments.json | 426 - .../ep16-issue-templates-segments.json | 406 - .../ep17-accessibility-agents-segments.json | 418 - .../transcripts/ep18-glossary-segments.json | 330 - ...p19-screen-reader-cheatsheet-segments.json | 338 - ...ep20-accessibility-standards-segments.json | 454 - .../ep21-git-authentication-segments.json | 422 - ...p22-github-flavored-markdown-segments.json | 406 - .../ep23-github-gists-segments.json | 394 - .../ep24-github-discussions-segments.json | 206 - .../ep25-releases-tags-insights-segments.json | 406 - .../ep26-github-projects-segments.json | 450 - .../ep27-advanced-search-segments.json | 386 - .../ep28-branch-protection-segments.json | 410 - .../ep29-security-features-segments.json | 466 - ...code-accessibility-reference-segments.json | 450 - .../ep31-github-codespaces-segments.json | 438 - .../ep32-github-mobile-segments.json | 446 - .../ep33-github-pages-segments.json | 446 - .../ep34-github-actions-segments.json | 446 - .../ep35-profile-sponsors-wikis-segments.json | 338 - ...ep36-organizations-templates-segments.json | 422 - ...-contributing-to-open-source-segments.json | 358 - .../transcripts/ep38-resources-segments.json | 386 - ...cessibility-agents-reference-segments.json | 414 - .../ep40-copilot-reference-segments.json | 366 - .../ep41-copilot-models-segments.json | 326 - ...accessing-workshop-materials-segments.json | 378 - .../ep43-github-skills-catalog-segments.json | 350 - podcasts/tts/README.md | 89 + podcasts/tts/__init__.py | 4 +- podcasts/tts/download_kokoro_samples.py | 201 + podcasts/tts/generate_all.py | 80 +- podcasts/tts/generate_all_kokoro.py | 484 + podcasts/tts/generate_episode.py | 318 +- podcasts/tts/voice-config.ini | 156 + podcasts/validate-catalog.js | 90 + podcasts/validate-feed.js | 143 + podcasts/verify_audio_inventory.py | 368 + scripts/build-html.js | 171 +- scripts/build-podcasts.ps1 | 34 + scripts/vibevoice/README.md | 124 + scripts/vibevoice/generate-voice-samples.bat | 41 + scripts/vibevoice/generate-voice-samples.py | 304 + scripts/vibevoice/setup-vibevoice.bat | 106 + validate-rss-feed.bat | 45 + 675 files changed, 256278 insertions(+), 197920 deletions(-) create mode 100644 .gitattributes delete mode 100644 .github/ISSUE_TEMPLATE/challenge-hub.md delete mode 100644 .github/PULL_REQUEST_TEMPLATE/pull_request_template.md create mode 100644 .github/internal/challenge-hub-template.md create mode 100644 .vscode/tasks.json create mode 100644 BATCH.md create mode 100644 GO-LIVE-QA-GUIDE.md create mode 100644 REGISTER.md create mode 100644 admin/FACILITATOR_CLASSROOM_TROUBLESHOOTING.md create mode 100644 admin/FACILITATOR_OPERATIONS.md create mode 100644 admin/FACILITATOR_RESOURCES.md create mode 100644 admin/README.md create mode 100644 admin/REGISTRATION-QUICKSTART.md create mode 100644 admin/classroom admin access.md create mode 100644 admin/classroom/README.md create mode 100644 admin/classroom/autograding-setup.md create mode 100644 admin/classroom/day1-assignment-copy-paste.md create mode 100644 admin/classroom/day2-assignment-copy-paste.md create mode 100644 admin/classroom/live-facilitation-flow.md create mode 100644 admin/classroom/seeding-ops.md create mode 100644 build-rss-feed.bat rename .github/ISSUE_TEMPLATES/ASSIGNMENT_ISSUE_TEMPLATE.md => classroom/assignment-issue-template.md (56%) create mode 100644 docs/get-going.md delete mode 100644 facilitator/FACILITATOR_GUIDE.md create mode 100644 generate-audio.bat create mode 100644 generate-transcripts.bat delete mode 100644 html/ACCESSIBILITY_TESTING.html create mode 100644 html/BATCH.html delete mode 100644 html/COMPREHENSIVE_VALIDATION_AUDIT.html delete mode 100644 html/DAY1_AGENDA.html delete mode 100644 html/DAY2_AGENDA.html delete mode 100644 html/FACILITATOR.html delete mode 100644 html/FACILITATOR_ASSESSMENT.html delete mode 100644 html/FAQ.html delete mode 100644 html/GITHUB_PROPOSAL.html create mode 100644 html/GO-LIVE-QA-GUIDE.html delete mode 100644 html/PODCASTS.html delete mode 100644 html/PROGRESS_TRACKER.html delete mode 100644 html/QUICK_REFERENCE.html delete mode 100644 html/REGISTRATION-ADMIN.html delete mode 100644 html/TROUBLESHOOTING.html create mode 100644 html/admin/FACILITATOR_CLASSROOM_TROUBLESHOOTING.html create mode 100644 html/admin/FACILITATOR_OPERATIONS.html create mode 100644 html/admin/FACILITATOR_RESOURCES.html create mode 100644 html/admin/REGISTRATION-QUICKSTART.html create mode 100644 html/admin/classroom admin access.html create mode 100644 html/admin/classroom/autograding-setup.html create mode 100644 html/admin/classroom/day1-assignment-copy-paste.html create mode 100644 html/admin/classroom/day2-assignment-copy-paste.html create mode 100644 html/admin/classroom/index.html create mode 100644 html/admin/classroom/live-facilitation-flow.html create mode 100644 html/admin/classroom/seeding-ops.html create mode 100644 html/admin/index.html create mode 100644 html/classroom/assignment-issue-template.html delete mode 100644 html/docs/01-understanding-github-web-structure.html delete mode 100644 html/docs/02-navigating-repositories.html delete mode 100644 html/docs/03-the-learning-room.html delete mode 100644 html/docs/04-working-with-issues.html delete mode 100644 html/docs/05-vscode-accessibility.html delete mode 100644 html/docs/05-working-with-pull-requests.html delete mode 100644 html/docs/06-merge-conflicts.html delete mode 100644 html/docs/07-culture-etiquette.html delete mode 100644 html/docs/08-culture-etiquette.html delete mode 100644 html/docs/08-labels-milestones-projects.html delete mode 100644 html/docs/09-notifications.html delete mode 100644 html/docs/10-notifications.html delete mode 100644 html/docs/10-vscode-basics.html delete mode 100644 html/docs/11-git-source-control.html delete mode 100644 html/docs/12-github-pull-requests-extension.html delete mode 100644 html/docs/13-github-copilot.html delete mode 100644 html/docs/14-accessible-code-review.html delete mode 100644 html/docs/15-issue-templates.html delete mode 100644 html/docs/16-accessibility-agents.html delete mode 100644 html/docs/appendix-aa-advanced-git.html delete mode 100644 html/docs/appendix-ab-github-desktop.html delete mode 100644 html/docs/appendix-ac-github-cli.html delete mode 100644 html/docs/appendix-ad-git-security.html delete mode 100644 html/docs/appendix-ae-github-social.html delete mode 100644 html/docs/appendix-c-accessibility-standards.html delete mode 100644 html/docs/appendix-e-github-flavored-markdown.html delete mode 100644 html/docs/appendix-f-github-gists.html delete mode 100644 html/docs/appendix-g-github-discussions.html delete mode 100644 html/docs/appendix-h-releases-tags-insights.html delete mode 100644 html/docs/appendix-i-github-projects.html delete mode 100644 html/docs/appendix-j-advanced-search.html delete mode 100644 html/docs/appendix-k-branch-protection-rulesets.html delete mode 100644 html/docs/appendix-l-github-security-features.html delete mode 100644 html/docs/appendix-m-vscode-accessibility-reference.html delete mode 100644 html/docs/appendix-n-github-codespaces.html delete mode 100644 html/docs/appendix-o-github-mobile.html delete mode 100644 html/docs/appendix-p-github-pages.html delete mode 100644 html/docs/appendix-q-github-actions-workflows.html delete mode 100644 html/docs/appendix-r-github-profile-sponsors-wikis.html delete mode 100644 html/docs/appendix-s-github-organizations-templates.html delete mode 100644 html/docs/appendix-t-contributing-to-open-source.html delete mode 100644 html/docs/appendix-u-resources.html delete mode 100644 html/docs/appendix-v-accessibility-agents-reference.html delete mode 100644 html/docs/appendix-w-github-copilot-reference.html delete mode 100644 html/docs/appendix-x-copilot-models.html delete mode 100644 html/docs/appendix-y-accessing-workshop-materials.html delete mode 100644 html/docs/appendix-z-github-skills-catalog.html create mode 100644 html/docs/get-going.html delete mode 100644 html/facilitator/FACILITATOR_GUIDE.html delete mode 100644 html/index.html delete mode 100644 html/learning-room/docs/CHALLENGES.html create mode 100644 html/learning-room/docs/course-roadmap.html create mode 100644 html/learning-room/docs/skills-bonus-scenarios.html create mode 100644 html/learning-room/docs/solutions/index.html create mode 100644 html/podcasts/REGENERATION.html delete mode 100644 html/podcasts/bundles/ep00-welcome.html delete mode 100644 html/podcasts/bundles/ep01-pre-workshop-setup.html delete mode 100644 html/podcasts/bundles/ep02-github-web-structure.html delete mode 100644 html/podcasts/bundles/ep03-navigating-repositories.html delete mode 100644 html/podcasts/bundles/ep04-the-learning-room.html delete mode 100644 html/podcasts/bundles/ep05-working-with-issues.html delete mode 100644 html/podcasts/bundles/ep06-working-with-pull-requests.html delete mode 100644 html/podcasts/bundles/ep07-merge-conflicts.html delete mode 100644 html/podcasts/bundles/ep08-culture-and-etiquette.html delete mode 100644 html/podcasts/bundles/ep09-labels-milestones-projects.html delete mode 100644 html/podcasts/bundles/ep10-notifications.html delete mode 100644 html/podcasts/bundles/ep11-vscode-basics.html delete mode 100644 html/podcasts/bundles/ep12-git-source-control.html delete mode 100644 html/podcasts/bundles/ep13-github-prs-extension.html delete mode 100644 html/podcasts/bundles/ep14-github-copilot.html delete mode 100644 html/podcasts/bundles/ep15-accessible-code-review.html delete mode 100644 html/podcasts/bundles/ep16-issue-templates.html delete mode 100644 html/podcasts/bundles/ep17-accessibility-agents.html delete mode 100644 html/podcasts/bundles/ep18-glossary.html delete mode 100644 html/podcasts/bundles/ep19-screen-reader-cheatsheet.html delete mode 100644 html/podcasts/bundles/ep20-accessibility-standards.html delete mode 100644 html/podcasts/bundles/ep21-git-authentication.html delete mode 100644 html/podcasts/bundles/ep22-github-flavored-markdown.html delete mode 100644 html/podcasts/bundles/ep23-github-gists.html delete mode 100644 html/podcasts/bundles/ep24-github-discussions.html delete mode 100644 html/podcasts/bundles/ep25-releases-tags-insights.html delete mode 100644 html/podcasts/bundles/ep26-github-projects.html delete mode 100644 html/podcasts/bundles/ep27-advanced-search.html delete mode 100644 html/podcasts/bundles/ep28-branch-protection.html delete mode 100644 html/podcasts/bundles/ep29-security-features.html delete mode 100644 html/podcasts/bundles/ep30-vscode-accessibility-reference.html delete mode 100644 html/podcasts/bundles/ep31-github-codespaces.html delete mode 100644 html/podcasts/bundles/ep32-github-mobile.html delete mode 100644 html/podcasts/bundles/ep33-github-pages.html delete mode 100644 html/podcasts/bundles/ep34-github-actions.html delete mode 100644 html/podcasts/bundles/ep35-profile-sponsors-wikis.html delete mode 100644 html/podcasts/bundles/ep36-organizations-templates.html delete mode 100644 html/podcasts/bundles/ep37-contributing-to-open-source.html delete mode 100644 html/podcasts/bundles/ep38-resources.html delete mode 100644 html/podcasts/bundles/ep39-accessibility-agents-reference.html delete mode 100644 html/podcasts/bundles/ep40-copilot-reference.html delete mode 100644 html/podcasts/bundles/ep41-copilot-models.html delete mode 100644 html/podcasts/bundles/ep42-accessing-workshop-materials.html delete mode 100644 html/podcasts/bundles/ep43-github-skills-catalog.html create mode 100644 html/podcasts/tts/index.html create mode 100644 html/scripts/vibevoice/index.html delete mode 100644 html/wxpython-specialist-original.html create mode 100644 podcasts/REGENERATION.md create mode 100644 podcasts/build-challenge-bundles.js delete mode 100644 podcasts/bundles/ep00-welcome.md delete mode 100644 podcasts/bundles/ep01-pre-workshop-setup.md delete mode 100644 podcasts/bundles/ep02-github-web-structure.md delete mode 100644 podcasts/bundles/ep03-navigating-repositories.md delete mode 100644 podcasts/bundles/ep04-the-learning-room.md delete mode 100644 podcasts/bundles/ep05-working-with-issues.md delete mode 100644 podcasts/bundles/ep06-working-with-pull-requests.md delete mode 100644 podcasts/bundles/ep07-merge-conflicts.md delete mode 100644 podcasts/bundles/ep08-culture-and-etiquette.md delete mode 100644 podcasts/bundles/ep09-labels-milestones-projects.md delete mode 100644 podcasts/bundles/ep10-notifications.md delete mode 100644 podcasts/bundles/ep11-vscode-basics.md delete mode 100644 podcasts/bundles/ep12-git-source-control.md delete mode 100644 podcasts/bundles/ep13-github-prs-extension.md delete mode 100644 podcasts/bundles/ep14-github-copilot.md delete mode 100644 podcasts/bundles/ep15-accessible-code-review.md delete mode 100644 podcasts/bundles/ep16-issue-templates.md delete mode 100644 podcasts/bundles/ep17-accessibility-agents.md delete mode 100644 podcasts/bundles/ep18-glossary.md delete mode 100644 podcasts/bundles/ep19-screen-reader-cheatsheet.md delete mode 100644 podcasts/bundles/ep20-accessibility-standards.md delete mode 100644 podcasts/bundles/ep21-git-authentication.md delete mode 100644 podcasts/bundles/ep22-github-flavored-markdown.md delete mode 100644 podcasts/bundles/ep23-github-gists.md delete mode 100644 podcasts/bundles/ep24-github-discussions.md delete mode 100644 podcasts/bundles/ep25-releases-tags-insights.md delete mode 100644 podcasts/bundles/ep26-github-projects.md delete mode 100644 podcasts/bundles/ep27-advanced-search.md delete mode 100644 podcasts/bundles/ep28-branch-protection.md delete mode 100644 podcasts/bundles/ep29-security-features.md delete mode 100644 podcasts/bundles/ep30-vscode-accessibility-reference.md delete mode 100644 podcasts/bundles/ep31-github-codespaces.md delete mode 100644 podcasts/bundles/ep32-github-mobile.md delete mode 100644 podcasts/bundles/ep33-github-pages.md delete mode 100644 podcasts/bundles/ep34-github-actions.md delete mode 100644 podcasts/bundles/ep35-profile-sponsors-wikis.md delete mode 100644 podcasts/bundles/ep36-organizations-templates.md delete mode 100644 podcasts/bundles/ep37-contributing-to-open-source.md delete mode 100644 podcasts/bundles/ep38-resources.md delete mode 100644 podcasts/bundles/ep39-accessibility-agents-reference.md delete mode 100644 podcasts/bundles/ep40-copilot-reference.md delete mode 100644 podcasts/bundles/ep41-copilot-models.md delete mode 100644 podcasts/bundles/ep42-accessing-workshop-materials.md delete mode 100644 podcasts/bundles/ep43-github-skills-catalog.md create mode 100644 podcasts/generate-draft-transcripts-extraction.js create mode 100644 podcasts/generate-draft-transcripts-old.js create mode 100644 podcasts/generate-draft-transcripts.js create mode 100644 podcasts/listening-order.json create mode 100644 podcasts/logs/audio_inventory_report.json create mode 100644 podcasts/logs/kokoro_samples.log create mode 100644 podcasts/logs/kokoro_voice_manifest.json create mode 100644 podcasts/logs/kokoro_voices_all.txt create mode 100644 podcasts/logs/kokoro_voices_english_high_quality.txt create mode 100644 podcasts/logs/piper_samples.log create mode 100644 podcasts/logs/piper_voices_current.txt create mode 100644 podcasts/reorganize_scripts_and_transcripts.py create mode 100644 podcasts/scripts/appendices/ep18-glossary.txt create mode 100644 podcasts/scripts/appendices/ep19-screen-reader-cheatsheet.txt create mode 100644 podcasts/scripts/appendices/ep20-accessibility-standards.txt create mode 100644 podcasts/scripts/appendices/ep21-git-authentication.txt create mode 100644 podcasts/scripts/appendices/ep22-github-flavored-markdown.txt create mode 100644 podcasts/scripts/appendices/ep23-github-gists.txt create mode 100644 podcasts/scripts/appendices/ep24-github-discussions.txt create mode 100644 podcasts/scripts/appendices/ep25-releases-tags-insights.txt create mode 100644 podcasts/scripts/appendices/ep26-github-projects.txt create mode 100644 podcasts/scripts/appendices/ep27-advanced-search.txt create mode 100644 podcasts/scripts/appendices/ep28-branch-protection.txt create mode 100644 podcasts/scripts/appendices/ep29-security-features.txt create mode 100644 podcasts/scripts/appendices/ep30-vscode-accessibility-reference.txt create mode 100644 podcasts/scripts/appendices/ep31-github-codespaces.txt create mode 100644 podcasts/scripts/appendices/ep32-github-mobile.txt create mode 100644 podcasts/scripts/appendices/ep33-github-pages.txt create mode 100644 podcasts/scripts/appendices/ep34-github-actions.txt create mode 100644 podcasts/scripts/appendices/ep35-profile-sponsors-wikis.txt create mode 100644 podcasts/scripts/appendices/ep36-organizations-templates.txt create mode 100644 podcasts/scripts/appendices/ep38-resources.txt create mode 100644 podcasts/scripts/appendices/ep39-accessibility-agents-reference.txt create mode 100644 podcasts/scripts/appendices/ep40-copilot-reference.txt create mode 100644 podcasts/scripts/appendices/ep41-copilot-models.txt create mode 100644 podcasts/scripts/appendices/ep42-accessing-workshop-materials.txt create mode 100644 podcasts/scripts/appendices/ep43-github-skills-catalog.txt create mode 100644 podcasts/scripts/appendices/ep50-advanced-git-operations.txt create mode 100644 podcasts/scripts/appendices/ep51-git-security-for-contributors.txt create mode 100644 podcasts/scripts/appendices/ep52-github-desktop.txt create mode 100644 podcasts/scripts/appendices/ep53-github-cli-reference.txt create mode 100644 podcasts/scripts/challenges/cc-01-find-your-way-around.txt create mode 100644 podcasts/scripts/challenges/cc-02-file-your-first-issue.txt create mode 100644 podcasts/scripts/challenges/cc-03-join-the-conversation.txt create mode 100644 podcasts/scripts/challenges/cc-04-branch-out.txt create mode 100644 podcasts/scripts/challenges/cc-05-make-your-mark.txt create mode 100644 podcasts/scripts/challenges/cc-06-open-your-first-pr.txt create mode 100644 podcasts/scripts/challenges/cc-07-survive-a-merge-conflict.txt create mode 100644 podcasts/scripts/challenges/cc-08-open-source-culture.txt create mode 100644 podcasts/scripts/challenges/cc-09-merge-day.txt create mode 100644 podcasts/scripts/challenges/cc-10-go-local.txt create mode 100644 podcasts/scripts/challenges/cc-11-day-2-pull-request.txt create mode 100644 podcasts/scripts/challenges/cc-12-code-review.txt create mode 100644 podcasts/scripts/challenges/cc-13-copilot-as-collaborator.txt create mode 100644 podcasts/scripts/challenges/cc-14-design-an-issue-template.txt create mode 100644 podcasts/scripts/challenges/cc-15-discover-accessibility-agents.txt create mode 100644 podcasts/scripts/challenges/cc-16-build-your-own-agent.txt create mode 100644 podcasts/scripts/challenges/cc-bonus-a-improve-agent.txt create mode 100644 podcasts/scripts/challenges/cc-bonus-b-document-your-journey.txt create mode 100644 podcasts/scripts/challenges/cc-bonus-c-group-challenge.txt create mode 100644 podcasts/scripts/challenges/cc-bonus-d-notifications.txt create mode 100644 podcasts/scripts/challenges/cc-bonus-e-git-history.txt create mode 100644 podcasts/scripts/chapters/ep00-welcome.txt create mode 100644 podcasts/scripts/chapters/ep01-pre-workshop-setup.txt create mode 100644 podcasts/scripts/chapters/ep02-github-web-structure.txt create mode 100644 podcasts/scripts/chapters/ep03-navigating-repositories.txt create mode 100644 podcasts/scripts/chapters/ep04-the-learning-room.txt create mode 100644 podcasts/scripts/chapters/ep05-working-with-issues.txt create mode 100644 podcasts/scripts/chapters/ep06-working-with-pull-requests.txt create mode 100644 podcasts/scripts/chapters/ep07-merge-conflicts.txt create mode 100644 podcasts/scripts/chapters/ep08-culture-and-etiquette.txt create mode 100644 podcasts/scripts/chapters/ep09-labels-milestones-projects.txt create mode 100644 podcasts/scripts/chapters/ep10-notifications.txt create mode 100644 podcasts/scripts/chapters/ep11-vscode-basics.txt create mode 100644 podcasts/scripts/chapters/ep12-git-source-control.txt create mode 100644 podcasts/scripts/chapters/ep13-github-prs-extension.txt create mode 100644 podcasts/scripts/chapters/ep14-github-copilot.txt create mode 100644 podcasts/scripts/chapters/ep15-accessible-code-review.txt create mode 100644 podcasts/scripts/chapters/ep16-issue-templates.txt create mode 100644 podcasts/scripts/chapters/ep17-accessibility-agents.txt create mode 100644 podcasts/scripts/chapters/ep37-contributing-to-open-source.txt create mode 100644 podcasts/scripts/chapters/ep44-choose-your-tools.txt create mode 100644 podcasts/scripts/chapters/ep45-vscode-accessibility-deep-dive.txt create mode 100644 podcasts/scripts/chapters/ep46-how-git-works.txt create mode 100644 podcasts/scripts/chapters/ep47-fork-and-contribute.txt create mode 100644 podcasts/scripts/chapters/ep48-build-your-agent-capstone.txt create mode 100644 podcasts/scripts/chapters/ep49-next-steps.txt delete mode 100644 podcasts/scripts/ep00-welcome.txt delete mode 100644 podcasts/scripts/ep01-pre-workshop-setup.txt delete mode 100644 podcasts/scripts/ep02-github-web-structure.txt delete mode 100644 podcasts/scripts/ep03-navigating-repositories.txt delete mode 100644 podcasts/scripts/ep04-the-learning-room.txt delete mode 100644 podcasts/scripts/ep05-working-with-issues.txt delete mode 100644 podcasts/scripts/ep06-working-with-pull-requests.txt delete mode 100644 podcasts/scripts/ep07-merge-conflicts.txt delete mode 100644 podcasts/scripts/ep08-culture-and-etiquette.txt delete mode 100644 podcasts/scripts/ep09-labels-milestones-projects.txt delete mode 100644 podcasts/scripts/ep10-notifications.txt delete mode 100644 podcasts/scripts/ep11-vscode-basics.txt delete mode 100644 podcasts/scripts/ep12-git-source-control.txt delete mode 100644 podcasts/scripts/ep13-github-prs-extension.txt delete mode 100644 podcasts/scripts/ep14-github-copilot.txt delete mode 100644 podcasts/scripts/ep15-accessible-code-review.txt delete mode 100644 podcasts/scripts/ep16-issue-templates.txt delete mode 100644 podcasts/scripts/ep17-accessibility-agents.txt delete mode 100644 podcasts/scripts/ep18-glossary.txt delete mode 100644 podcasts/scripts/ep19-screen-reader-cheatsheet.txt delete mode 100644 podcasts/scripts/ep20-accessibility-standards.txt delete mode 100644 podcasts/scripts/ep21-git-authentication.txt delete mode 100644 podcasts/scripts/ep22-github-flavored-markdown.txt delete mode 100644 podcasts/scripts/ep23-github-gists.txt delete mode 100644 podcasts/scripts/ep24-github-discussions.txt delete mode 100644 podcasts/scripts/ep25-releases-tags-insights.txt delete mode 100644 podcasts/scripts/ep26-github-projects.txt delete mode 100644 podcasts/scripts/ep27-advanced-search.txt delete mode 100644 podcasts/scripts/ep28-branch-protection.txt delete mode 100644 podcasts/scripts/ep29-security-features.txt delete mode 100644 podcasts/scripts/ep30-vscode-accessibility-reference.txt delete mode 100644 podcasts/scripts/ep31-github-codespaces.txt delete mode 100644 podcasts/scripts/ep32-github-mobile.txt delete mode 100644 podcasts/scripts/ep33-github-pages.txt delete mode 100644 podcasts/scripts/ep34-github-actions.txt delete mode 100644 podcasts/scripts/ep35-profile-sponsors-wikis.txt delete mode 100644 podcasts/scripts/ep36-organizations-templates.txt delete mode 100644 podcasts/scripts/ep37-contributing-to-open-source.txt delete mode 100644 podcasts/scripts/ep38-resources.txt delete mode 100644 podcasts/scripts/ep39-accessibility-agents-reference.txt delete mode 100644 podcasts/scripts/ep40-copilot-reference.txt delete mode 100644 podcasts/scripts/ep41-copilot-models.txt delete mode 100644 podcasts/scripts/ep42-accessing-workshop-materials.txt delete mode 100644 podcasts/scripts/ep43-github-skills-catalog.txt create mode 100644 podcasts/tag-audio-metadata.py create mode 100644 podcasts/transcripts/appendices/ep18-glossary-segments.json create mode 100644 podcasts/transcripts/appendices/ep19-screen-reader-cheatsheet-segments.json create mode 100644 podcasts/transcripts/appendices/ep20-accessibility-standards-segments.json create mode 100644 podcasts/transcripts/appendices/ep21-git-authentication-segments.json create mode 100644 podcasts/transcripts/appendices/ep22-github-flavored-markdown-segments.json create mode 100644 podcasts/transcripts/appendices/ep23-github-gists-segments.json create mode 100644 podcasts/transcripts/appendices/ep24-github-discussions-segments.json create mode 100644 podcasts/transcripts/appendices/ep25-releases-tags-insights-segments.json create mode 100644 podcasts/transcripts/appendices/ep26-github-projects-segments.json create mode 100644 podcasts/transcripts/appendices/ep27-advanced-search-segments.json create mode 100644 podcasts/transcripts/appendices/ep28-branch-protection-segments.json create mode 100644 podcasts/transcripts/appendices/ep29-security-features-segments.json create mode 100644 podcasts/transcripts/appendices/ep30-vscode-accessibility-reference-segments.json create mode 100644 podcasts/transcripts/appendices/ep31-github-codespaces-segments.json create mode 100644 podcasts/transcripts/appendices/ep32-github-mobile-segments.json create mode 100644 podcasts/transcripts/appendices/ep33-github-pages-segments.json create mode 100644 podcasts/transcripts/appendices/ep34-github-actions-segments.json create mode 100644 podcasts/transcripts/appendices/ep35-profile-sponsors-wikis-segments.json create mode 100644 podcasts/transcripts/appendices/ep36-organizations-templates-segments.json create mode 100644 podcasts/transcripts/appendices/ep38-resources-segments.json create mode 100644 podcasts/transcripts/appendices/ep39-accessibility-agents-reference-segments.json create mode 100644 podcasts/transcripts/appendices/ep40-copilot-reference-segments.json create mode 100644 podcasts/transcripts/appendices/ep41-copilot-models-segments.json create mode 100644 podcasts/transcripts/appendices/ep42-accessing-workshop-materials-segments.json create mode 100644 podcasts/transcripts/appendices/ep43-github-skills-catalog-segments.json create mode 100644 podcasts/transcripts/appendices/ep50-advanced-git-operations-segments.json create mode 100644 podcasts/transcripts/appendices/ep51-git-security-for-contributors-segments.json create mode 100644 podcasts/transcripts/appendices/ep52-github-desktop-segments.json create mode 100644 podcasts/transcripts/appendices/ep53-github-cli-reference-segments.json create mode 100644 podcasts/transcripts/challenges/cc-01-find-your-way-around-segments.json create mode 100644 podcasts/transcripts/challenges/cc-02-file-your-first-issue-segments.json create mode 100644 podcasts/transcripts/challenges/cc-03-join-the-conversation-segments.json create mode 100644 podcasts/transcripts/challenges/cc-04-branch-out-segments.json create mode 100644 podcasts/transcripts/challenges/cc-05-make-your-mark-segments.json create mode 100644 podcasts/transcripts/challenges/cc-06-open-your-first-pr-segments.json create mode 100644 podcasts/transcripts/challenges/cc-07-survive-a-merge-conflict-segments.json create mode 100644 podcasts/transcripts/challenges/cc-08-open-source-culture-segments.json create mode 100644 podcasts/transcripts/challenges/cc-09-merge-day-segments.json create mode 100644 podcasts/transcripts/challenges/cc-10-go-local-segments.json create mode 100644 podcasts/transcripts/challenges/cc-11-day-2-pull-request-segments.json create mode 100644 podcasts/transcripts/challenges/cc-12-code-review-segments.json create mode 100644 podcasts/transcripts/challenges/cc-13-copilot-as-collaborator-segments.json create mode 100644 podcasts/transcripts/challenges/cc-14-design-an-issue-template-segments.json create mode 100644 podcasts/transcripts/challenges/cc-15-discover-accessibility-agents-segments.json create mode 100644 podcasts/transcripts/challenges/cc-16-build-your-own-agent-segments.json create mode 100644 podcasts/transcripts/challenges/cc-bonus-a-improve-agent-segments.json create mode 100644 podcasts/transcripts/challenges/cc-bonus-b-document-your-journey-segments.json create mode 100644 podcasts/transcripts/challenges/cc-bonus-c-group-challenge-segments.json create mode 100644 podcasts/transcripts/challenges/cc-bonus-d-notifications-segments.json create mode 100644 podcasts/transcripts/challenges/cc-bonus-e-git-history-segments.json create mode 100644 podcasts/transcripts/chapters/ep00-welcome-segments.json create mode 100644 podcasts/transcripts/chapters/ep01-pre-workshop-setup-segments.json create mode 100644 podcasts/transcripts/chapters/ep02-github-web-structure-segments.json create mode 100644 podcasts/transcripts/chapters/ep03-navigating-repositories-segments.json create mode 100644 podcasts/transcripts/chapters/ep04-the-learning-room-segments.json create mode 100644 podcasts/transcripts/chapters/ep05-working-with-issues-segments.json create mode 100644 podcasts/transcripts/chapters/ep06-working-with-pull-requests-segments.json create mode 100644 podcasts/transcripts/chapters/ep07-merge-conflicts-segments.json create mode 100644 podcasts/transcripts/chapters/ep08-culture-and-etiquette-segments.json create mode 100644 podcasts/transcripts/chapters/ep09-labels-milestones-projects-segments.json create mode 100644 podcasts/transcripts/chapters/ep10-notifications-segments.json create mode 100644 podcasts/transcripts/chapters/ep11-vscode-basics-segments.json create mode 100644 podcasts/transcripts/chapters/ep12-git-source-control-segments.json create mode 100644 podcasts/transcripts/chapters/ep13-github-prs-extension-segments.json create mode 100644 podcasts/transcripts/chapters/ep14-github-copilot-segments.json create mode 100644 podcasts/transcripts/chapters/ep15-accessible-code-review-segments.json create mode 100644 podcasts/transcripts/chapters/ep16-issue-templates-segments.json create mode 100644 podcasts/transcripts/chapters/ep17-accessibility-agents-segments.json create mode 100644 podcasts/transcripts/chapters/ep37-contributing-to-open-source-segments.json create mode 100644 podcasts/transcripts/chapters/ep44-choose-your-tools-segments.json create mode 100644 podcasts/transcripts/chapters/ep45-vscode-accessibility-deep-dive-segments.json create mode 100644 podcasts/transcripts/chapters/ep46-how-git-works-segments.json create mode 100644 podcasts/transcripts/chapters/ep47-fork-and-contribute-segments.json create mode 100644 podcasts/transcripts/chapters/ep48-build-your-agent-capstone-segments.json create mode 100644 podcasts/transcripts/chapters/ep49-next-steps-segments.json delete mode 100644 podcasts/transcripts/ep00-welcome-segments.json delete mode 100644 podcasts/transcripts/ep01-pre-workshop-setup-segments.json delete mode 100644 podcasts/transcripts/ep02-github-web-structure-segments.json delete mode 100644 podcasts/transcripts/ep03-navigating-repositories-segments.json delete mode 100644 podcasts/transcripts/ep04-the-learning-room-segments.json delete mode 100644 podcasts/transcripts/ep05-working-with-issues-segments.json delete mode 100644 podcasts/transcripts/ep06-working-with-pull-requests-segments.json delete mode 100644 podcasts/transcripts/ep07-merge-conflicts-segments.json delete mode 100644 podcasts/transcripts/ep08-culture-and-etiquette-segments.json delete mode 100644 podcasts/transcripts/ep09-labels-milestones-projects-segments.json delete mode 100644 podcasts/transcripts/ep10-notifications-segments.json delete mode 100644 podcasts/transcripts/ep11-vscode-basics-segments.json delete mode 100644 podcasts/transcripts/ep12-git-source-control-segments.json delete mode 100644 podcasts/transcripts/ep13-github-prs-extension-segments.json delete mode 100644 podcasts/transcripts/ep14-github-copilot-segments.json delete mode 100644 podcasts/transcripts/ep15-accessible-code-review-segments.json delete mode 100644 podcasts/transcripts/ep16-issue-templates-segments.json delete mode 100644 podcasts/transcripts/ep17-accessibility-agents-segments.json delete mode 100644 podcasts/transcripts/ep18-glossary-segments.json delete mode 100644 podcasts/transcripts/ep19-screen-reader-cheatsheet-segments.json delete mode 100644 podcasts/transcripts/ep20-accessibility-standards-segments.json delete mode 100644 podcasts/transcripts/ep21-git-authentication-segments.json delete mode 100644 podcasts/transcripts/ep22-github-flavored-markdown-segments.json delete mode 100644 podcasts/transcripts/ep23-github-gists-segments.json delete mode 100644 podcasts/transcripts/ep24-github-discussions-segments.json delete mode 100644 podcasts/transcripts/ep25-releases-tags-insights-segments.json delete mode 100644 podcasts/transcripts/ep26-github-projects-segments.json delete mode 100644 podcasts/transcripts/ep27-advanced-search-segments.json delete mode 100644 podcasts/transcripts/ep28-branch-protection-segments.json delete mode 100644 podcasts/transcripts/ep29-security-features-segments.json delete mode 100644 podcasts/transcripts/ep30-vscode-accessibility-reference-segments.json delete mode 100644 podcasts/transcripts/ep31-github-codespaces-segments.json delete mode 100644 podcasts/transcripts/ep32-github-mobile-segments.json delete mode 100644 podcasts/transcripts/ep33-github-pages-segments.json delete mode 100644 podcasts/transcripts/ep34-github-actions-segments.json delete mode 100644 podcasts/transcripts/ep35-profile-sponsors-wikis-segments.json delete mode 100644 podcasts/transcripts/ep36-organizations-templates-segments.json delete mode 100644 podcasts/transcripts/ep37-contributing-to-open-source-segments.json delete mode 100644 podcasts/transcripts/ep38-resources-segments.json delete mode 100644 podcasts/transcripts/ep39-accessibility-agents-reference-segments.json delete mode 100644 podcasts/transcripts/ep40-copilot-reference-segments.json delete mode 100644 podcasts/transcripts/ep41-copilot-models-segments.json delete mode 100644 podcasts/transcripts/ep42-accessing-workshop-materials-segments.json delete mode 100644 podcasts/transcripts/ep43-github-skills-catalog-segments.json create mode 100644 podcasts/tts/README.md create mode 100644 podcasts/tts/download_kokoro_samples.py create mode 100644 podcasts/tts/generate_all_kokoro.py create mode 100644 podcasts/tts/voice-config.ini create mode 100644 podcasts/validate-catalog.js create mode 100644 podcasts/validate-feed.js create mode 100644 podcasts/verify_audio_inventory.py create mode 100644 scripts/build-podcasts.ps1 create mode 100644 scripts/vibevoice/README.md create mode 100644 scripts/vibevoice/generate-voice-samples.bat create mode 100644 scripts/vibevoice/generate-voice-samples.py create mode 100644 scripts/vibevoice/setup-vibevoice.bat create mode 100644 validate-rss-feed.bat diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..426a30e --- /dev/null +++ b/.gitattributes @@ -0,0 +1,40 @@ +# Normalize line endings to LF for all text files. +# This overrides core.autocrlf for all contributors regardless of OS. + +# Default: auto-detect text files and normalize to LF +* text=auto eol=lf + +# Explicitly mark common text formats as LF +*.md text eol=lf +*.html text eol=lf +*.htm text eol=lf +*.css text eol=lf +*.js text eol=lf +*.mjs text eol=lf +*.cjs text eol=lf +*.ts text eol=lf +*.json text eol=lf +*.yml text eol=lf +*.yaml text eol=lf +*.xml text eol=lf +*.svg text eol=lf +*.txt text eol=lf +*.sh text eol=lf +*.py text eol=lf +*.bat text eol=crlf + +# Binary files - do not touch line endings +*.png binary +*.jpg binary +*.jpeg binary +*.gif binary +*.webp binary +*.ico binary +*.pdf binary +*.mp3 binary +*.mp4 binary +*.woff binary +*.woff2 binary +*.ttf binary +*.otf binary +*.zip binary diff --git a/.github/ISSUE_TEMPLATE/challenge-hub.md b/.github/ISSUE_TEMPLATE/challenge-hub.md deleted file mode 100644 index b2a7170..0000000 --- a/.github/ISSUE_TEMPLATE/challenge-hub.md +++ /dev/null @@ -1,86 +0,0 @@ -name: "Challenge: {CHAPTER_NAME}" -about: "Chapter {CHAPTER_NUM} Challenge - {CHALLENGE_SUMMARY}" -title: "Chapter {CHAPTER_NUM}.{CHALLENGE_NUM}: {CHALLENGE_TITLE} (@{USERNAME})" -labels: ["challenge", "challenge: {CHALLENGE_DIFFICULTY}", "skill: {SKILL_TAG}", "day: {DAY}"] -assignees: ["{USERNAME}"] - -> [!WARNING] -> This issue is part of the **GIT Going with GitHub** course. -> Do not start this challenge until the course officially begins. - -# Chapter {CHAPTER_NUM}: {CHAPTER_NAME} Challenge - -**Student:** @{USERNAME} -**Estimated Time:** {TIME_ESTIMATE} -**Skill Level:** {CHALLENGE_DIFFICULTY} - - -## Challenge Overview - -{CHALLENGE_OVERVIEW} - -**All challenges in this chapter are linked to the [Challenge Hub](https://github.com/Community-Access/learning-room/blob/main/docs/CHALLENGES.md#chapter-{CHAPTER_NUM}-{ANCHOR_TEXT}) for full context and instructions.** - - -## Your Challenge: {CHALLENGE_TITLE} - -{CHALLENGE_BODY_FROM_HUB} - - -## What You Need to Do - -1. **Complete the challenge** following the instructions in the [Challenge Hub](https://github.com/Community-Access/learning-room/blob/main/docs/CHALLENGES.md#chapter-{CHAPTER_NUM}-{ANCHOR_TEXT}) -2. **Open a pull request** that references this issue: `Closes #{ISSUE_NUMBER}` -3. **Submit your work** - your PR should include proof of completion -4. **See your issue close** automatically when your PR merges - - -## How to Submit - -### Step 1: Claim This Issue -Reply with a comment: `I'm working on this!` - -### Step 2: Create Your Branch -```bash -git checkout -b chapter-{CHAPTER_NUM}-challenge-{USERNAME} -``` - -### Step 3: Complete the Challenge -Follow the detailed steps in the [Challenge Hub](https://github.com/Community-Access/learning-room/blob/main/docs/CHALLENGES.md#chapter-{CHAPTER_NUM}-{ANCHOR_TEXT}). - -{CHALLENGE_SPECIFIC_STEPS} - -### Step 4: Open a Pull Request -When ready: -```bash -git push origin chapter-{CHAPTER_NUM}-challenge-{USERNAME} -``` - -Then open a PR with: -- **Title:** `Chapter {CHAPTER_NUM}: {CHALLENGE_TITLE}` -- **Description:** Include `Closes #{ISSUE_NUMBER}` and add evidence of your work -- **Evidence:** Screenshots, links to created issues, or proof of completion per the Challenge Hub - -### Step 5: Watch for Validation -{VALIDATION_TEXT} - - -## Expected Outcomes - -{EXPECTED_OUTCOMES} - - -## If You Get Stuck - -1. **Re-read the [Challenge Hub](https://github.com/Community-Access/learning-room/blob/main/docs/CHALLENGES.md#chapter-{CHAPTER_NUM}-{ANCHOR_TEXT})** - it has detailed step-by-step instructions -2. **Check the [Screen Reader Cheat Sheet](https://github.com/Community-Access/git-going-with-github/blob/main/docs/appendix-b-screen-reader-cheatsheet.md)** - keyboard commands for navigation -3. **Watch the [Chapter {CHAPTER_NUM} walkthrough](https://github.com/Community-Access/git-going-with-github/blob/main/PODCASTS.md)** - audio explanation of the concepts -4. **Ask in Slack** - tag @facilitator with `#help` and your challenge number -5. **Comment on this issue** - describe what's blocking you; facilitator will help - - -## Learning Moment - -{LEARNING_MOMENT} - -**Next Step:** Check out [Challenge Hub](https://github.com/Community-Access/learning-room/blob/main/docs/CHALLENGES.md) for the next challenge or chapter! diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index fc00061..08d72ae 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,8 +1,8 @@ blank_issues_enabled: true contact_links: - - name: "Register for GIT Going with GitHub (May 21-22, 2026)" - url: https://community-access.github.io/git-going-with-github/REGISTER.html - about: Two-step registration (GitHub issue + Zoom). Free, online, 75 seats. + - 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). - name: GitHub Skills - Introduction to GitHub url: https://github.com/skills/introduction-to-github about: Interactive module - branches, commits, pull requests, and merge. Mona guides you step by step. diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md deleted file mode 100644 index 6cfe93b..0000000 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ /dev/null @@ -1,50 +0,0 @@ -## Description - -Briefly describe what you changed and why. What problem does this solve or what feature does it add? - -## Type of Change - -- [ ] Bug fix (fixes an issue without changing existing functionality) -- [ ] Documentation improvement (adds or updates documentation) -- [ ] Accessibility improvement (improves accessibility) -- [ ] Enhancement (adds new feature or improves existing feature) -- [ ] Other (describe below) - -## Related Issues - -Closes #[issue number] - -## Changes Made - -List the specific changes you made to the repository: - -- [ ] Change 1 -- [ ] Change 2 -- [ ] Change 3 - -## How to Test This - -If applicable, describe how reviewers can test your changes: - -1. Step 1 -2. Step 2 -3. Verify that X happens - -## Checklist - -- [ ] My changes follow the contribution guidelines -- [ ] I have tested my changes locally -- [ ] My changes do not break existing functionality -- [ ] I have read the documentation related to my changes -- [ ] My code has no syntax errors -- [ ] For accessibility improvements: I have tested with a screen reader if applicable -- [ ] For documentation changes: I have read the file aloud with a screen reader to verify it reads clearly - -## Screenshot or Demo - -If applicable, add a screenshot, GIF, or link to a demo showing your changes: - -[Add screenshot or video link here] - - -**Have questions?** Ask in the comments below, or review [Working with Pull Requests](../../docs/05-working-with-pull-requests.md) for guidance. diff --git a/.github/internal/challenge-hub-template.md b/.github/internal/challenge-hub-template.md new file mode 100644 index 0000000..f27dd11 --- /dev/null +++ b/.github/internal/challenge-hub-template.md @@ -0,0 +1,97 @@ +--- +status: reference-only +former_source: .github/ISSUE_TEMPLATE/challenge-hub.md +--- + +# Challenge Issue Template Reference + +This reference template is intentionally stored outside `.github/ISSUE_TEMPLATE/` so GitHub does not present placeholder values to workshop participants. Facilitators can copy it when generating cohort-specific challenge issues. + +## Template + +```markdown +name: "Challenge: {CHAPTER_NAME}" +about: "Chapter {CHAPTER_NUM} Challenge - {CHALLENGE_SUMMARY}" +title: "Chapter {CHAPTER_NUM}.{CHALLENGE_NUM}: {CHALLENGE_TITLE} (@{USERNAME})" +labels: ["challenge", "challenge: {CHALLENGE_DIFFICULTY}", "skill: {SKILL_TAG}", "day: {DAY}"] +assignees: ["{USERNAME}"] + +> [!WARNING] +> This issue is part of the **GIT Going with GitHub** course. +> Do not start this challenge until the course officially begins. + +# Chapter {CHAPTER_NUM}: {CHAPTER_NAME} Challenge + +**Student:** @{USERNAME} +**Estimated Time:** {TIME_ESTIMATE} +**Skill Level:** {CHALLENGE_DIFFICULTY} + +## Challenge Overview + +{CHALLENGE_OVERVIEW} + +**All challenges in this chapter are linked to the [Challenge Hub](https://github.com/Community-Access/git-going-with-github/blob/main/docs/CHALLENGES.md) for full context and instructions.** + +## Your Challenge: {CHALLENGE_TITLE} + +{CHALLENGE_BODY_FROM_HUB} + +## What You Need to Do + +1. **Complete the challenge** following the instructions in the Challenge Hub. +2. **Open a pull request** that references this issue: `Closes #{ISSUE_NUMBER}`. +3. **Submit your work** - your PR should include proof of completion. +4. **See your issue close** automatically when your PR merges. + +## How to Submit + +### Step 1: Claim This Issue + +Reply with a comment: `I'm working on this!` + +### Step 2: Create Your Branch + +```bash +git checkout -b chapter-{CHAPTER_NUM}-challenge-{USERNAME} +``` + +### Step 3: Complete the Challenge + +Follow the detailed steps in the Challenge Hub. + +{CHALLENGE_SPECIFIC_STEPS} + +### Step 4: Open a Pull Request + +When ready: + +```bash +git push origin chapter-{CHAPTER_NUM}-challenge-{USERNAME} +``` + +Then open a PR with: + +- **Title:** `Chapter {CHAPTER_NUM}: {CHALLENGE_TITLE}` +- **Description:** Include `Closes #{ISSUE_NUMBER}` and add evidence of your work +- **Evidence:** Links to created issues, pull requests, or proof of completion per the Challenge Hub + +### Step 5: Watch for Validation + +{VALIDATION_TEXT} + +## Expected Outcomes + +{EXPECTED_OUTCOMES} + +## If You Get Stuck + +1. Re-read the Challenge Hub. +2. Check the [Screen Reader Cheat Sheet](https://github.com/Community-Access/git-going-with-github/blob/main/docs/appendix-b-screen-reader-cheatsheet.md). +3. Listen to the companion episode in [PODCASTS.md](https://github.com/Community-Access/git-going-with-github/blob/main/PODCASTS.md). +4. Ask in the workshop help channel with your challenge number. +5. Comment on this issue with what is blocking you. + +## Learning Moment + +{LEARNING_MOMENT} +``` \ No newline at end of file diff --git a/.github/scripts/__tests__/challenge-doc-consistency.test.js b/.github/scripts/__tests__/challenge-doc-consistency.test.js index b45061c..b29bbb2 100644 --- a/.github/scripts/__tests__/challenge-doc-consistency.test.js +++ b/.github/scripts/__tests__/challenge-doc-consistency.test.js @@ -2,18 +2,22 @@ const test = require('node:test'); const assert = require('node:assert/strict'); const fs = require('node:fs'); const path = require('node:path'); +const { challenges } = require('../../../podcasts/build-challenge-bundles'); const repoRoot = path.resolve(__dirname, '../../../'); const templatesDir = path.join(repoRoot, 'learning-room/.github/ISSUE_TEMPLATE'); const challengeHubPath = path.join(repoRoot, 'docs/CHALLENGES.md'); const humanMatrixPath = path.join(repoRoot, 'classroom/HUMAN_TEST_MATRIX.md'); -const facilitatorGuidePath = path.join(repoRoot, 'facilitator/FACILITATOR_GUIDE.md'); +const facilitatorGuidePath = path.join(repoRoot, 'admin/FACILITATOR_GUIDE.md'); const learningRoomSolutionsIndexPath = path.join(repoRoot, 'learning-room/docs/solutions/README.md'); const skillsBonusScenariosPath = path.join(repoRoot, 'learning-room/docs/skills-bonus-scenarios.md'); const learningRoomRoadmapPath = path.join(repoRoot, 'learning-room/docs/course-roadmap.md'); const learningRoomReadmePath = path.join(repoRoot, 'learning-room/README.md'); const studentGuidePath = path.join(repoRoot, 'learning-room/.github/STUDENT_GUIDE.md'); const startHereTemplatePath = path.join(repoRoot, 'learning-room/.github/ISSUE_TEMPLATE/start-here-roadmap.yml'); +const assignmentDay1Path = path.join(repoRoot, 'classroom/assignment-day1-you-belong-here.md'); +const assignmentDay2Path = path.join(repoRoot, 'classroom/assignment-day2-you-can-build-this.md'); +const podcastScriptsDir = path.join(repoRoot, 'podcasts/scripts'); function getChallengeTemplateFiles() { return fs @@ -42,6 +46,11 @@ function getCanonicalChallengeTitles() { function titleVariants(title) { const variants = new Set([title]); + const challengePrefix = title.match(/^Challenge\s+(\d+):\s+(.+)$/i); + if (challengePrefix) { + variants.add(challengePrefix[2]); + variants.add(`${challengePrefix[1]}. ${challengePrefix[2]}`); + } if (/pull request/i.test(title)) { variants.add(title.replace(/pull request/gi, 'PR')); @@ -65,6 +74,64 @@ function assertContainsAnyTitleVariant(targetText, fileName, title, targetLabel) assert.equal(found, true, `${fileName}: title missing from ${targetLabel}`); } +function assertCanonicalTitlesInDocument(documentPath, targetLabel, challengeNumberPattern) { + const content = fs.readFileSync(documentPath, 'utf8'); + const titles = getCanonicalChallengeTitles().filter(({ fileName }) => challengeNumberPattern.test(fileName)); + + titles.forEach(({ fileName, title }) => { + assertContainsAnyTitleVariant(content, fileName, title, targetLabel); + }); +} + +test('classroom assignment docs use canonical challenge titles', () => { + assertCanonicalTitlesInDocument(assignmentDay1Path, 'classroom/assignment-day1-you-belong-here.md', /^challenge-0[1-9]-/); + assertCanonicalTitlesInDocument(assignmentDay2Path, 'classroom/assignment-day2-you-can-build-this.md', /^challenge-(1[0-6])-/); +}); + +test('challenge coach catalog titles match canonical issue templates', () => { + const canonicalByTemplate = new Map( + getCanonicalChallengeTitles().map(({ fileName, title }) => [fileName, title.replace(/^Challenge\s+\d+:\s*/, '')]) + ); + + challenges + .filter(challenge => /^\d+$/.test(challenge.id)) + .forEach(challenge => { + const templateName = path.basename(challenge.template); + assert.equal( + challenge.title, + canonicalByTemplate.get(templateName), + `${templateName}: podcast Challenge Coach title should match canonical template name` + ); + }); +}); + +test('generated podcast scripts avoid stale boilerplate', () => { + if (!fs.existsSync(podcastScriptsDir)) return; + + const bannedFragments = [ + 'as if we are standing together in a classroom', + 'not just memorizing clicks', + 'GitHub work is not magic', + 'Listen before reading to preview the concepts', + 'preview or review the key concepts', + 'Episode coming soon' + ]; + + const scriptFiles = fs.readdirSync(podcastScriptsDir).filter(name => name.endsWith('.txt')); + assert.ok(scriptFiles.length > 0, 'podcasts/scripts should contain generated script files'); + + scriptFiles.forEach(fileName => { + const script = fs.readFileSync(path.join(podcastScriptsDir, fileName), 'utf8'); + bannedFragments.forEach(fragment => { + assert.equal( + script.includes(fragment), + false, + `${fileName}: remove stale generated phrase: ${fragment}` + ); + }); + }); +}); + test('challenge hub contains all canonical challenge and bonus titles', () => { const hub = fs.readFileSync(challengeHubPath, 'utf8'); const titles = getCanonicalChallengeTitles(); @@ -89,11 +156,12 @@ test('facilitator guide progression map aligns with challenge model', () => { const guide = fs.readFileSync(facilitatorGuidePath, 'utf8'); const requiredSnippets = [ - 'close Challenge 1, see Challenge 2 appear', - 'The student-progression workflow begins delivering Challenge 10 onwards.', - '| Core Day 2 | 10-13 |', - '| Advanced | 14-16 |', - '| Bonus | bonus-a through bonus-e |' + "There it is! Challenge 2 just appeared. That's how progression works.", + 'Challenge 10 is waiting for you.', + '| **Core** | 10-13 |', + '| **Advanced** | 14-16 |', + '| **Bonus** | bonus-a through bonus-e |', + 'The progression bot unlocks them when challenges are closed.' ]; requiredSnippets.forEach(snippet => { diff --git a/.github/workflows/registration.yml b/.github/workflows/registration.yml index 40fec7d..9ab2030 100644 --- a/.github/workflows/registration.yml +++ b/.github/workflows/registration.yml @@ -142,11 +142,97 @@ jobs: labels: ['waitlist'] }); + - name: Invite registrant to classroom organization (optional) + id: classroom-invite + if: >- + steps.dup-check.outputs.is_duplicate == 'false' && + steps.capacity-check.outputs.is_full == 'false' && + vars.CLASSROOM_ORG != '' && + secrets.CLASSROOM_ORG_ADMIN_TOKEN != '' + uses: actions/github-script@v7 + env: + CLASSROOM_ORG: ${{ vars.CLASSROOM_ORG }} + with: + github-token: ${{ secrets.CLASSROOM_ORG_ADMIN_TOKEN }} + script: | + const org = process.env.CLASSROOM_ORG; + const username = context.payload.issue.user.login; + const userId = context.payload.issue.user.id; + let status = 'skipped'; + + try { + await github.rest.orgs.checkMembershipForUser({ org, username }); + status = 'already-member'; + core.info(`${username} is already a member of ${org}`); + } catch (error) { + if (error.status !== 404) { + throw error; + } + + const invites = await github.paginate(github.rest.orgs.listPendingInvitations, { + org, + per_page: 100 + }); + + const hasPendingInvite = invites.some(invite => + (invite.login || '').toLowerCase() === username.toLowerCase() + ); + + if (hasPendingInvite) { + status = 'already-invited'; + core.info(`${username} already has a pending invite to ${org}`); + } else { + await github.rest.orgs.createInvitation({ + org, + invitee_id: userId, + role: 'direct_member' + }); + status = 'invited'; + core.info(`Sent org invite for ${username} to ${org}`); + } + } + + core.setOutput('status', status); + - name: Post welcome comment if: steps.dup-check.outputs.is_duplicate == 'false' && steps.capacity-check.outputs.is_full == 'false' uses: actions/github-script@v7 + env: + CLASSROOM_ORG: ${{ vars.CLASSROOM_ORG }} + DAY1_ASSIGNMENT_URL: ${{ vars.CLASSROOM_DAY1_ASSIGNMENT_URL }} + DAY2_ASSIGNMENT_URL: ${{ vars.CLASSROOM_DAY2_ASSIGNMENT_URL }} + CLASSROOM_INVITE_STATUS: ${{ steps.classroom-invite.outputs.status }} with: script: | + const org = process.env.CLASSROOM_ORG; + const day1 = (process.env.DAY1_ASSIGNMENT_URL || '').trim(); + const day2 = (process.env.DAY2_ASSIGNMENT_URL || '').trim(); + const inviteStatus = (process.env.CLASSROOM_INVITE_STATUS || '').trim(); + + let classroomSection = ''; + if (day1 || day2 || inviteStatus) { + const lines = ['## Classroom Access']; + + if (inviteStatus === 'invited') { + lines.push(`- We sent an organization invitation for \`${org}\`. Please accept it from your GitHub notifications or email.`); + } else if (inviteStatus === 'already-invited') { + lines.push(`- You already have a pending invitation for \`${org}\`. Please accept it before using assignment links.`); + } else if (inviteStatus === 'already-member') { + lines.push(`- You are already a member of \`${org}\`.`); + } + + if (day1) { + lines.push(`- Day 1 assignment link: ${day1}`); + } + if (day2) { + lines.push(`- Day 2 assignment link: ${day2}`); + } + + if (lines.length > 1) { + classroomSection = `\n\n${lines.join('\n')}`; + } + } + await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, @@ -159,6 +245,8 @@ jobs: In the meantime, you can get a head start with the [Pre-Workshop Setup Guide](https://community-access.github.io/git-going-with-github/docs/00-pre-workshop-setup.html). + ${classroomSection} + If you have any questions, [file an issue](https://github.com/community-access/git-going-with-github/issues) in the workshop repository. See you at the workshop!` diff --git a/.gitignore b/.gitignore index 5bac9be..93e63bd 100644 --- a/.gitignore +++ b/.gitignore @@ -122,6 +122,8 @@ scripts/tests/ node_modules/ # Podcast audio files — hosted on GitHub Releases, not in the repo +podcasts/bundles/*.md +podcasts/challenge-bundles/*.md podcasts/audio/ *.mp3 diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..c877e9d --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,11 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Run Unit Tests", + "type": "shell", + "command": "npm run test:automation", + "isBackground": false + } + ] +} \ No newline at end of file diff --git a/BATCH.md b/BATCH.md new file mode 100644 index 0000000..2a76919 --- /dev/null +++ b/BATCH.md @@ -0,0 +1,119 @@ +# Batch Command Reference + +This file documents the cmd.exe batch files in the repo root for podcast operations. +All batch files change directory to the repo root automatically, so they work correctly +from any location. + +## Workflow order + +Run operations in this sequence for a full podcast build from scratch: + +1. `generate-transcripts.bat` - write episode scripts from the catalog +2. `generate-audio.bat` - synthesise MP3 audio from those scripts +3. `build-rss-feed.bat` - generate the RSS feed and podcast listing +4. `validate-rss-feed.bat` - verify the feed is valid before publishing + +## generate-transcripts.bat + +Validates the podcast catalog, builds episode and challenge bundles, then writes +all episode and challenge coach scripts to `podcasts\scripts\`. + +``` +generate-transcripts.bat +``` + +Output files: `podcasts\scripts\ep*.txt` and `podcasts\scripts\cc-*.txt` + +Note: transcript generation always rebuilds all episodes from the catalog. +Range selection is not supported at this stage. Run this step whenever the +catalog or source docs change. + +## generate-audio.bat + +Synthesises MP3 audio for all episodes or a specific numbered range. +Audio format, voice model, pitch, and speed settings are read from +`podcasts\tts\voice-config.ini`. + +The script echoes each episode name and index as it is processed. +ffmpeg is required for MP3 output and is located automatically from the +machine PATH, including after a fresh winget install. + +``` +generate-audio.bat generate all 75 episodes +generate-audio.bat 5 generate episodes 5 and above +generate-audio.bat 5 10 generate episodes 5 through 10 +``` + +Output files: `podcasts\audio\*.mp3` + +To change audio format, voice pitch, or speed, edit `podcasts\tts\voice-config.ini` +before running this command. + +## build-rss-feed.bat + +Generates the RSS 2.0 / iTunes-compatible podcast feed and the admin podcast listing. +Reads MP3 file sizes from `podcasts\audio\` and episode metadata from the catalog. + +``` +build-rss-feed.bat +``` + +Output files: + +- `podcasts\feed.xml` - the RSS feed for podcast directories +- `admin\PODCASTS.md` - human-readable episode listing + +Run this command after `generate-audio.bat` completes so that enclosure lengths +reflect the final MP3 file sizes. + +## validate-rss-feed.bat + +Runs local RSS 2.0 and iTunes compliance checks on `podcasts\feed.xml`. + +``` +validate-rss-feed.bat +``` + +Checks performed: + +- Required channel elements: title, link, description, language +- Required per-item elements: title, enclosure, guid +- Enclosure URL, byte length, and MIME type +- Duplicate GUID detection + +Run `build-rss-feed.bat` first. The validator exits with a non-zero code on +any failure so it can be used in CI scripts. + +## Configuration file + +`podcasts\tts\voice-config.ini` controls all audio generation settings. + +The following table lists the available settings. + +| Key | Description | Example | +|-----|-------------|---------| +| `male_model` | Piper ONNX model file for the male voice (Alex) | `en_US-ryan-high.onnx` | +| `female_model` | Piper ONNX model file for the female voice (Jamie) | `en_US-lessac-high.onnx` | +| `male_pitch_semitones` | Pitch shift in semitones for the male voice | `-2` | +| `female_pitch_semitones` | Pitch shift in semitones for the female voice | `2` | +| `speech_rate` | Words per minute (passed to Piper) | `180` | +| `episode_audio_format` | Output format: `wav`, `mp3`, or `both` | `mp3` | + +## npm scripts + +The batch files wrap these npm scripts. They can also be run directly from +a PowerShell or bash session at the repo root. + +| npm script | Description | +|------------|-------------| +| `npm run validate:podcasts` | Validate the podcast catalog | +| `npm run generate:podcast-transcripts` | Generate transcript scripts | +| `npm run build:podcast-audio` | Generate audio (all episodes) | +| `npm run build:podcast-site` | Build RSS feed and podcast listing | +| `npm run validate:podcast-feed` | Validate the RSS feed | + +To pass a range to the audio build from npm: + +``` +npm run build:podcast-audio -- --start 5 --end 10 +``` diff --git a/GO-LIVE-QA-GUIDE.md b/GO-LIVE-QA-GUIDE.md new file mode 100644 index 0000000..3a0a29c --- /dev/null +++ b/GO-LIVE-QA-GUIDE.md @@ -0,0 +1,368 @@ +# 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/README.md) | +| Classroom copy-paste setup pack | [admin/classroom/README.md](admin/classroom/README.md) | +| Human challenge walkthrough | [classroom/HUMAN_TEST_MATRIX.md](classroom/HUMAN_TEST_MATRIX.md) | +| Facilitator operations | [admin/FACILITATOR_OPERATIONS.md](admin/FACILITATOR_OPERATIONS.md) | +| Facilitator guide | [admin/FACILITATOR_GUIDE.md](admin/FACILITATOR_GUIDE.md) | +| Student challenge hub | [docs/CHALLENGES.md](docs/CHALLENGES.md) | +| Podcast pipeline | [podcasts/README.md](podcasts/README.md) | +| Podcast regeneration runbook | [podcasts/REGENERATION.md](podcasts/REGENERATION.md) | +| Post-workshop cleanup | [classroom/teardown-checklist.md](classroom/teardown-checklist.md) | + +## Roles + +- **Release owner:** owns the final go or no-go decision. +- **Classroom tester:** creates assignments, accepts invites with a test student account, and validates repository creation. +- **Automation tester:** checks workflows, seeding scripts, Aria feedback, progression, and autograding. +- **Accessibility tester:** tests with NVDA, JAWS, VoiceOver, keyboard-only navigation, zoom, and high contrast where available. +- **Curriculum tester:** reads chapters, appendices, challenge templates, solutions, and facilitator instructions for accuracy and consistency. +- **Podcast tester:** validates podcast scripts, transcripts, RSS metadata, and audio availability if audio has been generated. + +One person may hold multiple roles, but the release owner should not be the only human tester. + +## Phase 1: Local Repository Health + +Run these commands from the repository root. + +```powershell +npm run test:automation +npm run validate:podcasts +npm run validate:podcast-feed +npm run build:html +git diff --check +``` + +Expected results: + +- `npm run test:automation` reports all tests passing. +- `npm run validate:podcasts` reports 54 catalog episodes and passes. +- `npm run validate:podcast-feed` passes. If audio files have not been generated yet, the transcript-only warning is acceptable. +- `npm run build:html` completes without errors. +- `git diff --check` has no trailing-whitespace or conflict-marker errors. On Windows, LF-to-CRLF warnings may appear and are not release blockers by themselves. + +Record the command output summary in the release notes or QA issue. + +## Phase 2: Content Inventory Review + +Every content file must be reviewed before go-live. Use this checklist to assign coverage. + +- [ ] Root docs: [README.md](README.md), [BUILD.md](BUILD.md), [REGISTER.md](REGISTER.md), [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), [REPOSITORY_SECURITY.md](REPOSITORY_SECURITY.md). +- [ ] Student onboarding: [docs/get-going.md](docs/get-going.md), [docs/course-guide.md](docs/course-guide.md), and [docs/student-onboarding.md](docs/student-onboarding.md). +- [ ] Core chapters: [docs/00-pre-workshop-setup.md](docs/00-pre-workshop-setup.md) through [docs/21-next-steps.md](docs/21-next-steps.md). +- [ ] Appendices: [docs/appendix-a-glossary.md](docs/appendix-a-glossary.md) through [docs/appendix-z-github-skills.md](docs/appendix-z-github-skills.md). +- [ ] Challenge hub: [docs/CHALLENGES.md](docs/CHALLENGES.md). +- [ ] Challenge solutions: all files in [docs/solutions](docs/solutions/README.md). +- [ ] Learning Room template docs: all Markdown files under [learning-room](learning-room/README.md). +- [ ] Issue templates: all files under `learning-room/.github/ISSUE_TEMPLATE/`. +- [ ] Student automation guides: all Markdown files under `learning-room/.github/`. +- [ ] Facilitator guides: all Markdown files under [admin](admin/README.md) and [admin/classroom](admin/classroom/README.md). +- [ ] Classroom setup artifacts: all Markdown, JSON, CSV, and YAML files under [classroom](classroom/README.md). +- [ ] Podcast docs, scripts, manifests, transcripts, and generated site metadata under [podcasts](podcasts/README.md). +- [ ] Generated HTML under `html/` after `npm run build:html`. + +For each file, verify: + +- [ ] The title matches the current GitHub Classroom model. +- [ ] The file does not tell students they are working in a single shared repository unless it is explicitly discussing legacy history. +- [ ] Branch names use the current conventions: `learn/` for the Day 1 practice branch, or short-lived `fix/...` branches for focused PR exercises. +- [ ] Challenge numbers, titles, and evidence requirements match [docs/CHALLENGES.md](docs/CHALLENGES.md). +- [ ] Links resolve or are intentionally broken practice targets in the Learning Room template. +- [ ] Instructions are concise enough for a facilitator to read aloud. +- [ ] Screen reader steps avoid visual-only wording when a keyboard or structural path is available. +- [ ] Tables have a preceding sentence explaining what they contain. +- [ ] Diagrams, images, and SVGs have nearby text alternatives in the surrounding documentation. + +## Phase 3: Classroom Deployment Dry Run + +Use a real GitHub Classroom with disposable test accounts. Do not use a facilitator account as the student account. + +### Organization And Template Readiness + +- [ ] Confirm the classroom organization exists and facilitators have owner or admin access. +- [ ] Confirm `Community-Access/learning-room-template` exists and is the template repository selected for both assignments. +- [ ] Confirm GitHub Actions is enabled for the template repository. +- [ ] Confirm `GITHUB_TOKEN` has read and write permissions in the template repository settings. +- [ ] Confirm Actions can create and approve pull requests if Classroom feedback PRs are used. +- [ ] Confirm the Learning Room template includes `.github/workflows/pr-validation-bot.yml`. +- [ ] Confirm the Learning Room template includes `.github/workflows/student-progression.yml`. +- [ ] Confirm the Learning Room template includes all autograder workflows. +- [ ] Confirm the Learning Room template includes all challenge issue templates and bonus templates. + +### Day 1 Assignment + +- [ ] Create the Day 1 assignment using [classroom/assignment-day1-you-belong-here.md](classroom/assignment-day1-you-belong-here.md). +- [ ] Use private individual repositories. +- [ ] Enable feedback pull requests. +- [ ] Add every Day 1 autograding test from [classroom/autograding-day1.json](classroom/autograding-day1.json). +- [ ] Save the Day 1 invite link. +- [ ] Accept the invite with a test student account. +- [ ] Confirm the student repository appears in the Classroom dashboard. +- [ ] Confirm the repository name follows the expected pattern. +- [ ] Confirm the template files copied correctly. +- [ ] Seed Challenge 1: + +```powershell +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student -Challenge 1 -Assignee test-student +``` + +- [ ] Confirm Challenge 1 appears in the student repository. + +### Day 2 Assignment + +- [ ] Create the Day 2 assignment using [classroom/assignment-day2-you-can-build-this.md](classroom/assignment-day2-you-can-build-this.md). +- [ ] Use private individual repositories. +- [ ] Enable feedback pull requests. +- [ ] Add every Day 2 autograding test from [classroom/autograding-day2.json](classroom/autograding-day2.json). +- [ ] Save the Day 2 invite link. +- [ ] Accept the invite with the test student account. +- [ ] Confirm the Day 2 repository appears in the Classroom dashboard. +- [ ] Seed Challenge 10: + +```powershell +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-test-student-day2 -Challenge 10 -Assignee test-student +``` + +- [ ] Confirm Challenge 10 appears in the student repository. + +## Phase 4: Workflow And Automation QA + +Run these checks in disposable student repositories created by GitHub Classroom. + +### Aria PR Validation Bot + +- [ ] Open a PR with a clear title, body, and `Closes #N` reference. +- [ ] Confirm the first-time contributor welcome comment appears on the first PR. +- [ ] Confirm the PR Validation Report appears or updates within 60 seconds. +- [ ] Push another commit and confirm the existing validation comment updates instead of duplicating. +- [ ] Add an intentional issue, such as vague link text, and confirm the bot explains the problem. +- [ ] Fix the issue and confirm the validation result improves. +- [ ] Comment `@aria-bot help` and confirm the help responder answers. +- [ ] Comment with `merge conflict` and confirm the conflict guidance appears. +- [ ] Confirm bot-authored comments do not trigger an infinite response loop. + +### Student Progression Bot + +- [ ] Close Challenge 1 and confirm Challenge 2 appears. +- [ ] Continue closing challenges until Challenge 9 appears. +- [ ] Seed Challenge 10 and confirm the Day 2 sequence starts correctly. +- [ ] Close Challenge 10 and confirm Challenge 11 appears. +- [ ] Confirm duplicate challenge issues are not created if the workflow reruns. +- [ ] Confirm the assigned user is correct on each generated challenge. +- [ ] Confirm each generated challenge links to the right chapter and solution reference. + +### Autograders + +- [ ] Challenge 4 branch test passes when a non-default branch exists. +- [ ] Challenge 5 commit test passes when the student commits a real file change. +- [ ] Challenge 6 PR test passes when the PR references the correct issue. +- [ ] Challenge 7 conflict test fails while conflict markers remain. +- [ ] Challenge 7 conflict test passes after conflict markers are removed. +- [ ] Challenge 9 merge/readiness checks report useful results. +- [ ] Challenge 10 local commit test passes after clone, branch, commit, and push. +- [ ] Challenge 14 template test validates a structured issue template. +- [ ] Challenge 16 capstone test validates the required agent contribution evidence. + +### Seeding Scripts + +- [ ] `Seed-LearningRoomChallenge.ps1` creates the requested starting challenge. +- [ ] `Seed-PeerSimulation.ps1` creates the peer simulation issues, branch, file, and PR. +- [ ] `Start-MergeConflictChallenge.ps1` creates a real conflict against the student branch. +- [ ] `Test-LearningRoomTemplate.ps1` reports the template readiness state. +- [ ] Script failures show a clear error message and do not partially hide the problem. + +## Phase 5: Human Challenge Walkthrough + +Use [classroom/HUMAN_TEST_MATRIX.md](classroom/HUMAN_TEST_MATRIX.md) as the detailed scenario list. This section is the go-live summary gate. + +### Day 1 Core Path + +- [ ] Challenge 1: Find Your Way Around. +- [ ] Challenge 2: File Your First Issue. +- [ ] Challenge 3: Join the Conversation. +- [ ] Challenge 4: Branch Out. +- [ ] Challenge 5: Make Your Mark. +- [ ] Challenge 6: Open Your First Pull Request. +- [ ] Challenge 7: Survive a Merge Conflict. +- [ ] Challenge 8: The Culture Layer. +- [ ] Challenge 9: Merge Day. + +### Day 2 Core Path + +- [ ] Challenge 10: Go Local. +- [ ] Challenge 11: Open a Day 2 PR. +- [ ] Challenge 12: Review Like a Pro. +- [ ] Challenge 13: AI as Your Copilot. +- [ ] Challenge 14: Template Remix. +- [ ] Challenge 15: Meet the Agents. +- [ ] Challenge 16: Build Your Agent. + +### Bonus Path + +- [ ] Bonus A: Improve an Agent. +- [ ] Bonus B: Document Your Journey. +- [ ] Bonus C: Group Challenge. +- [ ] Bonus D: Notifications. +- [ ] Bonus E: Git History. + +For each challenge, record: + +- [ ] The issue appeared at the expected time. +- [ ] The issue instructions were understandable without facilitator translation. +- [ ] The linked chapter helped complete the task. +- [ ] The evidence prompt was clear. +- [ ] The bot or autograder response was useful. +- [ ] The next challenge unlocked correctly. +- [ ] The reference solution matched the challenge. + +## Phase 6: Accessibility QA + +Run accessibility testing with at least one screen reader and one keyboard-only tester. Use more assistive technology coverage when possible. + +- [ ] NVDA with Firefox or Chrome: complete Challenge 1, Challenge 6, Challenge 7, and one Day 2 challenge. +- [ ] JAWS with Chrome or Edge: complete issue creation, PR creation, review, and merge checks. +- [ ] VoiceOver with Safari or Chrome: accept Classroom invite, navigate repo, edit file, and read PR diff. +- [ ] Keyboard-only: complete invite acceptance, issue creation, PR creation, and review submission without a mouse. +- [ ] Low vision: verify 200 percent zoom, high contrast, browser zoom, and focus visibility across GitHub, docs, and generated HTML. +- [ ] Confirm all critical links have descriptive text. +- [ ] Confirm all tables in docs have a preceding explanation. +- [ ] Confirm images and diagrams have meaningful surrounding text or alt text. +- [ ] Confirm generated HTML task-list checkboxes are not duplicated. +- [ ] Confirm conflict-marker examples render as examples and do not break Git diff checks. + +## Phase 7: Podcast And Audio QA + +The podcast material is part of the release. Test it even if audio has not been regenerated yet. + +- [ ] `npm run validate:podcasts` passes. +- [ ] `npm run validate:podcast-feed` passes. +- [ ] Podcast catalog lists 54 companion episodes. +- [ ] Challenge Coach bundles exist for all 16 core challenges and 5 bonus challenges. +- [ ] Each chapter and appendix points to the intended podcast entry. +- [ ] Transcript scripts avoid stale shared-repository boilerplate. +- [ ] Speaker markers are consistent in generated scripts. +- [ ] RSS feed state is documented: transcript-only or audio-ready. +- [ ] If audio exists, every MP3 enclosure URL resolves. +- [ ] If audio exists, a human tester listens to a sample from Day 1, Day 2, appendices, and Challenge Coach. +- [ ] Podcast instructions do not contradict the current private Learning Room model. + +## Phase 8: Facilitator Dry Run + +Run this as a timed rehearsal before student testing. + +- [ ] Facilitator can find this guide from [README.md](README.md), [admin/README.md](admin/README.md), and [classroom/README.md](classroom/README.md). +- [ ] Facilitator can explain the architecture in under 2 minutes. +- [ ] Facilitator can create Assignment 1 without guessing any setting. +- [ ] Facilitator can create Assignment 2 without guessing any setting. +- [ ] Facilitator can seed Challenge 1 and Challenge 10 from PowerShell. +- [ ] Facilitator can seed peer simulation artifacts. +- [ ] Facilitator can start a merge conflict challenge. +- [ ] Facilitator can read Aria feedback and decide whether it is correct. +- [ ] Facilitator can override or manually support a student if automation fails. +- [ ] Facilitator can explain how Day-2-only participants enter the course. +- [ ] Facilitator can explain what to do when a student joins late. +- [ ] Facilitator can run post-workshop teardown. + +## Issue Severity + +The following table defines release-blocking severity levels. + +| Severity | Meaning | Release action | +|---|---|---| +| Blocker | Prevents assignment creation, repository creation, challenge progression, PR validation, accessibility use, or student safety | Fix before release | +| High | Causes confusing instructions, broken links in required paths, wrong challenge evidence, or broken generated content | Fix before release unless release owner approves exception | +| Medium | Causes friction but has a clear workaround | Fix before or immediately after release | +| Low | Typo, minor wording, or non-blocking polish | Fix when practical | + +## QA Evidence Log Template + +Copy this template into a release issue or testing document. + +```markdown +## QA Evidence Log + +Release candidate: +Date: +Release owner: +Classroom tester: +Automation tester: +Accessibility tester: +Curriculum tester: +Podcast tester: + +### Automated Checks +- npm run test:automation: +- npm run validate:podcasts: +- npm run validate:podcast-feed: +- npm run build:html: +- git diff --check: + +### Classroom Dry Run +- Day 1 assignment URL: +- Day 2 assignment URL: +- Test student account: +- Day 1 test repository: +- Day 2 test repository: + +### Human Walkthrough +- Day 1 challenges completed: +- Day 2 challenges completed: +- Bonus challenges completed: +- Accessibility coverage: +- Podcast coverage: + +### Findings +| ID | Severity | Area | Finding | Owner | Status | +|---|---|---|---|---|---| + +### Release Decision +- [ ] Go +- [ ] No-go +- Notes: +``` + +## Final Go-Live Checklist + +- [ ] All required automated checks passed. +- [ ] All required Classroom dry-run checks passed. +- [ ] Human testers completed Day 1, Day 2, bonus, accessibility, and podcast coverage. +- [ ] No open Blocker findings remain. +- [ ] No open High findings remain without written release-owner exception. +- [ ] Invite links are stored in the facilitator runbook and student communications. +- [ ] Facilitators know how to seed Challenge 1 and Challenge 10. +- [ ] Facilitators know how to recover when Aria, progression, or autograding fails. +- [ ] Student-facing instructions match the current GitHub Classroom private-repository model. +- [ ] Generated HTML and podcast site have been rebuilt from the final sources. +- [ ] Release owner has recorded the final decision. \ No newline at end of file diff --git a/README.md b/README.md index 40a33c5..b0b4e12 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ License: CC BY 4.0 | [Site](https://community-access.org/git-going-with-github/) | Detail | Information | |---|---| | **Workshop site** | [community-access.org/git-going-with-github](https://community-access.org/git-going-with-github/) | -| **Registration** | Closed - thank you to all who registered! | +| **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) | | **Dates** | May 21, 2026 & May 22, 2026 | @@ -22,7 +22,7 @@ License: CC BY 4.0 | [Site](https://community-access.org/git-going-with-github/) > > This workshop is built around a real, live open source project: **[Accessibility Agents](https://github.com/community-access/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. By the end of Day 2, your name is in its commit history. +> 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. @@ -35,7 +35,7 @@ During this two-day workshop, you will learn how to confidently navigate and con - **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 made **real contributions** to a real repository. Not simulated. Not pretend. Real. +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? @@ -55,7 +55,7 @@ You do **not** need to know how to code to participate and contribute meaningful | 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), run agentic workflows in the cloud, and ship a real PR upstream to `community-access/accessibility-agents` | +| **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 @@ -75,24 +75,26 @@ github.dev - VS Code on the web, no install needed Day 2 - Deepen with VS Code + Accessibility Agents Learn VS Code basics → Copilot inline → Copilot Chat - @daily-briefing → @issue-tracker → @pr-review → @analytics → ship upstream + @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 Day 2, you will have:** +**By the end of the Day 2 core path, you will have:** - A fork of `accessibility-agents` with your personalized preferences -- At least one merged PR in a real open source project -- Your name in the commit history of `community-access/accessibility-agents` +- 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. Read them in order for the full experience, or jump to what you need. +All documentation lives in the `docs/` folder. If you are new, start with [Get Going with GitHub](docs/get-going.md). 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](GO-LIVE-QA-GUIDE.md) as the release gate before sharing Classroom invite links. -## Your Challenges + +## Your Challenges **16 challenges guide you through the workshop, plus 5 bonus challenges for those who finish early.** @@ -111,7 +113,7 @@ Every chapter has an "If You Get Stuck" section. Every challenge has a [referenc > **HTML Version Available:** All markdown documentation is automatically converted to HTML format. After cloning the repository, you can browse the `html/` directory for web-formatted versions of every document. See [BUILD.md](BUILD.md) for details. -> **Audio Series Available:** Every chapter and appendix has a companion podcast episode - a conversational two-host overview perfect for previewing concepts or reducing screen reader fatigue. [Browse all 44 episodes](PODCASTS.md) or [subscribe via RSS](https://community-access.org/git-going-with-github/podcasts/feed.xml). +> **Audio Series Available:** Every chapter and appendix has a companion podcast episode - a conversational two-host overview perfect for previewing concepts or reducing screen reader fatigue. The refreshed catalog now covers 54 companion episodes, with Challenge Coach episodes planned as a separate teaching layer. [Browse the podcast episodes](admin/PODCASTS.md) or [subscribe via RSS](https://community-access.org/git-going-with-github/podcasts/feed.xml). ### Quick Navigation @@ -121,11 +123,12 @@ Every chapter has an "If You Get Stuck" section. Every challenge has a [referenc | # | Document | What It Covers | |---|----------|----------------| +| [Start](docs/get-going.md) | **Get Going with GitHub** | GitHub Classroom onboarding, Learning Room first steps, support, and tool choice | | [00](docs/00-pre-workshop-setup.md) | **Pre-Workshop Setup** | Everything to install and configure before Day 1 | | [01](docs/01-choose-your-tools.md) | **Choose Your Tools** | Screen reader options, tooling decisions, and workflow setup | | [02](docs/02-understanding-github.md) | **Understanding GitHub** | How GitHub is organized, page types, landmark structure, and screen reader orientation | | [03](docs/03-navigating-repositories.md) | **Navigating Repositories** | Step-by-step repository navigation with your screen reader | -| [04](docs/04-the-learning-room.md) | **The Learning Room** | Your shared practice space, branching, committing, and PR workflow | +| [04](docs/04-the-learning-room.md) | **The Learning Room** | Your private practice repository, branching, committing, and PR workflow | | [05](docs/05-working-with-issues.md) | **Working with Issues** | Filing, managing, and participating in issues | | [06](docs/06-working-with-pull-requests.md) | **Working with Pull Requests** | Creating, reviewing, and merging pull requests | | [07](docs/07-merge-conflicts.md) | **Merge Conflicts** | Understanding, preventing, and resolving merge conflicts | @@ -216,7 +219,7 @@ Every chapter has an "If You Get Stuck" section. Every challenge has a [referenc │ ├── roster-template.csv │ ├── grading-guide.md │ └── teardown-checklist.md -├── learning-room/ -- Practice target for contribution exercises +├── learning-room/ -- GitHub Classroom template copied into each student's private repo │ ├── README.md │ └── docs/ │ ├── welcome.md -- Has TODO sections for you to complete diff --git a/REGISTER.md b/REGISTER.md new file mode 100644 index 0000000..3cfcb15 --- /dev/null +++ b/REGISTER.md @@ -0,0 +1,39 @@ +# Student Opt-In + +[Back to Home](https://community-access.org/git-going-with-github/) | [Discussion Forum](https://github.com/community-access/git-going-with-github/discussions) | [Pre-Workshop Setup Guide](https://community-access.org/git-going-with-github/docs/00-pre-workshop-setup.html) + +## Join the next GIT Going with GitHub cohort + +This page provides a fast, self-serve opt-in workflow for students. + +| | | +|---|---| +| **Status** | Open for student opt-in | +| **Current confirmed registrations** | **Loading...** | +| **Cost** | Free | +| **Form** | GitHub issue form with automated confirmation and waitlist handling | + +## Quick opt-in workflow + +1. Sign in to your [GitHub account](https://github.com/login). +2. Open the registration issue form. +3. Submit the form. + +> [**Start Student Opt-In Form**](https://github.com/community-access/git-going-with-github/issues/new?template=workshop-registration.yml&title=%5BREGISTER%5D+GIT+Going+with+GitHub) + +## What happens automatically + +- Duplicate submissions are handled automatically. +- If capacity is available, your registration is confirmed. +- If capacity is full, your issue is placed on the waitlist automatically. + +## Important note + +Registration issues are public because this repository is public. + +## Need help? + +- [File an issue](https://github.com/community-access/git-going-with-github/issues) +- [Join the Discussion Forum](https://github.com/community-access/git-going-with-github/discussions) + +*A [Community Access](https://community-access.org) initiative.* diff --git a/admin/ANNOUNCEMENT.md b/admin/ANNOUNCEMENT.md index eda7d97..a37a1af 100644 --- a/admin/ANNOUNCEMENT.md +++ b/admin/ANNOUNCEMENT.md @@ -13,8 +13,8 @@ Sponsored by [Community Access](https://community-access.org) in partnership wit | Detail | Information | |---|---| | **Dates** | May 21, 2026 & May 22, 2026 | -| **Time** | 12:00 PM - 8:00 PM Eastern (both days) | -| **Location** | Online via [Zoom](https://zoom.us/) | +| **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](https://community-access.org) | @@ -23,6 +23,9 @@ Sponsored by [Community Access](https://community-access.org) in partnership wit ### 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**](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. @@ -35,7 +38,7 @@ This is a two-day, hands-on workshop where blind and low vision participants lea No mouse. No sighted assistance. No pretending. -By the end of Day 2, your name will be in the commit history of a live, public open source project. Not a sandbox. Not a simulation. The real thing. +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. @@ -44,7 +47,7 @@ This workshop exists because open source software powers the world - and the peo On Day 2, you will work with **[Accessibility Agents](https://community-access.org/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. By the end of the workshop, your name is in its commit history. +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? @@ -192,6 +195,8 @@ Our [Pre-Workshop Setup Guide](https://community-access.org/git-going-with-githu Registration for GIT Going with GitHub is now closed. Thank you to all who registered! +If you want to be considered for the next cohort, complete the [Student Opt-In page](https://community-access.org/git-going-with-github/REGISTER.html). The form is processed automatically and supports waitlist handling when needed. + Already registered? Complete the [**Pre-Workshop Setup Guide**](https://community-access.org/git-going-with-github/docs/00-pre-workshop-setup.html) before Day 1 to make sure you are ready. diff --git a/admin/DAY1_AGENDA.md b/admin/DAY1_AGENDA.md index 7a0abbe..8d09084 100644 --- a/admin/DAY1_AGENDA.md +++ b/admin/DAY1_AGENDA.md @@ -3,7 +3,17 @@ > **Day 1 Focus:** The GitHub web interface -- navigating repositories, filing and responding to issues, understanding pull requests, and contributing through the browser using only your keyboard and screen reader. > -> **How learning works today:** Each participant has their own private repository, created automatically when you accept the Classroom assignment. Inside that repo, an automation system called Aria guides you through a series of challenges delivered as GitHub Issues. When you complete one challenge and close the issue, Aria unlocks the next. You work at your own pace through Challenges 1-9 during the structured blocks below, with facilitator guidance and peer collaboration throughout. +> **How learning works today:** Each participant has their own private repository, created automatically when you accept the Classroom assignment. Inside that repo, an automation system called Aria guides you through a series of challenges delivered as GitHub Issues. The live session prioritizes the core path through repository navigation, issues, branches, commits, and a first pull request. The remaining challenges stay available for async completion during open lab time or after the event. + + +## Coverage Promise + +This agenda is a live facilitation plan, not a requirement that every chapter and challenge be completed in the room. The full curriculum contains more material than a shortened live day can responsibly cover. + +- **Live core:** Participants should leave able to navigate a repository, file and discuss issues, create a branch, edit a file, commit, and open a pull request. +- **Live support if time allows:** Merge conflicts, review practice, labels, milestones, notifications, and culture exercises. +- **Async follow-up:** Challenges 7-9 and the reference chapters remain available after the live session. Facilitators can use open lab time for catch-up instead of moving the whole room forward. +- **Remote-ready delivery:** Remote participants should receive the same Classroom links, Slack channel, CART/ASL access where available, and written checkpoints. Every block should include a clear "you are done when" checkpoint so people can pause and resume later. ## Your Classroom Repository @@ -27,21 +37,25 @@ When you accept the Day 1 assignment link, GitHub creates a private copy of the ## At a Glance -| Block | Time (Eastern) | Topic | Challenges | -|-------|----------------|-------|-----------| -| 0 | 12:00 PM | Welcome, setup verification, and accept Classroom assignment | -- | -| 1 | 12:30 PM | Screen reader orientation to GitHub | Challenge 1: Find Your Way | -| 2 | 1:10 PM | Navigating repositories, issues, and conversations | Challenges 2-3 | -| -- | 2:00 PM | **Break** | -- | -| 3 | 2:15 PM | Branching, editing, and committing | Challenges 4-5 | -| 4 | 3:10 PM | Pull requests, review, and merge conflicts | Challenges 6-7 | -| -- | 4:00 PM | **Dinner break** | -- | -| 5 | 5:00 PM | Culture, triage, and merge day | Challenges 8-9 | -| -- | 6:00 PM | **Break** | -- | -| 6 | 6:15 PM | Community: communication, labels, and notifications | -- | -| -- | 7:30 PM | Wrap-up and reflections | -- | +The following table summarizes the Pacific-time live agenda and identifies which blocks are required live coverage versus stretch or async material. -**Total:** ~7.5 hours of structured time (12:00 PM - 8:00 PM Eastern) +| Time (Pacific) | Block | Topic | Coverage | +|----------------|-------|-------|----------| +| 9:00-9:30 AM | Event welcome | Check-in, breakfast, access services, and orientation | Required live | +| 9:30-10:00 AM | Keynote | Making real change through real learning | Required live | +| 10:00-10:15 AM | Opening remarks | Event goals, agenda, and participation norms | Required live | +| 10:15-10:45 AM | Block 0 | Learning Room setup and Classroom assignment acceptance | Required live | +| 10:45-11:20 AM | Block 1 | Screen reader orientation to GitHub | Required live: Challenge 1 | +| 11:20 AM-12:00 PM | Block 2 | Issues and conversations | Required live: Challenges 2-3 | +| 12:00-1:00 PM | Lunch | Food, rest, informal support | Required break | +| 1:00-1:50 PM | Block 3 | Branching, editing, and committing | Required live: Challenges 4-5 | +| 1:50-2:45 PM | Block 4 | Pull requests and review basics | Required live: Challenge 6; Challenge 7 if time allows | +| 2:45-3:00 PM | Break | Rest and facilitator triage | Required break | +| 3:00-4:00 PM | Block 5 | Contribution lab and merge-conflict support | Live support: finish Challenges 4-7 | +| 4:00-4:30 PM | Block 6 | Culture, triage, labels, and notifications | Async or stretch: Challenges 8-9 | +| 4:30-5:00 PM | Wrap-up | Reflection, next steps, remote catch-up path | Required live | + +**Total:** 8 hours of event time (9:00 AM - 5:00 PM Pacific), with about 5 hours of hands-on GitHub instruction after keynote, opening remarks, lunch, and breaks. ## Pre-Day Checklist @@ -49,12 +63,12 @@ When you accept the Day 1 assignment link, GitHub creates a private copy of the Before entering the room (or joining the call), participants should have completed everything in [Pre-Workshop Setup](../docs/00-pre-workshop-setup.md). The facilitator will do a quick verification at the start. -## Block 0 - Welcome and Orientation (12:00 PM, 30 min) +## Block 0 - Learning Room Setup and Orientation (10:15 AM, 30 min) ### Date and Location -**Day 1: May 21, 2026** | 12:00 PM - 8:00 PM Eastern -**Day 2: May 22, 2026** | 12:00 PM - 8:00 PM Eastern +**Day 1: May 21, 2026** | 9:00 AM - 5:00 PM Pacific +**Day 2: May 22, 2026** | 9:00 AM - 5:00 PM Pacific ### Facilitators @@ -96,7 +110,7 @@ The facilitator shares the Day 1 assignment link. Each participant follows the [ - Each participant: your name, your screen reader and OS, what brings you here -## Block 1 - Screen Reader Orientation to GitHub (12:30 PM, 40 min) +## Block 1 - Screen Reader Orientation to GitHub (10:45 AM, 35 min) ### Purpose @@ -161,7 +175,7 @@ When you finish, submit your evidence in the challenge issue and close it. Withi [Screen Reader Cheat Sheet](../docs/appendix-b-screen-reader-cheatsheet.md) -## Block 2 - Issues and Conversations (1:10 PM, 50 min) +## Block 2 - Issues and Conversations (11:20 AM, 40 min) ### Purpose @@ -211,12 +225,12 @@ After submitting your evidence, close Challenge 3. Challenge 4 opens. [Working with Issues](../docs/05-working-with-issues.md) | [Glossary](../docs/appendix-a-glossary.md) -## Break (2:00 PM, 15 min) +## Lunch (12:00 PM, 60 min) Encourage participants to stand, stretch, and rest their ears. Screen reader listening is cognitively demanding work. -## Block 3 - Branching, Editing, and Committing (2:15 PM, 55 min) +## Block 3 - Branching, Editing, and Committing (1:00 PM, 50 min) ### Purpose @@ -281,7 +295,7 @@ If you are still working on a challenge, use this time to finish. [Working with Pull Requests](../docs/06-working-with-pull-requests.md) -## Block 4 - Pull Requests, Review, and Merge Conflicts (3:10 PM, 50 min) +## Block 4 - Pull Requests, Review, and Merge Conflicts (1:50 PM, 55 min) ### Purpose @@ -358,7 +372,7 @@ Submit your evidence and close Challenge 7. Challenge 8 appears. ### Part C - Navigating a PR with Your Screen Reader (10 min) -Before lunch, practice navigating the PR you just opened: +Before the afternoon break, practice navigating the PR you just opened: 1. **Conversation tab:** Read the PR title, description, and Aria's comment 2. **Commits tab:** How many commits? Navigate the list @@ -371,10 +385,12 @@ Before lunch, practice navigating the PR you just opened: [Working with Pull Requests](../docs/06-working-with-pull-requests.md) | [Merge Conflicts](../docs/07-merge-conflicts.md) -## Dinner Break (4:00 PM, 60 min) +## Break (2:45 PM, 15 min) + +## Block 5 - Contribution Lab and Merge-Conflict Support (3:00 PM, 60 min) -## Block 5 - Culture, Triage, and Merge Day (5:00 PM, 60 min) +Use this block as supported lab time first. If most participants have already opened a pull request, move into culture, triage, and merge-day practice. If not, keep facilitators focused on helping participants finish Challenges 4-7. ### Purpose @@ -416,7 +432,7 @@ Challenge 9 is the Day 1 capstone: get your PR merged. 4. After the merge, go to the Code tab and verify your changes appear on `main` 5. Check that your linked issue was automatically closed -> **Magic Moment:** Navigate to the Code tab. Your changes are on `main`. The issue you filed is closed. Your name is in the commit history. This is how every open source contribution works -- everywhere, on every project, forever. +> **Magic Moment:** If your PR merged today, navigate to the Code tab. Your changes are on `main`. The issue you filed is closed. Your name is in the commit history. If your PR is still in progress, you have the same path in front of you: finish the review, merge when ready, and the result is real. Submit your evidence and close Challenge 9. @@ -430,12 +446,9 @@ If you finished Challenges 8-9, find a classmate who is still working: If everyone is done, browse the bonus challenges (A through E) for extra practice. -## Break (6:00 PM, 15 min) - -Stand, stretch, and rest your ears. The final block is discussion-centered and lower intensity. - +## Block 6 - Community: Communication, Labels, and Notifications (4:00 PM, 30 min) -## Block 6 - Community: Communication, Labels, and Notifications (6:15 PM, 75 min) +This block is stretch content for live delivery. If participants are still finishing pull requests, use this time as supported lab time and assign the culture, triage, labels, and notifications material as async follow-up. ### Purpose @@ -521,7 +534,7 @@ Practice applying labels to a challenge issue in your repo. If you have complete 4. Change your repository Watch settings to "Participating and @mentions only" -## Wrap-Up (7:30 PM, 30 min) +## Wrap-Up (4:30 PM, 30 min) ### What You Built Today (10 min) diff --git a/admin/DAY2_AGENDA.md b/admin/DAY2_AGENDA.md index 1dc5d14..e589d0a 100644 --- a/admin/DAY2_AGENDA.md +++ b/admin/DAY2_AGENDA.md @@ -1,7 +1,7 @@ # Day 2 Agenda ## From Contributor to Product Maker - Igniting the Forge -**Date:** May 22, 2026 | 12:00 PM - 8:00 PM Eastern +**Date:** May 22, 2026 | 9:00 AM - 5:00 PM Pacific > **The premise of Day 2:** Whether you built your GitHub skills yesterday in Day 1 or you are joining today with existing GitHub experience, the foundation is the same: you know how to navigate repositories, file issues, open pull requests, and review someone else's work. Those skills are yours now. > @@ -12,6 +12,16 @@ > **Joining on Day 2 without attending Day 1?** See the [Day 2 Quick Start](DAY2_QUICK_START.md) guide to verify your setup and self-assess your readiness. +## Coverage Promise + +Day 2 is designed as a live contribution day with a self-paced continuation path. The complete Day 2 curriculum contains more material than the live schedule can cover, especially because participants will move at different speeds through setup, Git, Copilot, and project work. + +- **Live core:** Participants should leave able to work locally in VS Code, use Git with a branch and pull request, use Copilot as a reviewed writing partner, inspect accessibility agents, and identify one concrete contribution path. +- **Live support if time allows:** Custom issue templates, full agent creation, cross-fork upstream pull requests, GitHub Agentic Workflows, and Spec Kit planning. +- **Async follow-up:** Challenges 14-16, full capstone work, and upstream PR polish can continue after the event through the same repositories and Slack channel. +- **Remote-ready delivery:** Remote participants need the repository links, Slack channel, CART/ASL access where available, and written checkpoints before each lab. Facilitators should state when a block is demo-only, hands-on, or async-safe. + + ## Prerequisites for Day 2 Day 2 requires the following skills and setup. If you attended Day 1, you have all of these. If you are joining fresh, verify each item before the session. @@ -29,23 +39,25 @@ Day 2 requires the following skills and setup. If you attended Day 1, you have a ## At a Glance -| Time | Block | Theme | -|------|-------|-------| -| 9:00-9:30 | Block 0 - Welcome and Orientation | Onboard all participants, verify setup, set goals | -| 9:30-10:30 | Block 1 - VS Code Setup | Screen reader mode, Accessibility Agents as workspace, navigation | -| 10:30-10:45 | Break | - | -| 10:45-12:00 | Block 2 - Deep Contribution | Copilot Chat, inline suggestions, richer PR work | -| 12:00-13:00 | Lunch | - | -| 13:00-14:00 | Block 3 - Activate the Agents | First live agent commands - after earning them | -| 14:00-15:00 | Block 4 - Agentic Workflows | Cloud agents, GitHub Actions, the full reach | -| 15:00-15:15 | Break | - | -| 15:15-16:15 | Block 5 - Ship Your Contribution | Real PR upstream to `community-access/accessibility-agents` | -| 16:15-17:00 | Block 6 - Spec Kit: Design the Future | Group speccing session - what comes next | -| 17:00-17:30 | Wrap-Up | Names in history, reflections, next steps | +The following table summarizes the Pacific-time live agenda and marks which material is core, stretch, or async-friendly. + +| Time (Pacific) | Block | Theme | Coverage | +|----------------|-------|-------|----------| +| 9:00-9:30 AM | Block 0 - Welcome and Orientation | Onboard participants, verify setup, set goals | Required live | +| 9:30-10:30 AM | Block 1 - VS Code and Local Git Setup | Screen reader mode, local clone, branch, commit, push | Required live | +| 10:30-10:45 AM | Break | Rest and facilitator triage | Required break | +| 10:45 AM-12:00 PM | Block 2 - Deep Contribution with Copilot | Copilot Chat, inline suggestions, contribution drafting | Required live | +| 12:00-1:00 PM | Lunch | Food, rest, informal support | Required break | +| 1:00-2:00 PM | Block 3 - Activate the Agents | Agent discovery, validation, and human review | Required live | +| 2:00-2:15 PM | Break | Rest and facilitator triage | Required break | +| 2:15-3:00 PM | Block 4 - Agentic Workflows | Cloud agents, Actions, and broader automation | Stretch or demo | +| 3:00-4:15 PM | Block 5 - Ship Your Contribution | Supported project work and PR preparation | Required lab | +| 4:15-4:40 PM | Block 6 - Spec Kit: Design the Future | Group speccing and future ideas | Stretch or async | +| 4:40-5:00 PM | Wrap-Up | Demos, reflections, and continued contribution paths | Required live | ## Block 0 - Welcome and Orientation -**9:00-9:30** +**9:00-9:30 AM Pacific** ### Purpose Bring everyone to the same starting line -- whether they attended Day 1 or are joining fresh today. Celebrate what was shipped yesterday, onboard new participants, and set the Day 2 mindset: you are not a learner today - you are a product maker. @@ -70,13 +82,13 @@ Each participant states one contribution goal for the day. Examples: - *"I want to improve the screen reader output of the `@daily-briefing` report."* - *"I want to write documentation for the `@insiders-a11y-tracker` agent."* -Write it down. You will check it against reality at 5pm. +Write it down. You will check it against reality during wrap-up. ## Block 1 - VS Code Setup -**9:30-10:30** +**9:30-10:30 AM Pacific** -> This block builds on [VS Code: Setup & Accessibility Basics](docs/11-vscode-interface.md), [Git & Source Control in VS Code](docs/14-git-in-practice.md), and [GitHub Pull Requests Extension](docs/15-code-review.md) for full reference. +> This block builds on [VS Code: Setup & Accessibility Basics](../docs/11-vscode-interface.md), [Git & Source Control in VS Code](../docs/14-git-in-practice.md), and [GitHub Pull Requests Extension](../docs/15-code-review.md) for full reference. ### Purpose Move from browser-based GitHub to VS Code as your contribution environment. Set up screen reader mode. Open `accessibility-agents` as a workspace. Understand what you are looking at before any agent runs. @@ -163,7 +175,7 @@ Press `Ctrl+Shift+I` to open the Chat panel. ## Block 2 - Deep Contribution with Copilot -**10:45-12:00** +**10:45 AM-12:00 PM Pacific** ### Copilot Orientation (15 min) @@ -234,7 +246,7 @@ Before leaving for lunch, check your progress: ## Block 3 - Activate the Agents -**13:00-14:00** +**1:00-2:00 PM Pacific** > **This block is the payoff.** You earned it yesterday. You understand what GitHub is, how repositories work, what issues and pull requests are, and how notifications flow. Now you watch an agent do the work you know how to verify. > @@ -291,7 +303,7 @@ Participants answer from their Day 1 knowledge. Then the command runs. Then the **Critical exercise:** Compare the agent's suggested comments to what you wrote manually in your Day 1 review. - Did the agent catch things you missed? - Did the agent miss context you knew from the issue thread? -- Is the agent's tone aligned with the community standards from [Culture and Etiquette](docs/08-open-source-culture.md)? +- Is the agent's tone aligned with the community standards from [Culture and Etiquette](../docs/08-open-source-culture.md)? Edit the agent's output before posting any of it. Your name goes on it. @@ -310,9 +322,11 @@ The agents are running. Step away from the screen for five minutes. Screen reade ## Block 4 - GitHub Agentic Workflows -**14:00-15:00** +**2:15-3:00 PM Pacific** + +This block is stretch material. If participants need more time to draft, commit, or push their contribution, convert this block into supported lab time and assign the workflow overview as async reading. -> **Reference:** [GitHub Actions and Workflows](docs/appendix-q-actions-workflows.md) - read the "Day 2 Bridge" section at the bottom before this block. +> **Reference:** [GitHub Actions and Workflows](../docs/appendix-q-actions-workflows.md) - read the "Day 2 Bridge" section at the bottom before this block. ### The Cloud Extension: What Agentic Workflows Are @@ -385,7 +399,7 @@ Do not close the issue. Do not merge anything. Do not modify any files. ## Block 5 - Ship Your Contribution -**15:15-16:15** +**3:00-4:15 PM Pacific** ### Purpose Polish and submit your real pull request upstream to `community-access/accessibility-agents`. Not to your fork - to the original. This is the moment the product maker mindset becomes tangible. @@ -445,7 +459,9 @@ While your PR is awaiting review, review a forge partner's PR: ## Block 6 - Spec Kit: Design the Future -**16:15-17:00** +**4:15-4:40 PM Pacific** + +This block is optional when the contribution lab needs more time. For remote cohorts, it can become an async discussion thread where participants propose agent or project ideas after the live session. > **What is Spec-Driven Development?** It is the practice of writing the *intent* of a feature before anyone builds it. The specification becomes the source of truth - AI uses it to plan tasks, contributors use it to stay aligned, and the community uses it to evaluate whether the feature actually delivered what was intended. @@ -477,7 +493,7 @@ Speak your requirements aloud. The facilitator types them. Copilot helps convert ## Wrap-Up -**17:00-17:30** +**4:40-5:00 PM Pacific** ### The Moment: Find Your Name in History @@ -544,6 +560,6 @@ Day 2 has two peaks: Do not rush the wrap-up. The moment of seeing your name in a public commit history is one of the most meaningful things a first-time open source contributor experiences. -*Previous: [Notifications ←](docs/10-notifications-and-day-1-close.md)* -*Next: [VS Code: Setup & Accessibility Basics](docs/11-vscode-interface.md)* -*Related: [Day 1 Agenda](DAY1_AGENDA.md) | [GitHub Actions & Workflows](docs/appendix-q-actions-workflows.md) | [Resources](docs/appendix-x-resources.md)* +*Previous: [Notifications ←](../docs/10-notifications-and-day-1-close.md)* +*Next: [VS Code: Setup & Accessibility Basics](../docs/11-vscode-interface.md)* +*Related: [Day 1 Agenda](DAY1_AGENDA.md) | [GitHub Actions & Workflows](../docs/appendix-q-actions-workflows.md) | [Resources](../docs/appendix-x-resources.md)* diff --git a/admin/DAY2_QUICK_START.md b/admin/DAY2_QUICK_START.md index 659c43c..1b0d0f3 100644 --- a/admin/DAY2_QUICK_START.md +++ b/admin/DAY2_QUICK_START.md @@ -82,7 +82,7 @@ You do not need to complete those modules or practice files. If you already have ## What Happens When You Arrive -Day 2 Block 0 (9:00-9:30) includes time for Day-2-only participants to: +Day 2 Block 0 (9:00-9:30 AM Pacific) includes time for Day-2-only participants to: 1. Introduce yourself to the group 2. Verify your setup with a facilitator diff --git a/admin/FACILITATOR_CLASSROOM_TROUBLESHOOTING.md b/admin/FACILITATOR_CLASSROOM_TROUBLESHOOTING.md new file mode 100644 index 0000000..c6c32f6 --- /dev/null +++ b/admin/FACILITATOR_CLASSROOM_TROUBLESHOOTING.md @@ -0,0 +1,537 @@ +# GitHub Classroom Troubleshooting Guide +## For Facilitators Managing Student Workflows + +This document covers common issues that arise during GitHub Classroom workshops and how to resolve them quickly. Use this alongside [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md) for general facilitation. + +--- + +## 🚨 Emergency: What to Do When Everything Stops Working + +### Bots Stopped Responding + +**Symptom:** Students are creating PRs but Aria bot isn't commenting within 30 seconds. + +**Diagnostics:** +1. Check [GitHub Status](https://www.githubstatus.com) — is GitHub Actions down? +2. Check your test repo — try creating a PR yourself. Does Aria respond? +3. Check the workflow logs in the template repository: + - Go to your template repo → Actions tab + - Look for recent Aria workflow runs + - Do they show errors or successful completions? + +**Solutions:** + +| Issue | Fix | +|-------|---| +| **GitHub Actions is down** | Post in chat: "We're experiencing a brief delay with our automated feedback. You can still work on challenges — we'll review PRs manually." Then skip to "Manual PR Review" below. | +| **Aria workflow is disabled** | Go to template repo → Actions → Enable Aria workflow → Re-run failed runs | +| **Aria workflow has an error** | Check the error log. If it's a configuration issue, fix the workflow file and re-run. | +| **Aria is working but slow** | Wait a bit longer (sometimes takes 60 seconds). Refresh PR page. If still nothing, manually review. | + +**Temporary Workaround — Manual PR Review:** + +If the bot is down and you need to review PRs: + +1. Go to student's PR +2. Comment with this template (copy Aria's format): + ```markdown + Checking your work... + + ✓ [thing that's good] + ✓ [thing that's good] + + Consider: [suggestion] + Consider: [suggestion] + + Nice work! [personalized comment] + ``` +3. Students continue as normal (they don't know the difference) +4. When bot comes back, future PRs will get automatic feedback + +### Student Progression Bot Failed + +**Symptom:** Student merged a PR, but the next challenge didn't appear. They're stuck waiting for Challenge 2. + +**Diagnostics:** +1. Go to student's repo → Issues tab +2. Check if the old challenge is closed +3. Check if the new challenge exists (might be closed too) + +**Solutions:** + +| Symptom | Fix | +|---------|---| +| **Old challenge is open, new challenge doesn't exist** | Progression bot failed. Manually create the next challenge: Copy the old challenge issue, change the number, and assign to student. | +| **Both challenges exist but student can't see new one** | Refresh their browser or have them sign out/in. | +| **Old challenge never closed** | Manually close it (if student merged PR but it didn't auto-close). Then manually create the next challenge. | + +### Video Call Is Down + +**Symptom:** Zoom/Teams/Google Meet is disconnected. Students are isolated. + +**What to Do:** +1. **Don't panic** — GitHub Classroom work doesn't stop without the call +2. **Create backup**: Send message to any chat channel (email, GitHub Discussions): + > "Video call dropped temporarily. You can keep working on your challenges — we're working on reconnecting. Use [Discussions/email/Slack] if you need help in the meantime." +3. **Reconnect** — Get the call back up within 5 minutes if possible +4. **Continue async** — If can't reconnect, facilitate async through chat/email until next day + +### Co-Facilitator Is Unavailable + +**Symptom:** You're alone and need to: +- Monitor dashboard +- Answer chat questions +- Do a demo +- Review PRs +- Manage 20+ students + +**Solutions:** + +**Short-term (next 30 min):** +- Shift to async mode: "We're doing async today. Post questions in chat and I'll respond promptly." +- Use recorded demo if you have one +- Focus on responding to questions quickly rather than real-time facilitation + +**Mid-term (next few hours):** +- Recruit a volunteer: + - Advanced student + - TA or peer + - Anyone who can watch chat + - Give them these 3 jobs: (1) watch chat for "stuck" messages, (2) ping facilitator with blocking questions, (3) celebrate wins +- Put facilitator on mute except for key moments + +**Long-term:** +- Consider pausing until co-facilitator returns +- Or shift to fully asynchronous (post challenges, respond to questions async) + +--- + +## 👤 Student-Level Issues + +### "I Can't Find My Repo" + +**Student is logged in, accepted the assignment, but can't find their repo.** + +**First, clarify:** "Can you get to github.com? What do you see?" + +**Solution Flowchart:** + +``` +Q: Are you logged in? +├─ No → Have them log in +└─ Yes → Q: Do you see an organization name in your top-left? + ├─ No → They accepted but repo creation stalled + │ └─ Solution: Go to classroom.github.com, refresh the assignment + │ If still nothing, manually create repo in organization: + │ - Go to org + │ - Click "New repository" + │ - Name it: learning-room-[username] + │ - Use template + │ - Done + └─ Yes → Q: When you click your profile (top-right), + do you see "Your repositories"? + ├─ No → Permissions issue + │ └─ Solution: Go to github.com/settings/repositories + │ Filter by organization + │ Find your repo in the list + └─ Yes → They have repos but can't navigate + └─ Solution: Direct link: + github.com/community-access-classroom/learning-room-[username] + Share this link directly +``` + +### "The Issue Isn't In My Repo" + +**Student accepted assignment, but Challenge 1 issue doesn't exist.** + +**Causes:** +- Template repo doesn't have Challenge 1 issue +- Issue exists but in wrong place +- Student accepted but issue creation failed + +**Fix:** +1. Check template repo → Issues → Does Challenge 1 exist? + - If no: Create it in template, then re-create in student repo + - If yes: Go to step 2 +2. Go to student repo → Issues → Is Challenge 1 there? + - If no: Manually create it by copying from template + - If yes: Problem solved (they might not be looking in the right place) + +**Manual Creation:** +1. Student repo → Issues tab +2. Click "New issue" +3. Copy the Challenge 1 content from the template issue +4. Create it +5. Tell student: "Refresh your Issues page" + +### "I Don't Know What the Challenge Is Asking" + +**Student is confused about the task.** + +**First:** Read the challenge text back to them aloud. + +**Then:** Break it down: +- What is it asking me to change? [Tell them] +- Where is that in my repo? [Show them] +- How will I know when I'm done? [Tell them the success criterion] + +**Next:** Give them the first tiny step: +> "Start by [one specific action]. Do that, then come back and tell me what you see." + +**Don't:** +- Do it for them +- Overwhelm with the whole solution +- Use jargon without explaining + +### "The Bot's Feedback Doesn't Make Sense" + +**Student is confused by Aria bot comment.** + +**What the bot might say:** +``` +Consider: PR title should follow the pattern "Challenge X: [description]" +``` + +**What you say:** +> "Aria is asking you to change your PR title. Right now it says '[current title]'. +> Change it to 'Challenge 1: [something describing the change]'. +> Go back to your PR, click 'Edit' on the title, make the change, save." + +**Practice Translation:** +- Bot: "Markdown formatting issue" → You: "Your description has an extra space somewhere. Check for weird spacing." +- Bot: "File path incorrect" → You: "You edited the wrong file. Edit [correct filename] instead." +- Bot: "Branch naming convention" → You: "Your branch name should be [format], not [what they did]." + +### "I Merged But Challenge 2 Didn't Appear" + +**Student merged PR. Old issue closed. New issue missing.** + +**Causes:** +1. Progression bot is running late (just wait) +2. Progression bot failed +3. Student is looking in wrong place + +**Fix:** +1. Ask: "Refresh your Issues page. Do you see Challenge 2 now?" + - If yes: Problem solved + - If no: Go to step 2 +2. Manually create Challenge 2: + - Go to student repo → Issues + - Click "New issue" + - Copy Challenge 2 from template + - Create it + - Tell student: "Refresh and you should see it now" + +### "I Keep Getting an Error on PR Submit" + +**Student is trying to create PR but gets an error.** + +**Common errors:** + +| Error Message | Fix | +|---------------|---| +| "Nothing to commit" | They didn't make any changes. Have them edit the file first. | +| "Merge conflict" | This is actually a good learning moment. See "Merge Conflict" section below. | +| "Can't create branch" | Check branch naming. May need to delete failed branch and try again. | +| "Access denied" | Check repo permissions. Should be able to write to their own repo. | +| "File not found" | They're trying to edit wrong file. Help them find correct one. | + +**General troubleshooting:** +1. Have them refresh the repo +2. Have them close/reopen the file they're editing +3. Have them try a simpler edit (just one word) first +4. If still broken, escalate to facilitator manual review + +### "I'm Done — What's Next?" + +**Student finished a challenge and wants to continue.** + +**Options:** + +1. **Start the next challenge automatically:** + > "Close this challenge issue (click 'Close issue' at the bottom) and the bot will create the next challenge for you." + +2. **Help a peer:** + > "Great work! Could you review [peer's] PR? That's how real developers learn." + +3. **Explore bonus challenges:** + > "You can also try some bonus challenges if you want to go deeper." + +4. **Take a break:** + > "You've done great work. Take a break and come back when you're ready for the next one." + +--- + +## 🔄 Specific Technical Scenarios + +### Merge Conflict + +**What it is:** Two people edited the same file in incompatible ways. Git doesn't know which version to use. + +**When it happens:** Usually Challenge 7 or later in the workshop. + +**Student sees:** +``` +This branch has conflicts that must be resolved +``` + +**Your response:** +1. Don't panic — this is intentional (a learning challenge) +2. **Don't try to fix it over chat** — merge conflict resolution is hands-on +3. Do one of these: + - **Pair the student with someone who's done merge conflicts** → They learn from peer + - **Offer 1:1 help** → This is worth 20 minutes of your time (real skill) + - **Have them post in Discussions** → Someone can walk them through async + +**Teaching the fix:** +1. Go to the PR → click "Resolve conflicts" +2. GitHub shows the conflicting lines +3. The student picks which version is correct (or combines both) +4. Student marks conflict as resolved +5. Student completes merge +6. Done + +**Key point:** This is not a failure — this is GitHub's hardest challenge because conflicts ARE hard in real code. + +### Autograder Failed + +**What it is:** Challenge X has an automated test. Student's submission failed the test. + +**Student sees:** +``` +Autograding failed (X failed) +``` + +**Your steps:** + +1. Go to student repo → Actions tab +2. Find the failed autograding run +3. Click it → look at the test output +4. Understand what failed +5. Explain to student in plain language: + > "The test was checking for [thing]. You have [what they did]. Try [fix]." + +**Common test failures:** + +| Test | Usual Reason for Failure | +|------|---| +| File exists | File named wrong or in wrong folder | +| Content contains X | Text wasn't added; student edited wrong file | +| Markdown formatting | Extra spaces or wrong heading level | +| Git history | Wrong number of commits or wrong branch | + +**Next step:** Have student fix the issue and push a new commit. Autograder re-runs automatically. + +### Accidental Merge + +**What happened:** Two students somehow merged the same file / repo / change. + +**Student panics:** "I messed up!" + +**Your response:** +> "This happens in real GitHub all the time. We just undo it." + +**How to undo:** +1. Go to the merged PR +2. Look for "Revert this pull request" button +3. Click it +4. GitHub creates a new PR that reverses the change +5. Merge that PR +6. Done + +**Teaching moment:** Use this to explain why code review matters — this is why you have peers check your work. + +### Student Lost Their Work + +**Student says:** "I was working on something and it's gone now." + +**Possible causes:** +1. They edited in GitHub web editor (not saved) +2. They refreshed before saving +3. They closed browser +4. They're looking in wrong repo/branch + +**Your investigation:** +1. "What were you trying to change?" → You explain it +2. "Let's look at your repo" → You check it together +3. "Do you see a [branch/PR/draft]?" → Navigate together + +**If truly lost:** +1. "It's okay, let's start fresh" +2. Help them re-do the work +3. This time, save properly by creating PR (not just editing) + +**Prevention:** Teach students: "Always create a PR before you finish. That saves your work." + +--- + +## 🌐 GitHub Platform Issues (Not Your Fault) + +### GitHub.com Is Down + +**How to know:** You get an error like "502 Bad Gateway" when accessing any GitHub page. + +**What to do:** +1. Check [GitHub Status](https://www.githubstatus.com) +2. Post in chat: "GitHub.com is temporarily down. We're waiting for it to come back up. Keep your changes safe (don't refresh)." +3. Wait for GitHub to recover +4. Resume workshop + +**In the meantime:** Students can: +- Read challenge instructions offline +- Plan their approach +- Discuss with peers + +### GitHub Actions is Slow/Down + +**Symptom:** PRs are created but Aria bot takes 5+ minutes to respond. + +**What's happening:** GitHub's infrastructure is overloaded. + +**What to do:** +- Let students know: "Feedback bot is running a bit slow today. Don't refresh — it'll show up in a few minutes." +- Continue working while waiting +- If it doesn't show up, manually review (as described earlier) + +### Organization Is Having Permission Issues + +**Symptom:** Students can't create repos or write to repos. + +**Likely cause:** Organization settings changed accidentally. + +**Fix:** +1. Go to Organization Settings +2. Check "Member privileges" +3. Make sure members can create public/private repos +4. Check "Repository creation" is enabled + +--- + +## 📊 Dashboard & Monitoring Issues + +### Dashboard Shows Wrong Data + +**Symptom:** Classroom dashboard shows "0 PRs merged" but you know students merged things. + +**Cause:** Dashboard is cached or lagging behind. + +**Fix:** +1. Refresh the page +2. Wait a few minutes (GitHub's dashboard updates asynchronously) +3. Try incognito/private browser (clears cache) + +### Can't Access Classroom Dashboard + +**Causes:** +1. Not logged in +2. Organization didn't set up Classroom +3. Permissions issue + +**Fix:** +1. Go to https://classroom.github.com +2. Click "Sign in" +3. Select your organization +4. If not listed, go to organization settings and link GitHub Classroom + +### Missing Students in Dashboard + +**Symptom:** You know 30 people accepted the assignment, but dashboard shows only 25. + +**Cause:** Dashboard is lagging or those people haven't been processed yet. + +**Fix:** +1. Refresh +2. Wait 5 minutes +3. Check directly: Go to org → Repositories → Look for new repos manually + +--- + +## 🛠️ Facilitator Mistakes & Recovery + +### You Accidentally Closed the Wrong Challenge + +**You:** Closed Challenge 2 in a student's repo by mistake. + +**Recovery:** +1. Go to the repo +2. Find the closed challenge in the Issues tab (closed filter) +3. Re-open it +4. Apologize to the student: "My mistake — I reopened it. You're good to go." + +### You Created Duplicate Challenges + +**Symptom:** Student sees Challenge 2 twice. + +**Cause:** Manual creation while bot was also creating it. + +**Fix:** +1. Go to student repo +2. Close/delete the duplicate +3. Tell student: "Cleaned that up. You should see one Challenge 2 now." + +### You Merged Something You Shouldn't Have + +**You:** Accepted and merged a PR meant for a student to merge. + +**Recovery:** +1. Revert the PR (see "Accidental Merge" section) +2. Apologize: "I shouldn't have done that — I reverted it. Your merge is what counts." +3. Have student re-merge it (they'll get the learning) + +--- + +## 🎯 Prevention Strategies + +### Before Workshop Even Starts + +- [ ] Test everything with your co-facilitator +- [ ] Try breaking things intentionally to know how to fix them +- [ ] Document the fixes in your notes +- [ ] Create a shared "if this then that" troubleshooting doc with your co-facilitator + +### During Workshop + +- [ ] Monitor dashboard constantly (not just when someone asks for help) +- [ ] Catch small issues before they become big ones +- [ ] Celebrate successful workflows ("You're doing this perfectly!") +- [ ] Keep a running log of issues that came up so you can add to this guide next time + +### Post-Workshop + +- [ ] What issues came up? Add them to this guide. +- [ ] What took longer than expected? Update timelines. +- [ ] What automation failed? Document the fix. +- [ ] What did facilitators do well? Keep doing it. + +--- + +## 📞 When to Escalate + +**Escalate to:** GitHub Support, your organization admins, or external help when: + +- [ ] GitHub itself is broken (Actions down, authentication issues, data loss) +- [ ] Something is broken in the template repository (not a student issue) +- [ ] You don't know how to fix it and neither does your co-facilitator +- [ ] A student's entire repo is corrupted +- [ ] Security issue (someone got access they shouldn't have) + +**Don't escalate for:** Issues described in this guide. You can handle them. + +--- + +## 💪 You've Got This + +Most issues in this guide have happened to facilitators before. You're not the first and won't be the last. + +Key principles: +1. **Stay calm** — The students are watching. If you're calm, they're calm. +2. **Explain out loud** — "Here's what I think is happening... let's check..." +3. **Don't pretend to know** — "I'm not sure. Let's figure this out together." +4. **Celebrate the fix** — "And we solved it! That's what debugging is." +5. **Learn for next time** — Note it so you're faster next time + +Every issue you solve is a story you'll tell at the next workshop. + +--- + +**Last Updated:** May 2026 | **Version:** 1.0 | **Maintainer:** Jeff Bishop diff --git a/admin/FACILITATOR_GUIDE.md b/admin/FACILITATOR_GUIDE.md index fe05f4f..cd0967b 100644 --- a/admin/FACILITATOR_GUIDE.md +++ b/admin/FACILITATOR_GUIDE.md @@ -1,7 +1,827 @@ -# Facilitator Guide +# The Complete Facilitator Guide +## Running GitHub Classroom Workshops for Blind and Low-Vision Students -> **This file has moved.** The complete Facilitator Guide is now at [facilitator/FACILITATOR_GUIDE.md](../facilitator/FACILITATOR_GUIDE.md). +This is your comprehensive guide to facilitate a two-day GitHub workshop. It covers everything from initial GitHub Classroom setup through post-workshop follow-up, with special attention to accessibility and student success in an open-enrollment environment. -For challenge management, see [FACILITATOR_CHALLENGES.md](FACILITATOR_CHALLENGES.md). +--- -For workshop deployment, see [classroom/README.md](../classroom/README.md). +## 🎯 Quick Navigation + +- **Just starting?** → Go to [GitHub Classroom Setup](#-github-classroom-setup-before-day-1) +- **Workshop is tomorrow?** → Go to [Pre-Workshop Checklist](#-pre-workshop-checklist-48-hours-before) +- **Workshop is happening now?** → Go to [Live Workshop Operations](#-day-1-live-operations) +- **Student got stuck?** → Go to [Troubleshooting Guide](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) +- **Need hands-on details?** → Go to [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) + +--- + +## About This Workshop + +**What:** A two-day hybrid workshop where blind and low-vision students learn GitHub through hands-on collaboration. + +**Who:** You're facilitating for students with varying GitHub experience (zero to intermediate). You won't know ahead of time exactly who will join. + +**Where:** Hybrid — video call + individual GitHub Classroom repositories. + +**Why It Matters:** GitHub is a critical skill for modern tech careers. This workshop makes GitHub accessible through: +- Hybrid delivery (people can join sync or async) +- Individual private repos (safe practice space) +- Automated feedback (Aria bot) +- Progressive challenges (no overwhelming leaps) +- Peer community (students help each other) + +**Main Goal:** Every student merges their first pull request and experiences successful collaboration. + +--- + +## 👥 Your Facilitation Team + +This workshop is designed for **2 co-facilitators** who can split roles: + +- **Lead Facilitator** -- Owns messaging, demos, and orchestration +- **Co-Facilitator** -- Monitors chat, watches dashboard, helps individuals + +If you're solo: +- Recruit a volunteer (TA, peer mentor, or co-instructor) +- Pre-record demos for asynchronous watching +- Use GitHub Discussions more heavily for async Q&A + +--- + +## 🚀 GitHub Classroom Setup (Before Day 1) + +This section is for someone (probably you!) setting up GitHub Classroom for the first time. If your Classroom is already configured, skip to [Pre-Workshop Checklist](#-pre-workshop-checklist-48-hours-before). + +### What is GitHub Classroom? + +GitHub Classroom is a free service that automatically creates private repositories for students. When a student clicks an invite link, GitHub Classroom: +1. Creates a repo from your template +2. Assigns it to that student +3. Sets permissions (student owns it, you can see it) +4. Returns them to their new repo + +You get a dashboard showing all students' progress without manual intervention. + +### Prerequisites + +Before setting up Classroom, you need: + +- A GitHub Organization (free plan works) — used to hold student repos + - Create at https://github.com/organizations/new (or use existing one) + - Add both facilitators as owners +- At least one template repository in that organization + - Template includes: Challenge 1 issue, PR template, README + - See [classroom/README.md](../classroom/README.md) for template structure +- GitHub Classroom is linked to your organization (automatic if you're an org owner) + +### Step 1: Create Your First Assignment in GitHub Classroom + +1. Go to https://classroom.github.com +2. Click "New Classroom" +3. Select your Organization +4. Give it a name: `learning-room-day1` (or similar) +5. Click "Create" + +### Step 2: Add Your Co-Facilitator + +1. In the new classroom, click "Settings" +2. Under "Organization admins," add your co-facilitator's GitHub username +3. Save + +### Step 3: Create Your First Assignment + +1. Click "New Assignment" +2. Enter title: `Day 1: GitHub Basics` +3. Select "Individual" (not group) +4. Under "Add your starter template repository," select your template repo +5. Under "Add auto-grading tests," skip this for Day 1 (optional for later challenges) +6. Click "Create assignment" +7. **Copy the invite link** and save it somewhere safe + +This link is what you'll share with students. It never expires. + +### Step 4: Create Your Second Assignment (for Day 2) + +Repeat Step 3 but title it `Day 2: Advanced Skills` + +Save both invite links in a safe place (notes, email yourself, password manager). + +### Step 5: Test the Automation + +1. Accept your own invite link (as if you were a student) +2. You should be asked to select your name from the roster +3. GitHub Classroom creates a repo for you +4. Verify: + - Challenge 1 issue exists in your repo + - Aria bot is configured (check Actions tab) + - Student Progression bot can create new issues when you close one +5. Test creating and merging a PR to ensure: + - Aria bot comments within 30 seconds + - Merging closes the issue + - Next challenge issue appears + +If anything is missing, see [Troubleshooting GitHub Classroom Setup](#troubleshooting-github-classroom-setup) below. + +### ⚠️ Known Gotchas + +**"The invite link isn't working"** +- Make sure your Organization is created +- Make sure the assignment is published (green checkmark in Classroom) +- Make sure students have GitHub accounts (free account works) + +**"No one in my organization can accept the invite"** +- Students don't need to be org members +- They just need a GitHub account +- If issue persists, check if Classroom link was copied correctly + +**"Aria bot isn't commenting on PRs"** +- Verify Aria bot is installed in your Organization (Settings > GitHub Apps) +- Check if the Actions workflow is enabled in the template repo +- Manually test a PR in your test repo + +**"I created a second assignment but can't see an invite link"** +- Assignments don't have individual invite links +- Use the **classroom-wide** invite link and let students select which assignment +- Or create separate Classrooms for Day 1 and Day 2 + +--- + +## 📋 Pre-Workshop Checklist (48 Hours Before) + +You have two days until the workshop. Use this checklist: + +### 72 Hours Before: Communication Sent + +- [ ] Email sent to all registered students with: + - Exact workshop date/time with time zone + - Video call link + audio-only dial-in option + - "Please test your setup 1 hour before start time" + - FAQ link (see Appendix A) + - Your emergency contact info + - Screen reader accessibility note: "We've tested this with NVDA, JAWS, and VoiceOver" + +### 48 Hours Before: Infrastructure Verified + +- [ ] GitHub Classroom created with both Day 1 and Day 2 assignments +- [ ] Invite links copied and ready to share +- [ ] Template repo has Challenge 1 issue (will auto-create for each student) +- [ ] Your test student repo exists (you accepted invite to test) +- [ ] Aria bot installed and tested (posted to a PR, bot replied) +- [ ] Student Progression bot works (closed an issue, new challenge appeared) +- [ ] Both facilitators have admin access to the Classroom + +### 24 Hours Before: Final Dry Run + +- [ ] You've sent the invite link to someone as a test +- [ ] That person accepts and a repo is created successfully +- [ ] Check the Classroom dashboard: the test student shows up +- [ ] You can see their repo from the dashboard +- [ ] Video call link and audio dial-in tested +- [ ] Facilitator chat/question channel ready (Slack, Discord, GitHub Discussions, etc.) +- [ ] Any visual slides or demos have been tested for screen reader compatibility + +### 6 Hours Before: Day-Of Setup + +- [ ] GitHub Classroom dashboard open and logged in on facilitator computer +- [ ] Student roster visible on a second monitor (or open in a tab) +- [ ] First demo script ready (should be memorized, not read) +- [ ] Chat moderator assigned to their role +- [ ] Backup plan ready if: + - Video call has tech issues (phone dial-in number active) + - Bot stops working (you'll manually review PRs) + - Key facilitator unavailable (co-facilitator can lead) +- [ ] Coffee/water ready 😄 + +--- + +## ✨ Day 1: Live Operations + +This section covers what you and your co-facilitator do during Day 1. + +### Hour 1: Welcome and GitHub Orientation (60 min) + +**What's Happening:** Students are joining the call for the first time. They're nervous. Your job is to make them feel welcome and get them oriented to their GitHub repos. + +#### Your Opening (First 5 Min) + +Say something like: + +> "Welcome everyone! I'm [name], and I'm so glad you're here. This is a completely accessible workshop — we've tested everything with screen readers, and if something breaks or doesn't work for you, please tell us immediately. +> +> Today we're learning GitHub, and in the next two days, every single one of you is going to merge your first pull request. That might not sound like a big deal, but it IS — it means you've collaborated with another person to improve code. That's a real developer skill. +> +> We're hybrid, so you can work at your own pace. Some of you will finish fast, some will take your time, and both are completely fine. +> +> Questions? Ask in chat anytime. That's what we're here for." + +#### Your First Task: Get Everyone Into Their Repos + +1. **Share the Day 1 invite link** in chat +2. Say: "I'm giving you a link to create your private GitHub repo. Click it and GitHub will ask you to pick your name from a list. Go ahead and do that now." +3. Give them 5 minutes +4. Check the GitHub Classroom dashboard for incoming acceptances +5. **Celebrate:** "Great! I see people joining. When you accept, GitHub creates your repo automatically. You should see a Challenge 1 issue waiting for you. Find it in your Issues tab." +6. In chat: "Raise your hand (type in chat) when you see Challenge 1" +7. When 70%+ have confirmed: "Perfect! Everyone has their Challenge 1. Let's look at what you're going to do." + +#### Demo: Show a Challenge 1 + +1. **Open your test student repo** on screen +2. **Narrate out loud** what you're seeing: + > "I'm going to click the Issues tab... I see Challenge 1 here. It has a description of what I need to do. At the bottom there's a 'If You Get Stuck' section. If anything is confusing, that's where to start." +3. Read the challenge text aloud (slowly) +4. Ask in chat: "Does everyone see something similar in your Challenge 1? Say yes in chat" +5. Help anyone who doesn't see it: + - "Go to your repo page" + - "Click the Issues tab" + - "You should see a list; click the one that says Challenge 1" + +**Success Metric:** Everyone has confirmed they can see Challenge 1. + +### Hour 2: Demo — Your First Pull Request (30 min) + +**What's Happening:** You're showing students the exact workflow they'll repeat for every challenge. Make it crystal clear. + +#### Your Narrated Demo + +Open a challenge in your test repo and **narrate every single step**: + +> "Okay, I'm going to do Challenge 1 right now, and you're going to watch me do it. I'm going to talk through every click so you know exactly what to do when it's your turn. +> +> **Step 1: Read the challenge** +> I'm looking at the Challenge 1 issue. It says [read it]. Okay, so I need to [summarize task]. Got it. +> +> **Step 2: Start editing** +> I see there's a file I need to edit. I'm going to find it in the file list and click the pencil icon to edit it. [Click pencil] +> Now I'm in the editor. I can see the current text. I need to [describe what to change]. +> +> **Step 3: Make my change** +> [Type the change while narrating] +> Okay, I've made my change. Now I need to create a pull request to propose this change. +> +> **Step 4: Create a pull request** +> I'm scrolling down to find the 'Propose changes' button. [Click it] +> GitHub is now asking me if I want to create a new branch. Yes, I do. [Click 'Create a new branch'] +> Now I see the PR comparison page. It shows my old version and my new version. +> +> **Step 5: Fill out the PR form** +> I'm clicking the 'Create pull request' button [click] +> Now I see a form with fields like title and description. There's a PR template here that helps me know what to fill in. +> [Fill out form while narrating each field] +> +> **Step 6: Submit the PR** +> I'm clicking the green 'Create pull request' button [click] +> Done! The PR is created. +> +> **Step 7: Wait for Aria bot feedback** +> Watch what happens next... Aria bot checks my work automatically. +> [Wait 30 seconds] +> See? The bot commented with feedback. It's checking if my change follows the rules. +> +> **Step 8: Address feedback (if any)** +> If the bot found an issue, I would go back and fix it. But my change looks good, so I'm ready to request a review. +> +> **Step 9: Request a review** +> I'm typing @[another student] in a comment to ask them to review my PR. +> [Wait for their response in real life] +> My peer approved it, so now I can merge. +> +> **Step 10: Merge the PR** +> I'm clicking the 'Merge pull request' button [click] +> Done! The PR is merged. The issue closes automatically. +> +> **Step 11: See your next challenge** +> Watch — because the bot closes the Challenge 1 issue when I merged, the next challenge will appear automatically... +> [Refresh Issues tab] +> There it is! Challenge 2 just appeared. That's how progression works." + +#### Key Teaching Points + +- **Don't rush** — students are taking notes +- **Narrate actions before doing them:** "I'm going to click the edit pencil now..." [then click] +- **Normalize mistakes:** "Oops, that's not the right button. Let me click over here instead." +- **Stop and ask:** "Does everyone see what I'm seeing? Type yes in chat." +- **Celebrate:** "This workflow — read issue → edit → propose changes → request review → merge — you're going to do this same thing 15 times over two days. You're going to be amazingly good at it." + +**Success Metric:** Students say things like "I see how this works" or "That was clear" in chat. + +### Hours 3-6: Supervised Working Session (Approximately 4.5 Hours) + +**What's Happening:** Students are working on their challenges while you monitor and help. + +#### Your Role During This Time + +**Primary:** Monitor the GitHub Classroom dashboard + +- Refresh it every 5-10 minutes +- Look for: + - New commits (student is active) + - PRs being created (they're progressing) + - Autograding failures (might need help) + - Students with zero activity (might need a nudge) + +**Secondary:** Be responsive in chat and comments + +When you notice something: + +1. **Student hasn't started after 20 min** → Chat message: + > "Hey @student! How's it going? Found your Challenge 1? If you need a hint, just ask in chat." + +2. **Student created a PR** → Check it + - Did Aria bot comment? + - Does the student understand the feedback? + - Comment if needed: "Looking good! I see the bot asked you to [X]. Give that a try!" + +3. **Student merged a PR** → Celebrate publicly: + > "🎉 Awesome work @student! You just merged your first pull request! That's huge." + +4. **Aria bot gave confusing feedback** → Translate it: + > "I see Aria's feedback. Let me explain what it means: [plain language explanation]. Try [specific fix]." + +5. **Student is stuck and says so** → Help them + - Look at their repo + - Read the "If You Get Stuck" section of their challenge + - Comment: "I see where you're stuck. Try [specific step]. Let me know how it goes!" + +#### Expected Rhythm + +| Time | What to Expect | +|------|---| +| **Min 1-15** | Students opening PRs on their first challenge | +| **Min 15-30** | Aria bot feedback flowing; students starting fixes | +| **Min 30-60** | First reviews happening; students requesting merges | +| **Min 60-120** | Early merges happening; progression bot creating Challenge 2 | +| **Min 120-180** | Second wave of PRs; momentum building; some finishing Challenge 2 | +| **Min 180-270** | Mixed activity: some on Challenge 3+, others still on Challenge 1, all valid | + +#### Facilitator Interventions + +**If a student says "I don't understand this challenge":** +1. Read the challenge text back to them +2. Break it into smaller steps +3. Give one next step: "Try [this specific thing] first" +4. Offer to look at their repo: "Send me the link and I'll take a look" + +**If a student says "I'm done, what do I do next?":** +- **Option A:** "Start Challenge 2 (it will appear automatically when the bot processes)" +- **Option B:** "Can you review someone else's PR? That helps them and teaches you code review" +- **Option C:** "Help a peer who's still working. Teaching others is real learning" + +**If Aria bot stops responding:** +1. Check [GitHub Actions status page](https://www.githubstatus.com) +2. If it's down, post in chat: "We're experiencing a brief delay with our feedback bot. We're looking into it." +3. Manually review PRs and post feedback in Aria's format (see [Troubleshooting](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md)) + +**If two students want to peer review:** +- Perfect! Encourage it. That's the whole point. +- Remind them: "Click the 'Files changed' tab to see the code. Leave thoughtful comments." + +#### Managing Energy + +- Every 60 minutes: "Quick break everyone. Stand up, stretch, grab water." +- Answer the same question multiple times without sighing +- Celebrate effort, not just finished work: "Nice debugging work!" (even if they haven't finished) +- If energy is low: "We're doing amazing. Look at how many PRs have been merged!" + +### Hour 7: Q&A and Reflection (30 min) + +**What's Happening:** You're wrapping up Day 1, celebrating progress, and setting up for Day 2. + +#### Reflection Prompt + +Ask in chat or video: + +> "Tell us in chat: What was one thing you learned today about GitHub? Or what surprised you?" + +Listen and affirm: + +- "GitHub is [student answer]" ✓ +- "Peer review helps [student answer]" ✓ +- "I struggled with [thing] but I figured it out" ✓ **CELEBRATE THIS** + +#### Share Day 1 Stats + +Pull from the Classroom dashboard: + +> "Today, X students joined, Y PRs were merged, Z students completed multiple challenges. That's real progress. You all should be proud." + +#### Troubleshoot Remaining Issues + +- Students still stuck: "We can help you after this call. Don't leave without asking." +- Questions about tomorrow: "Tomorrow we'll do deeper work. Same process, harder challenges." +- Access issues: "If you have anything that didn't work for your screen reader, email us. We fix it before tomorrow." + +#### Send Them Off + +> "Great work today! Rest well. Tomorrow we go deeper. See you at [time]!" + +### Hour 8: Optional Office Hours (60 min) + +- Stay available in chat or on call +- Help any student who wants to: + - Finish their first PR + - Start Challenge 2 + - Ask follow-up questions + - Troubleshoot issues + +--- + +## 🎉 Day 2: Deeper Skills and Celebration + +### Hour 1: Recap and Momentum (30 min) + +**What's Happening:** Students join fresh. You remind them of their progress and introduce Day 2 assignment. + +#### Your Opening + +> "Welcome back! Let me tell you what you did yesterday... +> +> X students completed Challenge 1 and merged their first PR. That's huge. +> Y students are already on Challenge 2 or beyond. +> Z students are working async and will finish today. +> +> That means you all know: +> - How to navigate GitHub +> - How to edit and create a PR +> - How to request a review +> - How to merge a PR +> +> You did that in one day. That's amazing. +> +> Today we go deeper. New challenges, more complex scenarios, and you're all ready for it." + +#### Day 2 Assignment + +1. **Share the Day 2 invite link** in chat +2. Say: "Click this link and accept Day 2 assignment. It's separate from Day 1." +3. Give them 5 minutes +4. Check the Classroom dashboard +5. When most have accepted: "Perfect! Challenge 10 is waiting for you. This one is a step up in difficulty. You've got this." + +### Hour 2: Code Review Deep Dive (60 min) + +**What's Happening:** You're teaching the skill of reviewing someone else's code professionally. + +#### Demo: How to Review a PR + +1. **Open a student's PR** from yesterday (ask permission or use your test repo) +2. **Narrate while reviewing:** + > "Okay, someone asked me to review their PR. Here's what I do: + > + > **Step 1: Read the description** — What are they changing and why? [read it] + > + > **Step 2: Click 'Files changed'** — Now I see the code diff. Red means removed, green means added. [click and show] + > + > **Step 3: Read the code carefully** — Does it make sense? Is it following the guidelines? [read and comment] + > + > **Step 4: Leave feedback** — I click the comment button next to lines I have thoughts about. [click] + > + > **Step 5: Be specific and kind** — Instead of 'this is wrong,' I say 'I notice this could be [better]. Consider [suggestion].' + > + > **Step 6: Approve or request changes** — At the top, I click 'Approve' if I'm happy with it, or 'Request changes' if I want fixes." + +#### Pair Review Activity + +1. Assign pairs: "Student A, you review Student B's PR. Student B, you'll review Student C's. Etc." +2. Give them a template for feedback: + ``` + - What I liked about this PR: [specific thing] + - One question I have: [genuine question] + - One suggestion: [improvement idea] + ``` +3. Give them 20 minutes to do reviews +4. Check back and celebrate: "I see great comments happening!" + +### Hours 3-7: Progressive Challenges (Approximately 4.5 Hours) + +**What's Happening:** Students are working through Challenges 10-16, which are harder and more realistic. + +#### Challenge Progression Map + +| Track | Challenges | Topics | Expected Time | +|-------|---|---|---| +| **Core** | 10-13 | VS Code, Git locally, branching, conflict resolution | 4-6 hrs | +| **Advanced** | 14-16 | Issue templates, fork-and-contribute workflow, capstone | 6-8 hrs | +| **Bonus** | bonus-a through bonus-e | CLI, search, branch protection, cloud editors | 2-4 hrs each | + +Students don't see challenges that aren't unlocked yet. The progression bot unlocks them when challenges are closed. + +#### Your Facilitation During Hour 3-7 + +**Dashboard monitoring:** Every 10 minutes, check: +- Who's on which challenge +- Any students still on Challenge 10 (might need help) +- Any autograding failures +- Recent merges (celebrate them) + +**Proactive help:** +- Students on Challenge 14+ → Extra encouragement: "You're getting into real developer territory!" +- Students still on Challenge 10-12 → Gentle check-in: "How's it going? Stuck on anything?" +- Peer reviews → Encourage more: "I see reviewers doing great work!" + +**Responsive help:** +- Student asks "What's Git?" → Explain clearly, add to a running glossary +- Student's PR has autograder failure → Check what test failed, help them debug +- Student at same place as another → Suggest they collaborate: "You two are both on Challenge 11 — want to pair?" + +#### Managing Different Paces + +**Faster students (on Challenge 14+):** +- Give them bonus challenges to explore +- Invite them to help peers +- Recognize their ambition: "You're flying through these!" + +**Average pace students (on Challenge 11-13):** +- Keep them engaged with encouragement +- Help when they hit roadblocks +- Celebrate steady progress + +**Slower pace students (still on Challenge 10-12):** +- NO pressure — this is fine +- Check if they need help or prefer async +- Offer 1:1 support after main session +- Include them in celebrations: "X students working on foundational skills" + +#### Key Facilitator Moves + +1. **Answer the same question multiple ways** — someone will finally get it +2. **Celebrate effort** — "I see you troubleshooting that error. That's exactly what real developers do." +3. **Normalize struggle** — "Everyone gets stuck. That's where learning happens." +4. **Bridge knowledge gaps** — If someone doesn't know Git, teach it briefly, add to resources +5. **Keep energy positive** — Day 2 is harder; your enthusiasm carries them + +### Hour 7: Final Q&A and Celebration (60 min) + +**What's Happening:** You're wrapping up the two-day journey, celebrating progress, and sending students off with confidence. + +#### Pull the Dashboard Data + +From GitHub Classroom, collect: + +- Total students enrolled +- Total students who merged at least one PR +- Total PRs merged (all challenges combined) +- Fastest student (by PRs merged) +- Students who completed code review cycle +- Students who made it to advanced challenges +- Students still actively working (will continue async) + +Say something like: + +> "Over two days, we had X students join. Here's what we accomplished: +> - Y students merged their first PR +> - Z total PRs were merged — that's real code changes +> - N students made it to advanced challenges +> - Everyone who's here learned something new about GitHub +> +> That's incredible. You should all be proud." + +#### Celebrate Specific Wins + +Call out individuals by name (with permission): + +> "@student1 — you merged 5 PRs! That's impressive velocity." +> "@student2 — you helped three peers debug their code. That's mentorship." +> "@student3 — you hit Challenge 15 on day 2. You went deep." + +#### Next Steps Guidance + +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 +> 4. **Build something** — Use GitHub as your project portfolio" + +#### Share Resources + +Point to: +- [CONTRIBUTING.md](../CONTRIBUTING.md) — How to contribute to open source +- [docs/](../docs/) — All the reference guides +- Alumni community link +- Your contact info for questions + +#### Thank You Note + +> "Thank you for being here, for asking great questions, for helping each other, and for giving GitHub a real try. The fact that you're learning this skill — that you know GitHub — that matters. Use it well. +> +> We're so glad you were here." + +### Hour 8: Informal Hangout / Office Hours (60 min) + +- Keep call open for students who want to: + - Continue working (keep dashboard accessible) + - Chat with peers + - Ask final questions + - Exchange GitHub usernames / social +- Optional: Have facilitators available in chat for async follow-ups + +--- + +## 📊 Post-Workshop Tasks (Week After) + +### Day 3 (Next Day) + +- [ ] Export GitHub Classroom dashboard data + - Total students, PRs merged, challenges completed + - Save as CSV or screenshot +- [ ] Identify students who are stuck/need follow-up + - Email them: "You're doing great! Need any help finishing?" +- [ ] Document any automation failures + - If Aria bot or progression bot had issues, log them for your next setup +- [ ] Thank your co-facilitator + - Debrief on what went well and what to improve + +### Days 4-7 + +- [ ] Send personalized email to each student + - Reference something specific they accomplished + - Point them to next resource (alumni channel, open source guide) + - Leave door open for questions +- [ ] Update your facilitator notes + - What questions came up most? + - What accessibility issues appeared? + - What challenges took longer than expected? +- [ ] Invite students to alumni community + - Slack / Discord / GitHub Discussions channel + - Encourage them to stay in touch and help future students + +### Weeks 2+ + +- [ ] Monitor alumni community + - Answer questions + - Celebrate project shares + - Offer 1:1 mentorship if interested +- [ ] Prepare for next cohort + - Update facilitator guide based on learnings + - Update challenge content based on student feedback + - Test GitHub Classroom automation again + +--- + +## 🆘 Quick Troubleshooting Reference + +### During Workshop + +**"I can't see my GitHub repo"** +→ Have them go to github.com/settings/repositories and look for repo with their name +→ Or share the direct link: community-access-classroom/learning-room-[username] + +**"The bot didn't comment on my PR"** +→ Refresh the page +→ Wait 30 seconds (bot takes a bit) +→ If still nothing, manually review and comment with feedback + +**"I merged but Challenge 2 didn't appear"** +→ Refresh their issues page +→ If still nothing, manually create Challenge 2 issue (copy Challenge 1, change number) + +**"Two students merged the same PR by accident"** +→ No problem! It happens in real GitHub too. +→ Revert the merge: "Revert this PR" button +→ 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 +→ Students can continue async + +For more, see [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) + +--- + +## 📚 Appendices + +### Appendix A: Facilitator Communication Templates + +**Pre-Workshop Email** + +Subject: Your GitHub Workshop Starts Tomorrow! + +> Hi [Name], +> +> We're excited to have you join us tomorrow at [TIME] for our two-day GitHub workshop! +> +> **Quick checklist:** +> - GitHub account created? (Go to github.com) +> - Can you join the video call? (Link: [URL]) or dial audio-only: [NUMBER] +> - Do you have a screen reader installed? (NVDA, JAWS, or VoiceOver work great with GitHub) +> +> **Tomorrow's plan:** +> - Hour 1: Welcome and GitHub orientation +> - Hour 2: Demo of your first PR +> - Hours 3-6: You work on challenges, we help +> - Hour 7: Q&A and celebration +> +> **If you have questions before we start:** Email us or chat us — we're here to help! +> +> See you tomorrow! + +**"Student is Stuck" Response** + +> Hi @[Name], +> +> I see you working on Challenge [X]. Let me help. +> +> The challenge is asking you to [rephrase in plain language]. +> +> Here's the next step: [ONE specific thing to do] +> +> Try that and let me know how it goes! + +**Post-Workshop Thank You** + +> Hi [Name], +> +> Thank you so much for joining our GitHub workshop! I wanted to reach out and tell you what an awesome job you did. +> +> You merged [X] pull requests and worked through [Y] challenges. That shows real growth. +> +> I especially appreciated when you [specific moment they did well]. +> +> **Keep learning:** +> - Check out [CONTRIBUTING.md](../CONTRIBUTING.md) for contributing to open source +> - Join our alumni community: [LINK] +> - Email if you have any GitHub questions — we're here +> +> Great work, and keep building! + +### Appendix B: Screen Reader Quick Reference + +**For NVDA Users:** +- `Insert + Down Arrow` — Read all +- `H` — Jump to next heading +- `Tab` — Jump to next button/link +- `F` — Jump to next form field +- `A` — Jump to next button or clickable element + +**For JAWS Users:** +- `Insert + Down Arrow` — Read all +- `H` — Jump to next heading +- `Tab` — Jump to next button/link +- `R` — Jump to next form field +- `B` — Jump to next button + +**For VoiceOver (Mac) Users:** +- `VO + Down Arrow` — Read continuously +- `H` — Jump to next heading +- `Tab` — Jump to next button/link +- `F` — Jump to next form field + +**GitHub.com Keyboard Shortcuts (Most Important):** +- `T` — Open file finder +- `I` — Jump to Issues +- `P` — Jump to Pull requests +- `G` then `C` — Go to Code +- `?` — Show all keyboard shortcuts + +### Appendix C: Common Challenge "If You Get Stuck" Phrases + +*These are used in each challenge issue. Paste them into challenge issues to guide stuck students:* + +**For editing challenges:** +> If you get stuck: Look for the pencil icon (✏️) to edit the file. Type your change, then scroll down and click "Propose changes." + +**For PR challenges:** +> If you get stuck: Don't refresh the page yet! GitHub is still processing. Wait 30 seconds. If still nothing, paste this link in chat: [direct link to PR] + +**For review challenges:** +> If you get stuck: Click the "Files changed" tab on the PR. Click the comment bubble next to lines you want to comment on. Type your feedback and click "Comment." + +**For merge conflicts:** +> If you get stuck: This is the hardest challenge because merge conflicts are tricky in real life too. Post your question in chat — this is not something to figure out alone. + +--- + +## 💡 Philosophy and Final Thoughts + +This workshop succeeds because of **you** — the facilitator. Here's what you bring: + +- **Patience** — Answer the same question 10 times without frustration +- **Clarity** — Explain complex things in simple language +- **Celebration** — Make everyone feel like their progress matters (it does) +- **Accessibility** — Test everything with screen readers, adapt for each student +- **Humanity** — You're not perfect, and that's okay. Normalize mistakes. +- **Community** — Build an environment where students help each other + +You're not just teaching GitHub. You're teaching inclusion — showing students that tech spaces can and should be accessible to everyone, including blind and low-vision people. + +Every student who merges their first PR is a student who now knows they belong in tech. + +That's the real goal. Everything else follows from that. + +--- + +## 📞 Need Help? + +If something goes wrong: + +1. **Automation failing?** → See [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) +2. **Student having issues?** → See [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) +3. **Setting up for first time?** → Scroll back to [GitHub Classroom Setup](#-github-classroom-setup-before-day-1) +4. **Can't find what you need?** → Email or ping us — we'll help and update this guide + +--- + +**Last Updated:** May 2026 | **Version:** 2.0 | **Maintainer:** Jeff Bishop diff --git a/admin/FACILITATOR_OPERATIONS.md b/admin/FACILITATOR_OPERATIONS.md new file mode 100644 index 0000000..ba7952a --- /dev/null +++ b/admin/FACILITATOR_OPERATIONS.md @@ -0,0 +1,579 @@ +# Facilitator Operations Guide +## Real-Time Workshop Management Procedures + +This guide provides step-by-step procedures for facilitators during the workshop. Use this alongside [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md) for the big picture and [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) for problem-solving. + +--- + +## Pre-Workshop Setup (3 Hours Before) + +### Facilitator Workstation Setup + +**Physical Setup:** +- [ ] Primary monitor: GitHub Classroom dashboard +- [ ] Secondary monitor (or browser tab): Student repo template / demo repo +- [ ] Laptop: Video call software tested +- [ ] Phone: Audio dial-in number saved +- [ ] Notepad: For tracking student issues in real-time +- [ ] Water/coffee within reach +- [ ] Noise-canceling headphones (optional but helpful) + +**Software Setup:** +- [ ] GitHub Classroom dashboard open and logged in + - URL: https://classroom.github.com + - Bookmark this for quick access +- [ ] Test student repo open in a tab (your repo you created during setup) +- [ ] GitHub Discussions / chat channel open +- [ ] Timer or stopwatch ready (for tracking session times) +- [ ] Email client visible (for student emails) + +**Communication Setup:** +- [ ] Co-facilitator has your phone number +- [ ] You have their phone number +- [ ] Both have chat channel open +- [ ] Backup communication method agreed on (Slack, Discord, etc.) + +### Dashboard Orientation + +Open [classroom.github.com](https://classroom.github.com): + +1. **Click your classroom** → You see: + - Assignment name + - Number of students who've accepted + - List of all students + their repo status + - Recent commit activity + +2. **Key columns to watch:** + - ✓ Accept status — Click to see if student repo was created + - Last commit time — When they last pushed code + - Autograding status — Pass/fail on any tests + +3. **Filter by status:** + - Accepted → Students who have repos + - Pending → Students who haven't accepted yet (you might need to follow up) + +4. **Favorite this page** — You'll visit it constantly + +### Notification Setup + +Ask GitHub or chat platform to notify you of: +- [ ] GitHub Discussions (if using for questions) +- [ ] Mentions in chat (@facilitator) +- [ ] Direct messages from students + +**Test notifications:** Have your co-facilitator ping you to confirm alerts work. + +--- + +## Starting Day 1 (15 Minutes Before Call Starts) + +### Final Checklist (5 min before start) + +- [ ] Yourself: Bathroom break done, water nearby, headphones on +- [ ] Software: All tabs open, no unexpected pop-ups +- [ ] Dashboard: Refreshed, showing latest data +- [ ] Co-facilitator: Online and confirmed in chat +- [ ] Students: Should be joining now — check incoming attendees +- [ ] Recording: If recording, make sure it's recording +- [ ] Slides: If using slides, they're visible and tested + +### First 60 Seconds on Call + +1. **Welcome message to chat:** + ``` + Welcome to the GitHub Workshop! 👋 + If you can see this message, you're connected. + Video or audio-only? Both are fine. + Screen reader users: All of GitHub.com is accessible. + Questions? Ask in chat anytime! + ``` + +2. **Monitor arrivals:** + - Watch participant list + - Greet people by name as they join + - "Hi [name], welcome! Glad you made it!" + +3. **Quick accessibility check:** + - "If your screen reader is working and you can hear me, say so in chat" + - Confirm at least 70% have confirmed + - If issues: "Let's get those fixed. Chat or email me." + +4. **Settle the room:** + - "We'll start in about 5 minutes. Get comfortable, grab water, etc." + +--- + +## During Hour 1: Welcome and Orientation + +### 0:00-0:05: Your Opening + +**Talking points (say these out loud):** + +> "Welcome everyone. I'm [name], and this is [co-facilitator name]. We're going to spend the next two days learning GitHub together. +> +> [Pause for acknowledgment] +> +> This is a completely accessible workshop. We've tested it with NVDA, JAWS, and VoiceOver. If something doesn't work for your screen reader, tell us immediately and we'll fix it. +> +> [Pause] +> +> Over the next two days, every single one of you is going to merge your first pull request. That might not sound like a big deal, but it is. It means you've collaborated with another person to improve code. That's a real developer skill. +> +> [Pause] +> +> We're hybrid, so you can work at your own pace. Some will finish fast, some will take time, and both are completely valid. No pressure. +> +> [Pause] +> +> Questions? Ask in chat anytime. That's what we're here for. Let's get started." + +### 0:05-0:15: Getting Into Repos + +**Step 1: Share the invite link** + +In chat, post: +``` +Here's your Day 1 invite link: +[PASTE YOUR INVITE LINK] + +Click it and GitHub will ask you to pick your name from a list. +Accept and GitHub creates your repo. +``` + +**Step 2: Monitor the Classroom dashboard** + +- Refresh every 30 seconds +- Watch for new acceptances +- Count them out loud: "I see 3... 5... 10 people joining..." + +**Step 3: Guide through the process** + +In chat as things happen: +``` +Great! I see people accepting the invite. +You should now be in your private repo. +Look for "Challenge 1" in your Issues tab. +When you see it, say so in chat! +``` + +**Step 4: Help people who are stuck** + +After 5 minutes, if someone hasn't said they found Challenge 1: +- Message them directly: "Hey @[name], did you find your Challenge 1? Let me know if you need help." +- Check dashboard: Did their repo get created? +- If repo created but they can't find issue: Direct link: `github.com/community-access-classroom/learning-room-[username]/issues` + +**Step 5: Confirm everyone is in** + +Wait until 70%+ have said they see Challenge 1 before moving forward. + +### 0:15-0:25: Demo Reading Challenge 1 + +**Your actions:** + +1. **Open your test repo on screen** +2. **Narrate what you're doing:** + ``` + "I'm going to show you what Challenge 1 looks like. + I'm clicking the Issues tab... + I see Challenge 1 here... + Let me read it to you..." + ``` +3. **Read the challenge issue text out loud** (slowly, pausing between sentences) +4. **Point out key sections:** + - "Here's what I need to do: [describe]" + - "At the bottom, there's a 'If You Get Stuck' section — that's your safety net" + - "This is a great challenge to learn the basics" + +**Ask in chat:** "Does everyone see something similar in their Challenge 1?" + +Wait for confirmations. Help anyone who sees something different. + +--- + +## During Hour 2: Demo PR Workflow + +### Demo Repo: Do Challenge 1 for Real + +**Setup:** You're using your test repo (the one you created during setup). + +**Narration Style:** Talk through EVERY action before doing it. + +> "Okay, I'm going to complete Challenge 1 right now. Watch what I do, because you're going to do the same thing 15 times this week. +> +> **Step 1: Read the challenge** +> The challenge is asking me to [describe]. Okay, I understand what I need to do. +> +> **Step 2: Find the file** +> I need to edit a file called [filename]. Let me look in the file list... there it is. +> +> **Step 3: Click edit** +> I'm clicking the pencil icon (✏️) to edit the file. +> +> **Step 4: Make my change** +> [Type while narrating] I'm adding this text... done. +> +> **Step 5: Create PR** +> I'm scrolling down... I see 'Propose changes' button. I'm clicking it. +> +> **Step 6: Create new branch** +> GitHub is asking if I want a new branch. Yes, I do. Clicking 'Create branch'... +> +> **Step 7: Compare PR** +> Now I see the comparison. My change is in green. Looks good! +> +> **Step 8: Review PR template** +> I'm clicking 'Create pull request'... +> Now I see a form with a template. The template tells me what to fill in. +> [Fill form while narrating each field] +> +> **Step 9: Create PR** +> I'm clicking the green 'Create pull request' button... done! +> +> **Step 10: Wait for Aria** +> Now watch... Aria bot automatically checks my work... +> [Wait 30 seconds] +> There! The bot commented. It's checking if I followed the rules. +> +> **Step 11: If I need to fix it** +> If Aria said I need to change something, I would go back to the PR and push a new commit. +> Since my PR is good, I'm ready to ask for a review. +> +> **Step 12: Request review** +> I'm typing @[another-student] to ask them to review my PR. +> +> **Step 13: Get approval** +> They reviewed it and approved. +> +> **Step 14: Merge** +> I'm clicking 'Merge pull request'... done! +> +> **Step 15: See next challenge** +> Now watch the Issues tab... +> [Refresh] +> Challenge 2 just appeared! That's how progression works. +> +> **That's the workflow.** You'll repeat this for every challenge. By the end of Day 2, you'll be excellent at this." + +### Post-Demo Q&A + +In chat: "Questions about what you just watched?" + +Answer a few questions, then: +> "Great. Any more questions? If not, let's move to working session. You've got this!" + +--- + +## During Hours 3-6: Working Session Management + +### Facilitator Dashboard Monitoring Routine + +**Every 5-10 minutes:** + +1. **Refresh Classroom dashboard** +2. **Scan for:** + - New repos created (scroll Accepted column) + - Recent commits (look at timestamps) + - PRs appearing (check student repos) + - Autograding failures (if applicable) + - Zero activity students (might need nudge) + +3. **Make notes:** + - "Student A has PR open — review when bot done" + - "Student B has zero commits — check in at 45-min mark" + - "Student C merged — celebrate in chat!" + +### Proactive Interventions (By Time) + +**0-15 min:** +- Monitor dashboard constantly +- Expect: First PRs being created +- If nothing: "Anyone need help with their first PR?" + +**15-30 min:** +- Aria bot feedback should be flowing +- Look for confused students +- In chat: "Anyone see feedback from Aria? Let me know if it's confusing!" + +**30-60 min:** +- First merges happening +- New challenges appearing +- Celebrate: "🎉 @student1 just merged their first PR! Nice work!" + +**60-120 min:** +- Mixed activity +- Some on Challenge 2, others still on Challenge 1 — both OK +- Check on quiet students: "How's it going, @student2?" + +**120-180 min:** +- Momentum building +- Multiple PRs happening simultaneously +- Watch for: Stuck students (same challenge 60+ min) + +**180-270 min:** +- Peak activity +- Help focuses on blockers, not starters +- Celebrate milestones: "Wow, @student3 is on Challenge 3!" + +### Responding to Common Chat Messages + +| Student Says | Your Response | +|---|---| +| "I'm stuck" | "Tell me what challenge you're on and what's confusing." (Then see troubleshooting guide) | +| "Is this right?" | "What did you create? Show me a link." (Then validate) | +| "I merged!" | "🎉 Awesome! You just merged your first PR! That's huge!" | +| "What's next?" | "Your next challenge should appear soon. Refresh your Issues. If not, let me know!" | +| "Is [technology] important?" | "Great question! [Short answer]. Let's talk more after this challenge." | +| "My screen reader glitched" | "Which screen reader? What glitched? Let's fix it." (Then escalate if needed) | + +### Peer Review Encouragement + +**What to look for:** +- Student A finishes Challenge 1 +- Student B also finished Challenge 1 +- Opportunity: Have them review each other! + +**What to say:** +> "@student1 and @student2 — you both finished Challenge 1! Want to review each other's PRs? That's how real developers work." + +**Guide them:** +- "Go to their PR" +- "Click 'Files changed'" +- "Leave a comment on lines you have thoughts about" +- "Then approve or request changes" + +--- + +## During Hour 7: Q&A and Wrap-Up + +### 0:00-0:10: Celebration + +**Pull Classroom dashboard data:** +- X students accepted +- Y PRs merged +- Z students on Challenge 2+ + +**Say:** +> "Okay everyone, look at what you did today: +> - [X] of you joined the workshop +> - [Y] pull requests were merged +> - [Z] of you are already on Challenge 2 +> +> That is incredible. You learned GitHub in one day. Give yourselves a hand." + +### 0:10-0:20: Reflection Prompt + +In chat or on call: +> "Tell us in chat: What was one thing you learned about GitHub today? Or something that surprised you?" + +Read responses out loud and affirm them: +- "GitHub is [response]" ✓ +- "Peer review is [response]" ✓ +- "I struggled with [thing] but figured it out" ✓✓✓ **BIG CELEBRATION** + +### 0:20-0:30: Troubleshoot Stragglers + +> "Anyone still stuck on Challenge 1 and want help?" + +Help them: +- Offer to review their PR if Aria bot isn't responding +- Give them a nudge in right direction +- Or schedule 1:1 after call + +### 0:30-0:35: Preview Day 2 + +> "Tomorrow we go deeper. Same process, harder challenges. You've got the skills now. +> +> Here's what to expect: +> - Code review deep dive +> - Challenges 10-16 (progressively harder) +> - More peer collaboration +> - By the end, you'll have real skills +> +> See you tomorrow at [time]!" + +### 0:35-0:45: Accessibility Check-In + +> "Before you go: Did your screen reader work well the whole time? Any accessibility issues we should fix before tomorrow?" + +Listen and note anything that broke. Fix it that night if possible. + +### 0:45-1:00: Optional Office Hours + +> "We're staying on the call for office hours. If you want to: +> - Finish your first PR +> - Start Challenge 2 +> - Ask follow-up questions +> +> Stay online and we'll help!" + +Monitor chat and help individuals. + +--- + +## Managing the Working Session Like a Pro + +### Energy Management + +**Every 60 minutes:** +- Announce: "Quick break everyone. Stand up, stretch, grab water. We'll resume in 5." +- Facilitators: Actually take a break too +- Mental check: Are you OK? Hydrated? Focused? + +**Every 120 minutes:** +- Celebrate progress: "Look at the dashboard! So many merges today!" +- Remind students: "This is normal pace. Everyone's doing great." +- Check co-facilitator: "How are you doing? Need to switch tasks?" + +### Dashboard Fatigue Prevention + +**Don't:** +- Stare at dashboard constantly (you'll miss chat questions) +- Check every 1 minute (data doesn't change that fast) +- Panic if someone is quiet (they might be concentrating) + +**Do:** +- Refresh every 5-10 minutes +- Trust that bots are working +- Pay attention to chat too (it's often where real help requests go) + +### When Students Help Students + +**This is great.** When you notice: +- "I see @student1 helping @student2 with merge conflicts!" + +**Publicly celebrate it:** +> "@student1 — thank you for helping. That's exactly what real developer teams do." + +This reinforces the collaborative culture and takes pressure off you. + +--- + +## Day 2 Operations (Similar Structure) + +### Key Differences from Day 1 + +| Day 1 | Day 2 | +|-------|-------| +| Intro focus | Skill-building focus | +| 1 assignment | New (2nd) assignment | +| Challenges 1-9 | Challenges 10-16+ | +| Basic workflow | Complex scenarios (merge conflicts, CLI, etc.) | +| Lots of encouragement | Challenge + celebrate | + +### Day 2 Hour 1: Recap Opening + +Pull Classroom dashboard (Day 1 assignment): +> "Yesterday, X of you joined and Y PRs were merged. Z of you kept working async. +> +> You all know: +> - How to navigate GitHub +> - How to edit and create a PR +> - How to request a review and merge +> +> That's real skills. Today we go deeper." + +Then: Share Day 2 assignment invite link + +### Day 2 Code Review Demo + +This is YOUR demo, not the bot's: + +1. **Open a student's Day 1 PR** (with permission or use your test repo) +2. **Narrate the review process:** + - "Here's what I do when reviewing someone's code..." + - "I read the description first..." + - "Then I click 'Files changed'..." + - "I think about: Is this right? Does it follow the rules? Is it clear?" + - "I leave kind, specific feedback..." + - "I either approve or ask for changes..." +3. **Have students practice** in pairs reviewing each other's Day 1 PRs + +### Day 2 Dashboard Monitoring + +Same as Day 1, but looking for: +- Students on Challenge 10+ (new territory) +- Autograding failures (these get harder) +- Merge conflicts (look for red flags in PR comments) +- Students helping with complex problems + +--- + +## Post-Workshop Operations + +### Immediately After (Last 15 min of Day 2) + +- [ ] Screenshot Classroom dashboard showing final stats +- [ ] Note any broken automations or issues +- [ ] Thank your co-facilitator +- [ ] Send students a closing message + +### That Night (Day 3) + +- [ ] Export Classroom data (total PRs, students, completion rates) +- [ ] Identify students still in progress (email: "Need any help finishing?") +- [ ] Document what worked and what broke +- [ ] Send thank you emails to co-facilitators and volunteers + +### Following Week + +- [ ] Send personalized email to each student +- [ ] Invite them to alumni community +- [ ] Offer 1:1 mentorship if interested +- [ ] Update this guide with lessons learned + +--- + +## Emergency Procedures Reference + +### If Aria Bot Stops + +1. Check GitHub status +2. Manually review PRs (use Aria's format) +3. Post in chat: "Brief delay with feedback bot, manually reviewing" + +### If Student Repo Won't Create + +1. Check Classroom assignment published +2. Manually create repo in org using template +3. Share direct link with student + +### If Your Voice Fails + +1. Use chat for all instructions +2. Have co-facilitator do vocal work +3. Use pre-recorded video if available +4. Type in chat for important messages + +### If You Lose the Call + +1. Post in chat: "Video call dropped, reconnecting..." +2. Send email to all: "Continuing asynchronously" +3. Facilitate through chat/email until reconnected + +--- + +## Facilitator Self-Care + +**During the workshop:** +- Drink water +- Stretch every 60 minutes +- Answer questions but don't obsess +- If co-facilitator is struggling, offer to swap tasks +- Remember: You can't help everyone at once + +**After the workshop:** +- Take a break (don't immediately plan next cohort) +- Celebrate what went well +- Document issues objectively (not as failures) +- Get feedback from co-facilitator + +**Before next cohort:** +- Update this guide based on lessons learned +- Test automation fresh +- Add your own notes and strategies +- Build on what worked + +--- + +**Last Updated:** May 2026 | **Version:** 1.0 | **Maintainer:** Jeff Bishop diff --git a/admin/FACILITATOR_RESOURCES.md b/admin/FACILITATOR_RESOURCES.md new file mode 100644 index 0000000..f6f7af7 --- /dev/null +++ b/admin/FACILITATOR_RESOURCES.md @@ -0,0 +1,291 @@ +# Facilitator Resource Index +## Complete Guide to Running GitHub Classroom Workshops + +Welcome, facilitator! This page helps you navigate all the documentation for running an accessible GitHub workshop for blind and low-vision students. + +--- + +## 🎯 Start Here Based on Your Situation + +### "I've Never Run This Workshop Before" +→ Read in this order: +1. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-github-classroom-setup-before-day-1) — GitHub Classroom Setup section +2. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-pre-workshop-checklist-48-hours-before) — Pre-Workshop Checklist +3. [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) — For hands-on procedures + +### "Workshop Is Tomorrow" +→ Quick tasks: +1. [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-pre-workshop-checklist-48-hours-before) — Pre-Workshop Checklist (all boxes) +2. [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md#pre-workshop-setup-3-hours-before) — 3-Hour Prep +3. [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md#starting-day-1-15-minutes-before-call-starts) — Day-Of Checklist + +### "Workshop Is Happening Right Now" +→ Reference: +- [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) — Hour-by-hour procedures +- [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) — When things break + +### "A Student Got Stuck" +→ Go to: +- [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md#-student-level-issues) — Student-level scenarios +- Then [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) — For how to respond + +### "Something Technical Broke" +→ Check: +- [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md#-emergency-what-to-do-when-everything-stops-working) — Emergency protocols +- Then [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-quick-troubleshooting-reference) — Quick reference + +### "Workshop Just Ended, What's Next?" +→ See: +- [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-post-workshop-tasks-week-after) — Post-workshop tasks +- [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md#post-workshop-operations) — Detailed post-workshop procedures + +--- + +## 📚 Complete Resource Reference + +### Primary Documents + +#### [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md) (33 KB) +**The complete workshop bible.** Everything from GitHub Classroom setup through post-workshop follow-up. + +**Main sections:** +- GitHub Classroom Setup (first-time setup) +- Pre-Workshop Checklist (48 hours before) +- Day 1 Live Operations (hour-by-hour) +- Day 2 Live Operations (hour-by-hour) +- Post-Workshop Tasks (week after) +- Quick Troubleshooting Reference +- Appendices (templates, keyboard shortcuts) + +**When to use:** +- First-time workshop setup +- Planning a cohort +- During workshop (overview reference) + +--- + +#### [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) (18 KB) +**Real-time, hands-on procedures.** Step-by-step what to do during each hour of the workshop. + +**Main sections:** +- Pre-Workshop Workstation Setup +- Hour-by-Hour Procedures +- Dashboard Monitoring Routines +- Chat Response Templates +- Emergency Procedures +- Facilitator Self-Care + +**When to use:** +- During workshop (follow procedures hour-by-hour) +- Preparing facilitator workstation +- Real-time student support + +--- + +#### [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) (18 KB) +**Problem-solving guide.** Specific issues and their solutions. + +**Main sections:** +- Emergency Scenarios (bots down, video call broken, etc.) +- Student-Level Issues (can't find repo, confused by feedback, etc.) +- Specific Technical Scenarios (merge conflicts, autograder failures, etc.) +- GitHub Platform Issues (GitHub down, Actions slow, etc.) +- Facilitator Mistakes & Recovery +- Prevention Strategies + +**When to use:** +- Something is broken and you need to fix it +- Student is confused or stuck +- Automation failed + +--- + +### Supporting Documents + +#### [FACILITATOR_CHALLENGES.md](FACILITATOR_CHALLENGES.md) (11.6 KB) +Operations guide for managing the challenge system and student progression during a live cohort. + +**Covers:** +- How the challenge system works +- Monitoring student progress +- Responding to help requests +- Common issue patterns + +**When to use:** +- Understanding the challenge flow +- Monitoring student progression +- Identifying stuck students + +--- + +#### [FACILITATOR_ASSESSMENT.md](FACILITATOR_ASSESSMENT.md) (0.4 KB) +Assessment rubric and grading guidance (brief reference). + +**Covers:** +- How to assess student work +- What "success" looks like + +**When to use:** +- Providing meaningful feedback to students +- Deciding if student meets learning goals + +--- + +## 🎓 Typical Workflow + +### Weeks 1-2 Before Workshop +1. Read [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-github-classroom-setup-before-day-1) GitHub Classroom Setup +2. Create your GitHub Classroom and assignments +3. Follow setup checklist in [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-pre-workshop-checklist-48-hours-before) + +### 48 Hours Before +1. Complete [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-pre-workshop-checklist-48-hours-before) checklist +2. Test everything one more time +3. Read [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) overview + +### Day Before +1. Final checklist items +2. Setup workstation per [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md#pre-workshop-setup-3-hours-before) +3. Message co-facilitator: "Ready for tomorrow?" + +### Day 1 During +1. Follow [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) hour-by-hour +2. Keep [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) open in another tab +3. Reference [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-day-1-live-operations) for overview + +### Day 2 During +1. Same as Day 1, but reference [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-day-2-deeper-skills-and-celebration) Day 2 section +2. Be ready for harder scenarios and more independence from students + +### After Workshop +1. Follow [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md#-post-workshop-tasks-week-after) post-workshop tasks +2. Note what worked and what didn't +3. Update this guide for next time + +--- + +## 🔧 How to Use These Documents + +### During Workshop: Have These Open + +**Browser tabs:** +1. [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) (current section) +2. [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) (troubleshooting reference) +3. Your GitHub Classroom dashboard +4. GitHub Discussions / chat with students + +**Physical:** +- Print [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md) or have on second monitor +- Notepad for tracking issues + +### Quick Reference: Keyboard Shortcuts + +**Jump to sections fast:** + +In your browser: `Ctrl+F` (or `Cmd+F` on Mac) + +Then search for: +- `### Hour` — Jump to specific hour procedures +- `**Student Says** "...` — Jump to chat response template +- `**Symptom:** ...` → Jump to troubleshooting scenario + +### Getting Help + +**If you can't find something:** +1. Check "Start Here Based on Your Situation" above +2. Use browser search (Ctrl+F) +3. Check the table of contents in individual documents +4. Ask co-facilitator or post in team chat + +--- + +## 📊 Document Overview at a Glance + +| Document | Purpose | Length | Best For | +|----------|---------|--------|----------| +| **FACILITATOR_GUIDE.md** | Complete workshop bible | 33 KB | Planning, overview, templates | +| **FACILITATOR_OPERATIONS.md** | Hour-by-hour procedures | 18 KB | During workshop, real-time decisions | +| **FACILITATOR_CLASSROOM_TROUBLESHOOTING.md** | Problem-solving | 18 KB | When things break or students stuck | +| **FACILITATOR_CHALLENGES.md** | Challenge management | 11.6 KB | Understanding progression system | +| **FACILITATOR_ASSESSMENT.md** | Grading rubric | 0.4 KB | Quick reference for assessment | + +--- + +## 🎯 Key Principles Across All Documents + +These principles appear repeatedly because they're **that important**: + +1. **Accessibility First** — Test with NVDA, JAWS, VoiceOver before every workshop +2. **Async-Friendly** — Students can join sync or async; both are valid +3. **No Pressure** — Fast pace and slow pace are both OK +4. **Narrate Everything** — Say what you're doing before you do it +5. **Celebrate Effort** — Not just finished work; recognition matters +6. **Ask for Help** — "I don't know but let's figure it out together" is OK +7. **Community** — Build an environment where students help each other + +--- + +## 💡 Pro Tips from Experienced Facilitators + +- **Bookmark the documents** — You'll reference them constantly +- **Add your own notes** — Margin notes about what worked for you +- **Screenshot the dashboard** — Keep records of student progress +- **Keep student emails** — Reference them when sending thank-yous +- **Document failures** — So next time is easier +- **Celebrate publicly** — Recognize achievements in real-time +- **Stay hydrated** — Drink water throughout the day +- **Sync with co-facilitator** — Check in every 60 minutes + +--- + +## 🚀 Related Resources + +**In this repository:** +- [classroom/README.md](../classroom/README.md) — GitHub Classroom deployment guide +- [docs/](../docs/) — Student-facing resources and guides +- [CONTRIBUTING.md](../CONTRIBUTING.md) — How to contribute to open source (post-workshop resource) + +**External:** +- [GitHub Classroom Help](https://classroom.github.com/help) +- [GitHub Docs](https://docs.github.com) +- [Accessibility Testing Guide](ACCESSIBILITY_TESTING.md) — For testing with screen readers + +--- + +## ✅ Pre-Workshop Sanity Check + +Before your first workshop, verify: + +- [ ] I've read [FACILITATOR_GUIDE.md](FACILITATOR_GUIDE.md) GitHub Classroom Setup +- [ ] I've created a test GitHub Classroom +- [ ] I've accepted my own invite link +- [ ] Aria bot commented on my test PR +- [ ] Progression bot created Challenge 2 when I closed Challenge 1 +- [ ] I've read [FACILITATOR_OPERATIONS.md](FACILITATOR_OPERATIONS.md) procedures +- [ ] I've set up my facilitator workstation per the guide +- [ ] I've tested video call + audio dial-in +- [ ] Co-facilitator has confirmed they're ready +- [ ] I've reviewed [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) emergency section + +**If all checked:** You're ready! + +**If any unchecked:** That item is probably your next task. Don't skip it — it matters. + +--- + +## 📞 Questions or Feedback? + +Found an error or unclear section? Help improve this guide: + +1. Make a note of what confused you +2. After the workshop, update the relevant document +3. Tag it with what you learned +4. Share with next facilitator + +This guide evolves with each cohort. Your experience makes it better for the next facilitator. + +--- + +**Last Updated:** May 2026 | **Maintainer:** Jeff Bishop | **Version:** 2.0 + +**Navigation:** [← Back to Admin](README.md) | [View All Docs](../docs/) | [Classroom Setup](../classroom/README.md) diff --git a/admin/PODCASTS.md b/admin/PODCASTS.md index 01af71d..dde3f72 100644 --- a/admin/PODCASTS.md +++ b/admin/PODCASTS.md @@ -2,25 +2,25 @@ ## Git Going with GitHub - Audio Series -> **Architecture update (May 2026):** Some episodes (notably Episode 4: The Learning Room) were recorded under the original "single shared learning-room repository" model. The workshop has since moved to a **GitHub Classroom** model where each participant gets their own private copy of `learning-room-template`. The high-level concepts (PR-driven practice, automated bot feedback, peer review) are still accurate. The bot is now called Aria, and your Learning Room repo is private to you. Refer to the live chapters in `docs/` for the current architecture; the audio remains a useful conceptual overview. - -Listen to companion audio episodes for every chapter and appendix in this workshop. Each episode is a conversational overview between hosts Alex and Jamie that previews or reviews the key concepts - perfect for learning on the go or reducing screen reader fatigue. 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](https://community-access.org/git-going-with-github/podcasts/feed.xml) 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 preview the concepts. You will know what to expect before diving into the exercises. -- **After a chapter:** Listen to reinforce what you learned 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 +## Start Here -### Episode 0: Welcome to Git Going with GitHub +### 1. Episode 0: Welcome to Git Going with GitHub A tour of the workshop structure, the two-day arc, and what you will accomplish. @@ -38,8778 +38,44878 @@ Based on: [Course Guide](docs/course-guide.md) #### Transcript -**Alex:** Welcome to Gitt Going with GitHub. This is episode zero, titled Welcome to Gitt Going with GitHub. I am your host, Alex, and I am thrilled to be starting this journey with you. Whether you are a seasoned programmer who is just now moving over to GitHub, or you are completely new to version control, this audio series is designed to be your companion. We are going to explore open source collaboration using GitHub, Visual Studio Code, and GitHub Copilot, all with a strict focus on screen reader and keyboard-only navigation. +**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 am so excited to be here. I will be learning right alongside you, asking the questions, and probably sharing a few embarrassing stories from my own learning journey. Because let me tell you, I learned GitHub just two years ago, and I remember exactly how overwhelming it felt. When I first heard people throwing around words like clone, fork, and branch, I thought we were doing some weird mix of agriculture and science fiction. +**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:** That is a perfect description of how it sounds at first. And that is exactly why we are doing this. Before we dive into the deep end, we want to give you a map of the territory. This episode is an overview of the entire two-day workshop. We are going to talk about what open source actually means, how this course is structured, the philosophy behind how we teach, and we will preview some of the core vocabulary you will be using every single day. +--- -**Jamie:** But before we get into all of that, a quick public service announcement. If you are listening to this and you have not yet completed Chapter 0, which is the Pre-Workshop Setup, you will want to navigate to that chapter and complete it before Day 1 officially begins. It takes about thirty minutes. It walks you through creating your GitHub account, installing Git, setting up VS Code, and configuring your screen reader specifically for GitHub. +**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. -**Alex:** Exactly. Getting your environment set up correctly is half the battle. Once your screen reader is optimized for the web interface, everything else flows much more smoothly. So, let us start with the big picture. The entire goal of this workshop is built around one single idea. By the end of these two days, you will make real contributions to a real open source project. Not a simulated sandbox. Not pretend. Real open source. +**Jamie:** So the episode should work even if someone has not read the chapter yet. -**Jamie:** Which brings up a great question. For someone entirely new to this space, what exactly does open source mean, and why does it matter so much? +**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:** Open source refers to software where the original source code is made freely available. Anyone can navigate to the code, read it, modify it, and distribute it. But more importantly, open source is a collaborative community. It is a way of building software where thousands of people from all over the world work together to solve problems, rather than one closed-off team in a single company. +--- -**Jamie:** I always like to think of open source as a massive community potluck dinner. Someone brings the main dish, which is the core software. But then someone else says, hey, this needs salt, and they add a new feature. Someone else brings dessert, which might be a documentation update. And someone else fixes the wobbly table, which is a bug fix. Anyone is allowed to walk into the room, taste the food, and contribute their own recipe to make the whole meal better for everyone. +**Jamie:** How should they picture the shape of the workshop? -**Alex:** I love that analogy. And what makes GitHub so powerful is that it provides the kitchen, the tables, and the recipe cards for that potluck. GitHub is the platform where millions of these open source projects live. It matters because much of the modern internet, including the tools we use for accessibility, runs on open source software. When you learn how to contribute, you get a voice in how the software you use every day is built. +**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:** Okay, so we are going to be cooking at the open source potluck. How exactly are we going to learn all of this in just two days? +**Jamie:** What should feel predictable before the first live session starts? -**Alex:** We divide the workshop into two distinct phases. Day 1 is all about GitHub Foundations in the browser. You will learn the GitHub web interface using only your keyboard and your screen reader. We will not touch a command line. We will not open a desktop application. You will learn how to navigate projects, find issues, propose changes, and review other people's work, entirely through the GitHub website. +**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. -**Jamie:** And I really appreciate this approach. When I started two years ago, I tried to learn the command line, the website, and the code editor all on the same day. It was a disaster. I did not know which program was throwing an error, or what the error even meant. +**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:** That is incredibly common, and it is the reason for our core learning philosophy in this workshop. We believe you must learn the manual skill first, before you introduce automation. If you try to use advanced tools before you understand what they are doing behind the scenes, you will get lost the moment something goes wrong. By spending all of Day 1 in the browser, you build a mental model of how GitHub is structured. You learn the concepts deeply. +--- -**Jamie:** So Day 1 is building the foundation. What happens on Day 2? +**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. -**Alex:** Day 2 is when we move to the desktop. We transition into Visual Studio Code, which we often just call VS Code. This is a powerful, accessible code editor. Once we are in VS Code, we introduce GitHub Copilot, which is an artificial intelligence coding assistant, and we activate the Accessibility Agents ecosystem. +**Jamie:** Where is the promise of the workshop, underneath all the logistics? -**Jamie:** Okay, hold on. Accessibility Agents? That sounds like something out of a spy movie. What are they? +**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:** They do sound a bit like secret agents. On Day 2, you will be introduced to a system of fifty-five accessibility agents working across three different teams. These agents are AI assistants configured specifically to help with accessibility tasks. For example, one team of agents acts as your daily briefing and issue tracking squad. They can summarize what happened in a project overnight so your screen reader does not have to read through fifty individual comments. Another team focuses on pull request reviews, helping you spot missing alternative text or improper heading structures in code before you submit it. +**Alex:** The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work. -**Jamie:** Oh, that is clever! It is like having a team of expert accessibility consultants sitting in the room with you, ready to review your work or summarize long threads. +**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 when you already understand what they are doing. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need. -**Alex:** Exactly. But again, tying back to our philosophy, these agents only make sense if you already know what an issue or a pull request is. If you do not know how to manually review code, the agent's advice will not mean anything to you. That is why Day 2 is all about taking the manual skills you mastered on Day 1 and amplifying them with these fifty-five agents. By the end of Day 2, you will use these tools to ship a real contribution, and your name will be permanently recorded in the commit history of an open source project. +--- +**Jamie:** What is the pre-flight check here? -**Jamie:** Alex, you just used a few terms that I want to make sure we define, because I remember being so confused by them. We have an entire glossary in Appendix A, but can we do a high-level preview of the core vocabulary right now? Let us start with Repository. +**Alex:** Here is the plain-English version of Before You Begin. Start with Get Going with GitHub if you want the most guided path. Put another way, 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. -**Alex:** Absolutely. A repository, or repo for short, is the container for an entire project. It holds all the files, the folders, the documentation, and, most importantly, the complete history of every change ever made. +**Alex:** Here is what that changes in practice. Creating a GitHub account. Installing Git. Setting up VS Code (optional for Day 1, required for Day 2). Configuring your screen reader for GitHub. -**Jamie:** I remember someone telling me a repository is just a folder. But it is more than that, right? +**Alex:** This is where the talk moves from concept to action. This is where Companion Audio Series becomes real: the audio track is a standalone teaching companion for the same concepts. That matters in practice: Use the episode whenever audio helps you enter or revisit the topic. -**Alex:** It is much more than that. Think of a repository as a project folder that has a time machine built into it. Because it tracks every single modification, you can ask the repository to show you exactly what the project looked like last Tuesday at noon, or who added a specific line of code three years ago. It never forgets. +**Alex:** The room should hear these as checkpoints. 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. -**Jamie:** Okay, next term. What is an Issue? +**Jamie:** Where does the workshop stop being a tour and start becoming contribution? -**Alex:** An issue is essentially a discussion item within a repository. If you find a bug, you open an issue to report it. If you want to request a new feature, you open an issue. +**Alex:** Keep the learner anchored in Day 1: GitHub Foundations. These chapters are designed to be read and practiced in order. This is the part to say slowly: 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. -**Jamie:** So it is like a digital to-do list combined with a discussion forum. When I want to fix something, I navigate to the Issues section, find one that sounds interesting, and announce that I am going to work on it. +--- -**Alex:** That is exactly right. Issues are the starting point for almost all open source work. Now, once you have done the work and fixed the bug, you need a way to give that fix back to the project. That brings us to our third core term, the Pull Request. +**Alex:** Before the learner moves on. The reason Day 2: VS Code + Accessibility Agents matters is that day 2 moves you from the browser to the desktop. That gives the learner a simple foothold: every skill maps directly to what you learned on Day 1. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places. -**Jamie:** Ah, the famous PR. I used to hear people say, just submit a PR, and I would nod and pretend I knew what they meant. +**Jamie:** What would you say to someone who is already bracing for this to be too much? -**Alex:** A pull request, or PR, is a formal proposal to combine your changes into the main project. And I love that name, because you are literally requesting that the maintainer pull your changes into their repository. You are saying, here is the work I did to fix that issue, please review it. +**Alex:** Start with Appendices - Reference Material: Open these at any time during the workshop. The next useful detail is this: They are not part of the chapter sequence - use them when you need them. -**Jamie:** My favorite analogy for a pull request is publishing a book. Imagine the repository is the official, published book. You cannot just grab a pen and write your own paragraph directly onto the printed pages for everyone in the world to see. Instead, you write your changes on a separate piece of paper, which is your draft. A pull request is you handing that piece of paper to the editor and saying, I think this paragraph makes the book better. What do you think? +**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. -**Alex:** That is a brilliant comparison. And the editor, who in our world is called the project maintainer, will read your draft. They might leave comments asking you to change a sentence, or fix a typo. This is the code review process. You update your draft based on their feedback. And finally, when the editor is happy with it, they perform the fourth core concept, the Merge. +--- -**Jamie:** And a merge is when the editor takes your piece of paper, types it into the official manuscript, and publishes it for real. +**Jamie:** What do you want them to do when the plan breaks? -**Alex:** Exactly. Merging is the act of combining your approved pull request into the main repository. Once it is merged, your code is officially part of the project. So, to recap the lifecycle. You find a problem in a Repository. You discuss it in an Issue. You propose a solution with a Pull Request. And the maintainer accepts it with a Merge. +**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:** 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:** Okay, that sounds like a lot of steps. And if I am being honest, thinking about doing all of this, plus moving over to VS Code on Day 2, feels a little intimidating. Especially for folks who might be totally new to the command line, or new to using version control. +**Jamie:** What is the one idea that makes the next few steps less mysterious? -**Alex:** It does sound like a lot! But here is the thing. You have already done most of this on Day 1 in the browser. You already know the workflow. When we move to VS Code, it is the exact same workflow, just with VS Code handling the heavy lifting. We are going to take it one step at a time. +**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. -**Jamie:** And there is actually a really cool bridge between Day 1 and Day 2, right? The period key trick. I wish I had known that when I started. +**Alex:** The parts worth keeping in working memory are these. 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. -**Alex:** It is one of my favorite features on GitHub. When you are on any repository page in your browser, if you simply press the period key on your keyboard, GitHub will instantly open a web-based version of VS Code right there in your browser tab. It is called GitHub dot dev. You do not have to install anything. It uses the exact same screen reader mode and keyboard shortcuts as the desktop version. It is the perfect stepping stone. You get to feel what a code editor is like, but you are still in the safety of your web browser. +--- -**Jamie:** That is amazing. You can literally just press period, and suddenly you are in an accessible editor. +**Alex:** Here is the practical turn. Start with Step 1 - Know Your Starting Place: Before Day 1 starts, complete Chapter 00: Pre-Workshop Setup. The next useful detail is this: 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. -**Alex:** Yes. And we deliberately designed this workshop so that you are never thrown into the deep end without a life vest. Every single chapter builds on the one right before it. If you look at the course guide, you will notice we have structured the materials very specifically. There are chapters, and there are appendices. +**Jamie:** How would you walk the room through that step by step? -**Jamie:** How should we be using those? Should I read the appendices before I start the exercises? +**Alex:** Here is the plain-English version of Step 2 - Accept the GitHub Classroom Assignment. At the start of Day 1, the facilitator gives you a GitHub Classroom assignment link. Put another way, it usually starts with https://classroom.github.com/a/. -**Alex:** No, please do not try to read the appendices straight through! The chapters, numbered one through sixteen, are your main journey. They are designed to be read and practiced in order. The appendices, labeled with letters like Appendix A for the Glossary, or Appendix B for the Screen Reader Cheat Sheet, are purely reference materials. You keep them open in a separate tab or window. When you encounter a term you do not know, or you forget a screen reader command, you navigate to the appendix, find what you need, and then jump right back into the chapter. +**Alex:** First, open the assignment link in the browser where you are signed in to GitHub. Then, if GitHub asks you to authorize GitHub Classroom, activate Authorize GitHub Classroom. After that, 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. Finally, activate Accept this assignment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. -**Jamie:** That takes a lot of pressure off. I do not have to memorize every single command before I start. I can just look them up as I go. +**Jamie:** What does the learner do first, second, and then after that? -**Alex:** Exactly. Memorization is not the goal. Navigation and confidence are the goals. And to build that confidence, we have included twenty-four structured exercises throughout the curriculum. +**Alex:** First, wait while GitHub Classroom creates your private repository. Then, refresh the page until the repository link appears. After that, open the repository link and bookmark it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Jamie:** I love the exercises in this course. They are so bite-sized. Can you explain the pattern we use for them? +**Alex:** Keep the thread going. This is where Step 3 - Understand the Learning Room becomes real: the Learning Room is a private repository created from a template. That matters in practice: Everyone starts from the same materials, but your work belongs to you. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed. -**Alex:** Every single exercise follows the exact same three-part pattern. First is the Try It section, which gives you clear, step-by-step instructions on what to do. Second is the You Are Done When section. This tells you the specific outcome you are looking for, so there is no guessing about whether you finished it correctly. Finally, there is the What Success Feels Like section. This is incredibly important for screen reader users. We describe exactly what you should hear, or where your focus should land, when the task is completed successfully. +**Alex:** These are the details that keep the idea from floating away. 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. -**Jamie:** That is so helpful. I remember reading tutorials that would just say, click the button and you are done. And I would press enter on a button, and my screen reader would say nothing, and I had no idea if it actually worked. Knowing what success feels like is a game changer. +--- -**Alex:** It really is. Let me give you an example. In Chapter One, there is an exercise called the Sixty Second Orientation. The Try It section asks you to navigate to a repository page, and press a sequence of keyboard shortcuts. Press the number 1 key, then the letter D, then the number 2 key, then the letter H. The You Are Done When section says you have successfully navigated between the main content, the repository details, and the file list. And the What Success Feels Like section explains the specific auditory feedback you will get from your screen reader as you jump between those landmarks. Every exercise takes between one and five minutes, and they are designed to be impossible to fail. They are just stepping stones. +**Jamie:** Turn that into a path someone can follow. +**Alex:** Keep the learner anchored in Step 4 - Find Challenge 1. After your Learning Room repository is created, the Student Progression Bot creates your first challenge issue. This is the part to say slowly: When you close a challenge issue, the next challenge opens. -**Jamie:** I am feeling so much better about this. But what if I do get stuck? What if my screen reader starts reading a wall of text, or I press the wrong shortcut and suddenly I am in a completely different view? +**Alex:** First, open your Learning Room repository. Then, navigate to the Issues tab. On GitHub, the keyboard shortcut is G then I. After that, find an issue titled Challenge 1: Find Your Way Around. Finally, open the issue and read the body from top to bottom. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. -**Alex:** First, take a breath. Getting lost is a normal part of learning a complex interface. If you get stuck, we have a whole section in the guide called Getting Help. You can reference the Troubleshooting guide, which has step-by-step solutions to common screen reader focus issues. You can check the Quick Reference guide for shortcuts. And if you are truly stuck, you can actually open an issue in the workshop repository itself! You will describe what you tried, what happened, and what you expected to happen. It is a safe environment to practice asking for help the open source way. +**Jamie:** What is the ordered workflow? -**Jamie:** I really appreciate that. It normalizes getting stuck. When I first started, I thought getting an error meant I was bad at programming. Now I know that getting errors just means I am programming. +**Alex:** First, follow the checklist in the issue. Then, post your evidence in the evidence field or as the requested comment. After that, close the challenge issue when the instructions tell you to close it. The rhythm is simple: orient, act, verify, then continue. -**Alex:** That is a fantastic way to look at it. Professional developers get errors all day long. The difference is just that they have built up the muscle memory of how to recover from them. And that is exactly the muscle memory we are going to build over these two days. +**Alex:** Another way to ground it. The reason Step 5 - Choose the Tool That Fits the Moment matters is that there is no single correct way to use GitHub. That gives the learner a simple foothold: the workshop teaches the workflow first, then offers tool paths. -**Jamie:** So, as we wrap up this introductory episode, what are the biggest takeaways we should keep in mind before we jump into Chapter One? +**Alex:** That becomes easier when you listen for these cues. 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. -**Alex:** I would say there are four main takeaways. Number one, remember our philosophy. We learn the manual skill first, then we automate it. Do not rush to the fancy tools until you understand the basic concepts. Number two, lean heavily on your reference materials. Keep the Glossary and the Screen Reader Cheat Sheet open in another tab. Number three, trust the exercise pattern. Focus on what success feels like, and take it one small step at a time. +**Jamie:** Where do you want a learner to place their attention here? -**Jamie:** And number four, be kind to yourself. You are learning a new language, a new platform, and a new way of collaborating all at once. If it feels like a lot, that is because it is a lot. But you are going to do great. +**Alex:** Start with Step 6 - What to Listen For with a Screen Reader: When you feel lost, listen for structure before you take action. The next useful detail is this: If you are not sure where you are, pause and navigate by headings or landmarks. -**Alex:** Well said, Jamie. Up next in episode one, we are going to dive into Chapter One, Understanding GitHub's Web Structure. We will explore how GitHub organizes its pages, how to orient yourself using headings and landmarks, and how to make your screen reader glide through the interface. We will see you there! +**Alex:** A few details make that real. Page title. Repository name heading. Landmark names such as main content or repository navigation. Tab names such as Code, Issues, and Pull requests. - +**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. +--- -### Episode 1: Pre-Workshop Setup +**Alex:** This is the part worth saying out loud. Here is the plain-English version of Step 7 - Use the Support Built into the Course. If something does not work, do not start over silently. Put another way, read the latest bot message, check the challenge issue, and ask for help with the link to the page where you are stuck. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction. -Creating your GitHub account, installing Git and VS Code, configuring your screen reader. +**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. -Based on: [Chapter 0: Pre-Workshop Setup](docs/00-pre-workshop-setup.md) +**Jamie:** Give me the sequence, because order matters here. - +**Alex:** This is where Step 8 - Your First Success Check becomes real: you are ready to continue when you can say these four things. That matters in practice: You do not need to understand every GitHub feature before you begin. -[Download Episode 1 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep01-pre-workshop-setup.mp3) +**Alex:** First, I can open my Learning Room repository. Then, I can find the Issues tab. After that, I can open Challenge 1. Finally, I know where to post my evidence and how to ask for help. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. + +**Jamie:** Let's pause on Where to Go Next. What should a learner take away from it? + +**Alex:** Keep the learner anchored in Where to Go Next. Use this order if you want the gentlest path. This is the part to say slowly: We will keep the path explicit, and we will keep giving you the next step. + +**Alex:** First, chapter 00: Pre-Workshop Setup. Then, chapter 01: Choose Your Tools. After that, chapter 02: Understanding GitHub. Finally, chapter 03: Navigating Repositories. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. + +**Jamie:** Before we leave Where to Go Next, what is the practical point? + +**Alex:** First, chapter 04: The Learning Room. Then, your Challenge 1: Find Your Way Around issue in your Learning Room repository. 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 0. Next in the series is episode 1, where we keep building the same contributor muscles. + + + +--- + +### 2. Episode 18: Glossary of Terms + +Comprehensive glossary: Git, GitHub, open source, and accessibility terminology. + +Based on: [Appendix A: Glossary of Terms](docs/appendix-a-glossary.md) + +Audio and transcript are being regenerated for this episode.
-Read Transcript - Episode 1: Pre-Workshop Setup +Read Transcript - Episode 18: Glossary of Terms #### Transcript -**Alex:** Welcome to Gitt Going with GitHub. This is episode one, titled Pre-Workshop Setup. I am your host, Alex, and I am here with my co-host, Jamie. In this audio series, we are going to guide you through learning GitHub, version control, and open source collaboration, specifically designed for developers who use screen readers or magnification. +**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:** Hi everyone. I am so excited to be here. I actually took this exact workshop about two years ago. I remember exactly what it feels like to hear all these new terms thrown around and feel completely overwhelmed. So I am here to ask Alex all the questions that are probably running through your head right now. +**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:** And those questions are exactly what we want. Today, our goal is to get your computer, your browser, and your screen reader completely set up and verified before day one of the workshop even begins. We will cover creating a GitHub account, understanding the difference between Git and GitHub, installing Visual Studio Code, turning on some essential accessibility settings, and verifying that everything works. +--- -**Jamie:** Okay, that sounds like a lot of steps. +**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. -**Alex:** It does! But here is the thing, you have already done most of this on Day One of any new job or project. It is the exact same workflow, just with some new tools. Once we get the foundation set up today, the rest of the workshop is just learning how to use it. +**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:** Let us start with the biggest question people usually have. What is the difference between Git and GitHub? They sound like the same thing, but they serve two very completely different purposes. +--- -**Jamie:** This confused me so much when I started. I thought GitHub was just the company that made Git. +**Jamie:** Okay, set the room for us. What are we walking into? -**Alex:** That is a very common misconception. Let us break it down. Git is a version control system. Version control is basically a system that records changes to a file or set of files over time so that you can recall specific versions later. Think of Git as a time machine for your code. It runs locally on your computer. When you make a mistake, Git allows you to roll back your files to exactly how they were yesterday, or last week. +**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. -**Jamie:** So if Git is the time machine running on my local laptop, what is GitHub? +**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:** GitHub is a hosting platform for collaboration. If Git is your personal camera saving photos to your hard drive, GitHub is the social media platform where you upload those albums so your friends can see them, comment on them, and add their own photos. GitHub lives on the web. It takes the code you manage locally with Git and gives you a place to share it, review it, and collaborate with developers all over the world. +**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:** That makes sense. Git is the local engine, and GitHub is the collaborative cloud platform. Which means to participate in the workshop, we need an account on that cloud platform. +**Jamie:** What is the one idea that makes the next few steps less mysterious? -**Alex:** Exactly. Step one is creating your GitHub account. You will navigate your browser to github dot com slash signup. The signup process is a single-page form. It will ask for your email address, a password, and a username. +**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. -**Jamie:** Let us talk about usernames for a second. Your GitHub username is public. It is going to appear on every piece of code you submit, every comment you make, and every project you contribute to. +--- -**Alex:** Right. Keep it professional. It represents you in the open source community. You can only use lowercase letters, numbers, and hyphens. +**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:** And we should warn people about the human verification step. When I signed up, I got completely stuck here because the default puzzle is highly visual. +**Jamie:** What would you say to someone who is already bracing for this to be too much? -**Alex:** I am really glad you brought that up. GitHub uses a visual capture puzzle to verify you are human, which is a known accessibility barrier. When your screen reader reaches that part of the form, you need to navigate to the button labeled Try an audio challenge. Activate that button. You will hear a short audio clip of spoken words or digits, and you will type what you hear into the text field. If that audio challenge does not load or fails, do not panic. Reach out to the workshop organizers and they can manually help verify your account. +**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:** Once your account is created, GitHub will send a launch code to your email. You copy that code, paste it into the browser, and you are in. But before we do anything else, we need to talk about security. Specifically, Two-Factor Authentication, or as you will often hear it called, two F A. +**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. -**Jamie:** I know a lot of people groan when they hear two F A, but it is actually required by most major open source projects now, right? +**Alex:** On the ground, that means a few things. origin - your fork on GitHub. upstream - the original repository you forked from. -**Alex:** It is. Two-factor authentication means that to sign into your account, you need two things. First, something you know, which is your password. Second, something you have, like a code from an app on your phone. Think of it like withdrawing money from an ATM. You need your physical debit card, which is the thing you have, and your PIN, which is the thing you know. If a hacker steals your password, they still cannot get into your GitHub account without that second factor. +--- -**Jamie:** So how do we set this up accessibly? +**Jamie:** What is the safe way to learn from that example? -**Alex:** You will navigate to your account settings, move to the Password and authentication section, and activate the Enable two-factor authentication button. GitHub gives you a few options. The most common is an authenticator app, like Microsoft Authenticator or Google Authenticator. +**Alex:** Start with To see your remotes. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** For screen reader users, scanning a visual QR code on the screen with a phone camera can be really frustrating. +**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:** Yes it can. And that is why you should navigate past the QR code graphic and activate the link that says enter this text code. That will reveal a long text string called a setup key. You just copy that text string and paste it into the manual entry field of your authenticator app. +**Jamie:** What should happen before anyone copies and runs it? -**Jamie:** Okay, so I have two F A turned on. I am secure. But wait, if I am using Git on my laptop terminal to send code up to GitHub, how does my terminal know my second factor code? +**Alex:** Start with To add a remote. There is something to understand, something to try, and something that proves the try worked. -**Alex:** That is a brilliant question. When you have two F A enabled, you can no longer use your standard GitHub password on the command line. Git will reject it. Instead, you need to use either a Personal Access Token, or an S S H key. +**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:** Okay, define those for me. +**Jamie:** Where do you want a learner to place their attention here? -**Alex:** Let us start with a Personal Access Token, often called a PAT. A PAT is a long, randomly generated string of characters that GitHub creates for you. You use it exactly like a password when Git asks for one. But unlike your main password, a PAT can be scoped. +**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. -**Jamie:** Scaped meaning limited? +--- -**Alex:** Exactly. Think of your main GitHub password like the master key to your house. It opens every door. A Personal Access Token is like a valet key you give to a parking attendant. It only starts the ignition, but it will not unlock the glove box or the trunk. You can create a PAT that only has permission to read and write code repositories, but cannot delete your account or change your billing settings. And you can set it to automatically expire after thirty days. +**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:** That is really smart. And what about the other option you mentioned, S S H keys? +**Jamie:** Give me the version that sounds like an instructor, not a manual. -**Alex:** S S H stands for Secure Shell. An S S H key is actually a pair of files generated on your computer. One is private, which stays securely on your hard drive, and one is public, which you upload to GitHub. Once they are linked, your computer and GitHub recognize each other automatically. No passwords or tokens to type ever again. +**Alex:** Start with Why use.gitignore? There is something to understand, something to try, and something that proves the try worked. -**Jamie:** I use S S H keys now and I love them, but I will say, generating them in the terminal was a bit intimidating on my first day. +**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:** Which is exactly why, for this workshop, we recommend starting with a Personal Access Token. It is entirely web-based, highly accessible to set up in the browser, and you just paste it into your credential manager once. +**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:** Now that we are authenticated, we need to adjust a few critical settings in the GitHub web interface. There is a dedicated Accessibility Settings page. You can reach it by opening the user navigation menu in the top right corner, selecting Settings, and then navigating to Accessibility in the left sidebar. +**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:** If listeners only take one thing away from this episode, let it be this next setting. Please, for your own sanity, disable Hovercards. +--- -**Alex:** I completely agree. A hovercard is a small pop-up window that appears when you move focus to a user's name or a repository link. It is meant to provide quick context. But for screen reader users, it is incredibly disruptive. +**Jamie:** How do you keep commands from becoming magic words? -**Jamie:** It is the worst. When I had it turned on, every single time I tabbed past a link, my screen reader would start reading a massive paragraph of metadata, and then announce the keyboard shortcut to open the card. It was like having a tour guide who interrupts you every time you walk past a painting to read you the entire Wikipedia article about the artist, while you are just trying to find the restroom. +**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:** That is the perfect analogy. So, on the Accessibility Settings page, navigate to the checkbox labeled Hovercards or Link Previews, and uncheck it. It saves automatically. While you are on that page, we also recommend checking the box for Link underlines. This forces all links on GitHub to have a solid underline, which is incredibly helpful for low-vision users who might struggle to distinguish links by color alone. +**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. -**Jamie:** Are there any other settings we need to change? +**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:** Yes, we need to check your Feature Previews. GitHub is constantly improving its interface, and they let users opt into new designs before they become the default. Open the user menu again and activate Feature Preview. You are looking for two specific items. The New Issues Experience, and the New Files Changed Experience. +**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 do those do? +**Jamie:** If I am listening before the workshop starts, what should settle in my mind first? -**Alex:** The New Issues Experience completely rebuilds how issue lists are structured. It adds proper heading levels, accessible list structures, and live regions so your screen reader announces when you apply a filter. The New Files Changed Experience does the same thing for code reviews, adding a navigable file tree and turning visual code comparisons into structured tables. +**Alex:** Start with Common branch names. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** So basically, they make everything we are going to do in the workshop actually accessible. +**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:** Exactly. If you find them in the Feature Preview list, activate the Enable button for both. If you do not see them in the list at all, do not worry. That just means GitHub has already made them the default for everyone, and you are good to go. +--- +**Jamie:** Let's pause on Commit. What should a learner take away from it? -**Alex:** Alright, our GitHub account is ready. Now we need to set up our local computer. That means installing Git, and installing our code editor. +**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.". -**Jamie:** Let us start with Git. How do we get that time machine onto our laptop? +**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:** It depends on your operating system. If you are on Windows, you will navigate to git dash s c m dot com, download the Git for Windows installer, and run it. The default options are perfectly fine. If you are on a Mac, Git is often already there. You can open your Terminal application and type git space dash dash version. If it is not installed, the Mac will automatically pop up a dialog asking if you want to install the command line developer tools. Just agree to that. Linux users can install it using their standard package manager, like apt or dnf. +**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:** Once it is installed, we have to introduce ourselves to Git, right? I remember this step. Configuring our Git identity. +**Jamie:** Let's pause on Diff. What should a learner take away from it? -**Alex:** That is right. Git embeds your name and your email address into every single snapshot, or commit, that you make. It needs to know who is making the changes. Think of it like signing the guestbook at an event. If you do not configure this, your commits might show up as authored by Unknown, which looks highly unprofessional, or Git might just refuse to save your changes entirely. +**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). -**Jamie:** How do we set that up? +**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:** You open your terminal and type two commands. The first is git space config space dash dash global space user dot name, followed by your full name in quotation marks. The second is git space config space dash dash global space user dot email, followed by the email address you used to sign up for GitHub. +**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. -**Jamie:** And a quick note here. The terminal is fully accessible. Whether you are using PowerShell on Windows with N V D A or JAWS, or the macOS Terminal with VoiceOver, you can read the output of your commands using your screen reader's review cursor or by simply arrowing up. +**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. -**Alex:** Now for the centerpiece of our local setup. Visual Studio Code, commonly called VS Code. +--- -**Jamie:** This is the recommended editor for the workshop, right? Why do we use VS Code instead of something else? +**Jamie:** Let's pause on Pull Request (PR). What should a learner take away from it? -**Alex:** VS Code is a free, open-source code editor built by Microsoft. We recommend it because its accessibility support is phenomenal. It has a dedicated team ensuring that screen readers can navigate complex codebases, interact with source control, and use artificial intelligence tools seamlessly. Think of VS Code as your digital workbench. It is where all your tools, your files, your terminal, and your version control live in one unified, accessible interface. +**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.". -**Jamie:** You can download it at code dot visual studio dot com. The installer is standard. But once you open it, there is a very specific setting you have to turn on immediately. +**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:** Yes. Screen Reader Optimized Mode. This is absolutely critical. By default, VS Code renders text in a highly visual way that screen readers struggle to parse efficiently. When you turn on Screen Reader Optimized Mode, VS Code completely changes how it outputs information. It renders the editor as a plain text region so you can arrow through it linearly. It turns visual side-by-side code comparisons into readable text. And it enables audio cues, which are little sounds that play to indicate errors, folded code, or inline suggestions. +**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. -**Jamie:** How do we turn it on? +**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. -**Alex:** Often, VS Code will detect your screen reader on startup and present a dialog asking if you want to enable it. If it does, just press Enter to accept. If it does not, you can toggle it instantly by pressing Shift plus Alt plus F1. +**Jamie:** Let's pause on Merge. What should a learner take away from it? -**Jamie:** Or you can use the Command Palette, right? The Command Palette is my favorite feature. You press Control plus Shift plus P on Windows, or Command plus Shift plus P on Mac, and it opens a search box where you can type any command. Just type screen reader, and you will find the toggle. +**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:** Exactly. Once your screen reader mode is on, we need to install two extensions. Extensions are like adding new power tools to your workbench. They give VS Code new capabilities. You open the Extensions view by pressing Control plus Shift plus X, and search for the ones we need. +--- -**Jamie:** The first one is the GitHub Pull Requests extension. What does that do? +**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. -**Alex:** A pull request is a request to merge your code changes into a main project. We will cover them deeply later. This extension allows you to review code, read comments, and manage pull requests entirely inside VS Code, without ever having to switch back to your web browser. +**Jamie:** Let's pause on Upstream. What should a learner take away from it? -**Jamie:** And the second extension is GitHub Copilot Chat. +**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:** Yes. Copilot is an artificial intelligence pair programmer. The Copilot Chat extension gives you a conversational interface right in your editor. You can press Control plus Shift plus I to open the chat, and ask it questions like, how do I undo my last Git commit? Or, can you explain what this Python function does? It will read the code you currently have focused and give you plain text answers. It is fully accessible and incredibly helpful when you are learning. +**Alex:** Here is the practical turn. Keep the learner anchored in Label. Labels are colored tags applied to issues and PRs to categorize them. -**Jamie:** And Copilot has a free tier now, right? +**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:** It does. Copilot Free is available to all GitHub users. It gives you a limited number of chat messages and code completions per month, which is more than enough for this workshop. You just need to sign into your GitHub account inside VS Code to activate it. +**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:** Alex, before we wrap up, I want to ask about something I heard some developers talking about. What if I am on a computer where I cannot install Git or VS Code? Like a library computer or a strict corporate laptop. Am I just locked out of contributing? +**Jamie:** Let's pause on Milestone. What should a learner take away from it? -**Alex:** Not at all. This brings us to a fantastic feature called github dot dev. It is a completely browser-based alternative. If you are looking at any repository on GitHub dot com, you can simply press the period key on your keyboard. +**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. -**Jamie:** Wait, just the period key? +**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. -**Alex:** Just the period key. When you press it, the web page transforms into a lightweight version of VS Code, running entirely inside your browser. It looks and acts exactly like the VS Code you install on your desktop. +**Jamie:** Let's pause on Maintainer. What should a learner take away from it? -**Jamie:** That is amazing. +**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:** It really is. Think of it like a pop-up tent version of your digital workbench. You can take it anywhere, it requires absolutely zero installation, and because it is built on the same architecture as desktop VS Code, all the screen reader accessibility features still work. You can edit files, commit changes, and push them back to the repository without ever touching your local hard drive. +--- -**Jamie:** I wish I had known about that trick when I started. Just press the period key. I love that. +**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. -**Alex:** It is incredibly handy for quick typo fixes or documentation updates. But for heavy development work, we still recommend the full desktop VS Code installation, because it gives you access to the local terminal and testing tools. +**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:** So, let us review our verification checklist before Day One. First, you have created your GitHub account, verified your email, and turned on Two-Factor Authentication. +**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:** Second, you went into GitHub's Accessibility Settings, turned off the extremely noisy Hovercards, and turned on Link underlines. +--- -**Alex:** Third, you installed Git, and configured your user dot name and user dot email in the terminal. +**Jamie:** Let's pause on Part 4: Common Abbreviations and Slang. What should a learner take away from it? -**Jamie:** Fourth, you installed Visual Studio Code, and immediately turned on Screen Reader Optimized Mode using Shift plus Alt plus F1. +**Alex:** Start with Common Abbreviations and Slang: These abbreviations appear frequently in GitHub comments, PR descriptions, and commit messages. -**Alex:** And finally, you installed the GitHub Pull Requests and GitHub Copilot Chat extensions, and signed into your GitHub account inside the editor. +**Jamie:** Let's pause on HEAD. What should a learner take away from it? -**Jamie:** If you can check all those boxes, you are completely ready for the workshop. But Alex, what if someone gets stuck on one of these steps? What if their terminal throws an error they do not understand, or their screen reader stops reading the editor? +**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:** Please do not suffer in silence. If you hit a roadblock, reach out to the workshop organizers immediately. You can file an issue on the Community Access repository, or send an email. We want to solve these setup quirks today. Every technical issue we fix before the workshop means more time for actual learning on Day One. You will not be left behind. +**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". -**Jamie:** This has been such a great overview. To summarize our key takeaways. Number one, Git is your local version control time machine, while GitHub is the web platform where you share and collaborate. Number two, disable Hovercards in your GitHub settings to keep your screen reader quiet and focused. Number three, always enable Screen Reader Optimized Mode in VS Code so your diffs and editor windows output clean, readable text. +**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. -**Alex:** Perfectly summarized. That brings us to the end of Episode One. Now that your tools are installed and configured, you are ready to start navigating. In Episode Two, we are going to dive into Understanding GitHub's Web Structure. We will explore how repository pages are laid out, which heading levels to jump to, and how to find exactly what you need without getting lost in the interface. +**Jamie:** Let's pause on Detached HEAD. What should a learner take away from it? -**Jamie:** I cannot wait. See you all in the next episode! +**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. -**Alex:** Thanks for listening to Gitt Going with GitHub. Keep practicing, and we will see you next 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. -### Episode 2: Understanding GitHub on the Web +**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. -How GitHub organizes its web pages, heading structure, landmarks, and keyboard shortcuts. +**Jamie:** Let's pause on What this means. What should a learner take away from it? -Based on: [Chapter 1: Understanding GitHub on the Web](docs/02-understanding-github.md) +**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". -[Download Episode 2 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep02-github-web-structure.mp3) +**Jamie:** Let's pause on How to fix it. What should a learner take away from it? -
-Read Transcript - Episode 2: Understanding GitHub on the Web +**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. -#### Transcript +**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. -**Alex:** Welcome to Gitt Going with GitHub. This is Episode 2: Understanding GitHub on the Web. I am your host, Alex, and I am here to guide you through learning GitHub and open source collaboration, specifically designed for screen reader users and developers with low vision. +--- -**Jamie:** And I am Jamie! I am so excited to be here. I learned GitHub about two years ago, and I still remember exactly how overwhelming it felt the first time I landed on a repository page. There is just so much information coming at you all at once. +**Jamie:** Let's pause on Stash. What should a learner take away from it? -**Alex:** It is incredibly overwhelming at first. In Episode 1, we made sure you had your GitHub account created and Git installed on your machine. Those were our prerequisites. Today, we are going entirely web-based. We are going to build a mental map of how GitHub organizes its web interface. Once you understand the underlying structure, the HTML headings, the ARIA landmarks, and the URL patterns, you will never feel lost on a GitHub page again. +**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:** I love the idea of a mental map. When I first started, I used to just press the Tab key about fifty times to find what I wanted. I had no map. I just had hope and a lot of patience. +**Jamie:** Let's pause on Common workflow. What should a learner take away from it? -**Alex:** We are definitely going to save your Tab key today. To start, let us talk about the big picture. GitHub is not just one type of page. It is a nested structure. Think of GitHub like a massive office building. +**Alex:** Start with Common workflow. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** Okay, an office building. I can picture that. +**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. -**Alex:** Right. When you first log in, you land on your dashboard. That is the lobby of the building. It shows you a feed of recent activity from projects you follow. Also in this lobby level, you have your profile page, which is like your employee badge showing your recent work, and your settings page, which is like the administrative office. +**Jamie:** What stays the same when the tool changes? -**Jamie:** So the dashboard, profile, and settings are all Level 1. The lobby. Where does the actual coding happen? +**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:** That happens in a repository. If the dashboard is the lobby, a repository is a dedicated project room on an upper floor. A repository is simply a central place where all the files, code, and history for a specific project live. When developers say, navigate to the repo, they mean navigate to that specific project room. +**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. -**Jamie:** And once you are inside that repository room, you have different stations, right? Like issues and pull requests. +--- -**Alex:** Exactly. Let us define those, because they are the most important page types you will interact with. An issue is basically a to-do ticket or a discussion thread. If you find a bug in the code, or you want to suggest a new feature, you open an issue. It has a title, a description, and a comment thread where people can discuss it. +**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:** And what about a pull request? +**Jamie:** Let's pause on When to use rebase. What should a learner take away from it? -**Alex:** So a pull request - and I love that name because you are literally requesting that someone pull your changes into their project - is what happens when you have actually written some code to fix that bug. You submit a pull request, often just called a PR, to propose your changes. The PR page is a bit more complex. It has the conversation thread, just like an issue, but it also has tabs to review the specific lines of code that were changed. +**Alex:** Start with When to use rebase. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** Okay, so to recap our building analogy. The dashboard is the lobby. The repository is the project room. An issue is a to-do ticket sitting on a desk in that room. And a pull request is a formal proposal to change something in that room. +**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:** That is a perfect summary. And no matter which of these rooms you are in, there are certain structural elements that are always present. Let us talk about how to navigate them without spamming the Tab key. +**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:** So, if I am not supposed to just Tab through the page, what is the first thing I should do when I land on a GitHub page? +--- -**Alex:** The very first thing you will encounter on every single GitHub page, if you are navigating from the top of the document, is the jump-to-content skip link. +**Jamie:** Let's pause on Basic rebase workflow. What should a learner take away from it? -**Jamie:** Oh, the skip link! I actually know this one. It is a hidden link right at the top of the page. If you press Tab exactly once when the page loads, your screen reader will announce, Skip to content. If you press Enter on it, it skips over all the global navigation links and drops your focus directly into the main, unique content of that specific page. +**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:** Exactly. It is a massive time saver. But sometimes, you actually do want to access that global navigation. The global navigation bar is present at the top of every single page on GitHub. It contains the GitHub logo, which takes you back to your dashboard lobby. It contains a global search bar. It has links to all your pull requests and issues across all your repositories, your notifications inbox, and your profile menu. +**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:** How do I jump straight to that global navigation if I am deep in the middle of reading an issue? +**Jamie:** Let's pause on Cherry-Pick. What should a learner take away from it? -**Alex:** This is where ARIA landmarks come in. ARIA landmarks are invisible structural signposts in the HTML that screen readers can recognize and jump between. Every screen reader has a shortcut to cycle through landmarks. If you are using NVDA or JAWS on Windows, you press the letter D. If you are using VoiceOver on a Mac, you press Control plus Option plus U to open the rotor, then use the arrow keys to select Landmarks. +**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. -**Jamie:** So if I press D, what will I hear? +**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. -**Alex:** The global navigation bar is wrapped in a landmark called Navigation Menu. So if you press D, your screen reader will say, Navigation Menu landmark. Once you hear that, you can press the letter K to move through the individual links inside it. +**Jamie:** Let's pause on When to use. What should a learner take away from it? -**Jamie:** That is so much faster. And what happens when I navigate into a repository? Do the landmarks change? +**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 Navigation Menu landmark stays exactly the same, because it is global. But a new landmark appears just below it, called the Repository navigation landmark. This contains the tabs specific to that project room: the Code tab, the Issues tab, the Pull requests tab, and so on. +**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:** Okay, so D for Navigation Menu gets me the global stuff. D again gets me the Repository navigation for the project tabs. What is below that? +--- -**Alex:** Below that is the Main landmark. This is where the actual content of the page lives. If you are on an issue, the Main landmark holds the issue description and comments. If you are on the repository home page, the Main landmark holds the file tree and the project Read Me. +**Jamie:** Let's pause on Fetch vs Pull. What should a learner take away from it? -**Jamie:** I remember struggling so much to find the reply box when I wanted to leave a comment on an issue. I would just scroll and scroll. Is there a landmark for that? +**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:** There is! This is one of my favorite GitHub accessibility features. On any page where you can leave a comment, like an issue or a pull request, there is a specific landmark called Add a comment. You just press D until you hear Add a comment landmark, and you are right at the text box, ready to type. +**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? -**Jamie:** Okay, so landmarks are like the major zones of the page. Global nav, repo nav, main content, and the comment box. What about the actual content itself? If I am in the Main landmark, how do I know what I am looking at? +**Alex:** Start with When to use fetch. There is something to understand, something to try, and something that proves the try worked. -**Alex:** For that, we use the HTML heading structure. GitHub is very disciplined about how they use headings, and learning their pattern is the key to orienting yourself. +**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. -**Jamie:** I use the letter H to jump between headings all the time. But how do you use it for orientation? +**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:** Think of the Heading Level 1, or H1, as your You Are Here marker on a shopping mall directory map. It tells you exactly what page you are on. Every time you land on a new GitHub page, I recommend pressing the number 1 on your keyboard to jump straight to the first H1. +**Alex:** The practical takeaway is this. You know you want the latest changes merged immediately. You're working alone on a branch. -**Jamie:** What will I hear when I press 1? +--- -**Alex:** It depends on the page type. If you navigate to a repository home page and press 1, you will hear the owner name slash the repository name. For example, community-access slash accessibility-agents. That confirms you are in the right project room. If you navigate to the issues list and press 1, you will just hear Issues. +**Jamie:** Let's pause on Force Push. What should a learner take away from it? -**Jamie:** And if I open a specific issue? +**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:** If you open an issue and press 1, the H1 is the title of the issue itself. Like, Fix contrast on submit button. Same for a pull request. The H1 is always the title of the PR. +**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. -**Jamie:** That is so consistent. I love that. So H1 tells me where I am. What about the rest of the content? +**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. -**Alex:** Below the H1, GitHub uses H2s for major sections, and H3s for individual items. For example, on an issue detail page, the H1 is the issue title. Below that, there is an H2 called Description, which is the original bug report. Below that is an H2 called Activity, which contains all the comments. +**Jamie:** Let's pause on When force push is NEVER okay. What should a learner take away from it? -**Jamie:** Oh, and let me guess, the individual comments are H3s? +**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:** You guessed exactly right. Every single comment on an issue or a pull request starts with an H3 heading that contains the author's username and the timestamp. So, if you open an issue with forty comments, you do not have to read them line by line. You just press the number 3 on your keyboard to jump from comment to comment, hearing who wrote it and when. +**Alex:** The practical takeaway is this. The main branch. Shared branches where others have based work on your commits. Public branches with collaborators. -**Jamie:** That is brilliant. I wish I had known that when I started. I used to read the entire page from top to bottom. Okay, that sounds like a lot of steps to remember, though. Press D for landmarks, press 1 for the title, press 3 for comments. +--- -**Alex:** It does sound like a lot! But here is the thing - you have already done most of this on Day 1 when you were browsing the web. It is the exact same workflow, just applied to a highly structured application. I recommend a ten-second orientation sequence every time you open a GitHub link. +**Jamie:** Let's pause on Safer alternative: --force-with-lease. What should a learner take away from it? -**Jamie:** Walk me through the ten-second sequence. +**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:** Step one: press the number 1. Listen to the H1 to confirm what page you are on. Step two: press D a few times to cycle through the landmarks, so you know what regions are available on this page. Step three: pull up your screen reader's Elements List. In NVDA, that is NVDA plus F7. In JAWS, it is Insert plus F6 for the headings list. +**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:** Ah, the Elements List! That brings up a dialog box with a clean list of every heading on the page, right? Like a table of contents. +**Jamie:** Let's pause on Why force push is needed after rebase. What should a learner take away from it? -**Alex:** Exactly. By doing those three things, which takes about ten seconds, you know exactly what page you are on, where the major zones are, and you have scanned the table of contents. You are completely oriented without needing to see the visual layout at all. +**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. -**Jamie:** One quick warning for folks - I remember getting really confused once because the landmarks disappeared. It turned out I had my browser window snapped to half the screen. GitHub is responsive, so when the window got narrow, it collapsed the sidebar and hid some of the navigation into a mobile-style menu. +**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. -**Alex:** That is a fantastic point, Jamie. To get the most consistent heading and landmark experience, always keep your browser window maximized when working on GitHub. +--- +**Jamie:** Let's pause on Tag / Release. What should a learner take away from it? -**Jamie:** So, navigating by headings and landmarks is great. But earlier you mentioned there are ways to jump around without even doing that. You mentioned built-in keyboard shortcuts. +**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:** Yes. GitHub has its own complex system of keyboard shortcuts built directly into the web application. They are powered by JavaScript, and they let you do things like jump straight to the pull requests tab, or filter issues by assignee, all with single keystrokes. +**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:** But wait. If I press the letter H to use a GitHub shortcut, my screen reader is just going to intercept it and jump to the next heading, right? +**Jamie:** Let's pause on Status Check. What should a learner take away from it? -**Alex:** Exactly. And this is the single biggest point of friction for screen reader users learning GitHub. You have to understand the difference between your screen reader's Browse Mode and Focus Mode. +**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. -**Jamie:** Can you break that down for us? +**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:** Absolutely. Browse Mode, which JAWS calls the Virtual Cursor, is what you use to read pages. In this mode, your screen reader intercepts your keystrokes. Pressing H goes to a heading. Pressing B goes to a button. The web page never hears you press those keys. +--- -**Jamie:** Right, because if the web page heard it, you would just be typing the letter H over and over. +**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. -**Alex:** Exactly. Focus Mode, on the other hand, is what you use to type into text boxes. When you enter Focus Mode, the screen reader stops intercepting keys and passes them directly through to the web page. Usually, your screen reader switches to Focus Mode automatically when you land on a text box. +**Jamie:** Let's pause on GitHub Discussions. What should a learner take away from it? -**Jamie:** But to use GitHub's custom keyboard shortcuts, we need to manually switch to Focus Mode even when we are not in a text box, right? So the page can hear the keystroke. +**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:** You nailed it. If you want to use a GitHub shortcut, you must manually enter Focus Mode first. In NVDA, you press NVDA plus Space. In JAWS, you press Insert plus Z. You will hear a little click or chime. Now, your keystrokes are going straight to GitHub. +**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:** Okay, so once I am in Focus Mode, what are these magical GitHub shortcuts? How do I learn them? +--- -**Alex:** You do not have to memorize them from a manual. GitHub has a built-in cheat sheet. If you press the Question Mark key - which is Shift plus Slash - GitHub opens a dialog box that lists every single shortcut available for the exact page you are currently on. +**Jamie:** Let's pause on GitHub Copilot. What should a learner take away from it? -**Jamie:** Oh, that is clever! So the list changes depending on whether I am in the lobby dashboard or the project repository? +**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:** Yes, it is context-aware. Let us say you are in a repository. You press NVDA plus Space to enter Focus Mode. Then you press Shift plus Slash to open the shortcut menu. You will see shortcuts like pressing the letter G followed by the letter I to jump straight to the Issues tab. Or G followed by P to jump to the Pull Requests tab. Think of them as the secret elevator buttons in our office building. +**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:** So G stands for Go. Go to Issues, Go to Pull Requests. That makes total sense. And once I am done using the shortcut, I need to remember to press NVDA plus Space again to turn Browse Mode back on, so I can read the new page with my normal heading keys. +**Jamie:** Let's pause on Learning Cards: Alphabetical Quick Reference. What should a learner take away from it? -**Alex:** Exactly. It takes a little practice to toggle between Focus Mode and Browse Mode, but it unlocks incredible speed. And there is one shortcut that is so powerful, you do not even need to toggle modes to use it, because it automatically throws your focus into a text field. +**Alex:** Start with Learning Cards: Alphabetical Quick Reference. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** Ooh, I know this one. The Command Palette! +**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:** Yes, the Command Palette. You can reach it from any page on GitHub by pressing the Forward Slash key, or by pressing Control plus K. +--- -**Jamie:** Control plus K is my absolute favorite. What does it actually do? +**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. -**Alex:** When you press Control plus K, a search box pops up in the middle of your screen. But it is not just for searching text. It is a command center. You can type the name of a repository, and press Enter to jump straight to it. You can type the name of a file, or type the word settings to jump to your settings page. +--- -**Jamie:** To use our building analogy, the Command Palette is like a magical concierge desk. You just walk up, press Control plus K, tell them where you want to go, and they instantly teleport you there. You do not even need to know which floor it is on. +**Jamie:** What should people carry with them after this? -**Alex:** That is a perfect analogy. The Command Palette is incredibly powerful for accessibility because it completely bypasses the need to navigate through complex menus or nested tabs. You just declare your intent, and GitHub takes you there. +**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. -**Jamie:** Alex, there is one more shortcut I have heard people talk about, and it sounds almost like magic. Something about pressing the period key? +**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:** Ah, yes. The period key shortcut. This is one of the most remarkable features GitHub has introduced in recent years. It is the bridge between reading code on the web and actually editing it. +
-**Jamie:** How does it work? +--- -**Alex:** If you are on any repository page or viewing any file on GitHub, and you switch to Focus Mode and press the period key, the entire web page transforms. You leave github dot com, and you are redirected to a URL that says github dot dev. +### 3. Episode 1: Pre-Workshop Setup -**Jamie:** Github dot dev. What is the difference? +Creating your GitHub account, installing Git and VS Code, configuring your screen reader. -**Alex:** Github dot com is the standard web interface we have been talking about—the issues, the pull requests, the project rooms. Github dot dev is a fully functioning version of Visual Studio Code, the code editor, running entirely inside your web browser. +Based on: [Chapter 0: Pre-Workshop Setup](docs/00-pre-workshop-setup.md) -**Jamie:** Wait, so I do not have to install anything? I just press the period key, and suddenly I am in a professional code editor with the entire project loaded up? + -**Alex:** Exactly. No installation, no cloning the repository to your local computer, no terminal commands. It just opens the project in a web-based editor. And because it is VS Code, it has excellent screen reader support built right in. +[Download Episode 1 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep01-pre-workshop-setup.mp3) -**Jamie:** That is wild. Why would I use that instead of just downloading the code to my laptop? +
+Read Transcript - Episode 1: Pre-Workshop Setup -**Alex:** It is perfect for quick changes. Let us say you are reading the project Read Me, and you notice a typo. Instead of opening your terminal, downloading the project, opening your local editor, fixing the typo, and pushing the code back up... you just press the period key. The editor opens in your browser, you fix the typo, you commit the change from the web interface, and you are done. +#### Transcript -**Jamie:** I love that. It lowers the barrier to entry so much. If someone finds an accessibility bug in documentation, they can fix it in literally two minutes right from the browser. +**Alex:** Welcome back to Git Going with GitHub. This is episode 1: Pre-Workshop Setup. I am Alex, and today we are turning Pre-Workshop Setup from a list of instructions into a working mental model. -**Alex:** Exactly. Now, there is one pro-tip for screen reader users regarding the period key. If you just press period, it transforms your current browser tab into the editor. When you are done, you have to hit the back button to get back to GitHub. A better way is to press Shift plus Period, which types the greater-than symbol. +**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:** What does Shift plus Period do? +--- -**Alex:** It opens github dot dev in a brand new browser tab. That way, you keep your original GitHub page open in your first tab, and you have your code editor in the second tab. It is much easier to keep your mental map intact that way. +**Alex:** Creating your GitHub account, installing Git and VS Code, configuring your screen reader. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result. -**Jamie:** Shift plus Period for a new tab. I am definitely writing that one down. +**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:** We have covered a massive amount of ground today, Jamie. Let us wrap up with some concrete takeaways for our listeners to practice. +--- -**Jamie:** I will take the first one! Takeaway number one: Think of GitHub like a building. The dashboard is the lobby, the repository is the project room, issues are to-do tickets, and pull requests are formal proposals to change the code. +**Jamie:** What does someone need before they touch the keyboard? -**Alex:** Perfect. Takeaway number two: Use the ten-second orientation sequence on every new page. Press the number 1 to hear the H1 heading and know where you are. Press D to scan the ARIA landmarks like Navigation Menu and Main. And use your screen reader's Elements List to read the table of contents. +**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. -**Jamie:** Takeaway number three: Comments are always H3 headings. If you want to read a discussion thread quickly, just press the number 3 to jump from author to author without reading every single line in between. +**Alex:** The next layer is this. Start with Hardware. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Takeaway number four: Learn to toggle Browse Mode and Focus Mode. Use NVDA plus Space, or Insert plus Z, to enter Focus Mode so you can use GitHub's built-in shortcuts. Press Shift plus Slash to open the cheat sheet for whatever page you are on. +**Alex:** The practical anchors are these. A computer running Windows or macOS. A reliable internet connection. Headphones (recommended - screen reader audio during group sessions). -**Jamie:** And takeaway number five: When in doubt, teleport. Press Control plus K to open the Command Palette, type where you want to go, and press Enter. Or press Shift plus Period to instantly open the code in a web-based editor. +**Jamie:** What should feel predictable before the first live session starts? -**Alex:** Those are excellent takeaways. Now that you have a mental map of the building, and you know how to navigate the hallways, you are ready to start looking at the code itself. In Episode 3, we are going to dive deep into Navigating Repositories. We will cover how to read the file tree, how to switch between different branches of code, and how to read the project documentation. +**Alex:** Start with Software - Day 1. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** I cannot wait. I am ready to get out of the lobby and into the project rooms. +**Alex:** That shows up in the workshop in a few specific ways. 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). -**Alex:** Until then, open up your browser, head to GitHub, and practice your ten-second orientation. Thank you for listening to Gitt Going with GitHub. We will see you in the next episode. +--- -
+**Alex:** Now bring the learner back to the room. Start with Software - Required Before the Workshop. There is something to understand, something to try, and something that proves the try worked. +**Alex:** For a learner, the useful signals are these. 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). -### Episode 3: Navigating Repositories +**Jamie:** How should someone choose between those options? -Exploring a repository: tabs, files, README, branches, and commit history. +**Alex:** The reason Screen Reader Options matters is that use whichever you are most comfortable with. That gives the learner a simple foothold: all workshop exercises are designed to work with any of these screen readers. -Based on: [Chapter 2: Navigating Repositories](docs/03-navigating-repositories.md) +**Alex:** Use the comparison to make a decision, not to recite a table. The main contrasts are: Screen Reader means Platform means Download. NVDA (NonVisual Desktop Access) means Download NVDA. JAWS (Job Access With Speech) means Paid (trial available) means Download JAWS. - +**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. -[Download Episode 3 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep03-navigating-repositories.mp3) +**Alex:** That matters because of the next idea. Start with Step 1 - Create Your GitHub Account: See also: Appendix D: Git Authentication covers SSH keys and personal access tokens in detail. The next useful detail is this: If you already have a GitHub account, skip to Step 2. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need. -
-Read Transcript - Episode 3: Navigating Repositories +**Alex:** The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work. -#### Transcript +--- -**Alex:** Welcome to Gitt Going with GitHub. This is episode three, Navigating Repositories. I am Alex, and I am so glad you are joining us today. +**Jamie:** How would you walk the room through that step by step? -**Jamie:** Hello everyone! I am Jamie, and I am incredibly ready for this one. +**Alex:** Here is the plain-English version of Create an account. GitHub presents a visual CAPTCHA puzzle to verify you are human. Put another way, follow the on-screen prompts - typically clicking images that match a category, or checking a box. -**Alex:** Today we are diving into the absolute core of GitHub. We are going to explore what a repository actually is, how to read its history, and how to navigate its structure using your screen reader. We will cover branches, cloning, forking, and all those different sections you encounter when you first open a project. +**Alex:** Here is what that changes in practice. Type your email address and press Tab or activate Continue. Choose a password of at least 8 characters (15+ recommended). Press Tab or Continue. Your username appears on every issue, PR, and comment you make. Guidelines. Use lowercase letters, numbers, and hyphens only. -**Jamie:** And just a quick reminder, if you have not listened to episode two, you might want to jump back and check it out. In that episode, we covered the basic structure of a GitHub page. We talked about navigating by headings, using landmarks to find your way around, and using the built in keyboard shortcuts. We will be building directly on those skills today. +**Alex:** First, open your browser and navigate to the GitHub signup page. Then, the page loads with focus on the first field: "Enter your email address". After that, the next field is "Create a password". Finally, the next field is "Enter a username". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. -**Alex:** Exactly. If you are comfortable moving through landmarks and jumping to headings, everything we talk about today is going to feel very approachable. +**Jamie:** What does the learner do first, second, and then after that? +**Alex:** First, the next question asks whether you want to receive product updates by email. Then, human verification step. After that, activate the Create account button. Finally, GitHub sends a launch code (a short numeric code) to your email inbox. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Alex:** Let us start at the very beginning. What is a repository? At its most basic level, a repository is essentially a project folder that is tracked by Git. It holds all the files, all the folders, and the complete documentation for a specific project. +**Alex:** This is where the talk moves from concept to action. This is where Verify your email address becomes real: GitHub also sends a separate email verification link after account creation. That matters in practice: Check your inbox for an email from GitHub with subject "Please verify your email address" and activate the link inside it. -**Jamie:** When I was learning this a couple of years ago, I realized a repository is not just a folder. It is like a magical filing cabinet with a built in time machine. It does not just hold the files as they are right now. It holds every single version of every single file, going all the way back to the very first day the project was created. +**Jamie:** Where does the workshop stop being a tour and start becoming contribution? -**Alex:** That is a perfect way to describe it. It is the entire history of the project. And when you navigate to a repository address, like github dot com slash owner slash repo name, you land on the repository home page. +**Alex:** Keep the learner anchored in 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. This is the part to say slowly: GitHub now requires 2FA for all accounts, so you may already have it enabled. -**Jamie:** Right, and as soon as the page loads, your screen reader will announce the page title, which tells you the owner and the repository name. If you press the number one key, you will jump straight to the main heading one, which is also the repository name. +--- -**Alex:** Once you are on that page, the first major landmark you want to find is the repository navigation landmark. You can reach this by pressing the D key to cycle through your landmarks. This navigation area contains the tab bar, which is how you move between the different sections of the repository. +**Jamie:** What is the ordered workflow? -**Jamie:** I like to think of these tabs as different rooms in an office building. They all belong to the same company, but different types of work happen in each room. +**Alex:** Start with Quick steps to enable 2FA. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Let us walk through those rooms. The default tab, the one you land on first, is the Code tab. We will spend a lot of time here. Next to it, you will find the Issues tab. +**Alex:** That becomes easier when you listen for these cues. 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. 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. -**Jamie:** Issues are your discussion board. This is the room where people report bugs, request new features, or ask questions. If you find a problem with the software, you go to the Issues tab to tell the team about it. +**Alex:** First, open the GitHub security settings page while signed in. Then, under Two-factor authentication, choose Enable and follow the prompts. After that, choose one of the second-factor methods (recommended order). The rhythm is simple: orient, act, verify, then continue. -**Alex:** Next is the Pull Requests tab. So a pull request, and I love that name because you are literally requesting that someone pull your changes into their project, is a proposal to merge your code. When you write new code and want to share it with the project, you open a pull request. +**Jamie:** What is the pre-flight check here? -**Jamie:** Then we have the Actions tab. Actions are automated scripts. This is the robot room of the office. It is where automated tests run every time someone submits new code, to make sure nothing is broken. +**Alex:** Start with Detailed setup notes. There is something to understand, something to try, and something that proves the try worked. -**Alex:** And finally, depending on your permissions, you might find the Settings tab. This is the manager's office. It is usually only visible to the maintainers of the project, and it is where they control permissions and repository features. +**Alex:** A few details make that real. 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. +**Alex:** Hold that next to this. Start with Recovery and backup. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Let us focus on that first tab, the Code tab. When you are on the Code tab, the main piece of content is the files table. This table shows every file and folder currently in the project. +**Alex:** The parts worth keeping in working memory are these. 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. -**Jamie:** To get to the files table quickly, I press the T key to jump to the next table on the page. My screen reader will announce something like, table with twenty rows and three columns. +--- -**Alex:** Those three columns are very important. The first column is the Name of the file or folder. The second column is the Message, which tells you the most recent change made to that specific file. And the third column is the Age, which tells you how long ago that change happened. +**Jamie:** Turn that into a path someone can follow. -**Jamie:** Navigating this table is a great time to use your screen reader table commands. If I am using N V D A or Jaws, I hold down Control and Alt, and use my arrow keys. Pressing Control plus Alt plus Down Arrow moves me to the next row, which is the next file. Pressing Control plus Alt plus Right Arrow moves me across the columns, from the file name, to the message, and then to the age. +**Alex:** This is where Authenticating Git with GitHub: browser-based sign-in (OAuth) becomes real: when you use Git inside VS Code or GitHub Desktop, you do not need to manage passwords, tokens, or SSH keys manually. That matters in practice: These tools use browser-based OAuth sign-in - the same "Sign in with GitHub" flow you use on any website. -**Alex:** And if you are using VoiceOver on a Mac, you will hold down the V O keys, plus Shift, and use your arrow keys to move through the table cells. +**Alex:** First, the first time you push or pull code, VS Code (or GitHub Desktop) opens your default web browser to a GitHub authorization page. Then, 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). After that, approve the authorization request. Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Jamie:** One thing that confused me at first was telling the difference between a file and a folder in that table. But I learned that if it is a folder, the screen reader will announce a slash at the end of the name. If you press Enter on a folder, the page reloads and shows you the contents of that 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. -**Alex:** Exactly. Now, immediately following the files table in the reading order is the read me section. The read me dot m d file is a markdown file that acts as the welcome mat for the project. GitHub automatically renders this file and displays it right below the files table. +**Alex:** That connects to another useful point. Keep the learner anchored in Workshop policy. For this workshop, participants need a GitHub account with 2FA enabled. This is the part to say slowly: The browser-based sign-in described above handles all Git authentication automatically - no additional setup is required beyond having a working GitHub account. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor. -**Jamie:** The read me is its own landmark region, so you can press D to jump to it. Because it is rendered markdown, it has a full heading structure. I always press the H key to read through the headings in the read me so I can quickly understand what the project does and how to install it. +**Jamie:** What is the one idea that makes the next few steps less mysterious? +**Alex:** Start with Learning Cards: Create Your GitHub Account. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Before you reach the files table, there is a very important control called the branch selector. To understand this, we need to define what a branch is, and why repositories have them. +**Alex:** On the ground, that means a few things. 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. 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. -**Jamie:** A branch is a separate line of development inside a repository. If we all edited the exact same files at the exact same time, it would be complete chaos. Branches give us parallel timelines to work in safely. +--- -**Alex:** That is exactly right. A branch lets you isolate your work. +**Alex:** Here is the practical turn. Start with Step 2 - Configure GitHub Accessibility Settings: These settings make GitHub significantly more usable with a screen reader. The next useful detail is this: Do not skip this section - one setting in particular (hovercards) adds significant noise to every page if left on. -**Jamie:** My favorite analogy for a branch is baking. Imagine you are baking a cake from a cherished family recipe. You want to try adding lemon zest to the batter, but you absolutely do not want to ruin the original recipe card in case your experiment tastes terrible. So, you copy the entire recipe onto a brand new card, write Lemon Experiment at the top, and make your changes there. That new card is a branch. If the cake turns out delicious, you can permanently update the original recipe later. +**Jamie:** Give me the sequence, because order matters here. -**Alex:** And that original recipe card has a name. It is called the default branch. On modern GitHub projects, the default branch is almost always named main. The main branch holds the stable, official version of the project. Whenever you navigate to a repository, you are viewing the main branch by default. +**Alex:** Here is the plain-English version of Navigate to Accessibility Settings. The fastest path for everyone: navigate directly to GitHub Accessibility Settings while signed in. Put another way, if you prefer to navigate through the interface. -**Jamie:** To switch to a different branch, you use the branch selector. You can press the B key to jump to buttons until you hear the current branch name, which usually sounds like main branch button. When you press Enter, it opens a dropdown panel. +**Alex:** First, click your profile picture (avatar) in the top-right corner of any GitHub page. Then, a dropdown menu appears - click Settings. After that, on the Settings page, scroll the left sidebar and click Accessibility. Finally, 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). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. -**Alex:** This dropdown is a live region. As soon as it opens, your focus is placed in a search field. You can simply start typing the name of the branch you are looking for. +**Jamie:** Let's pause on Navigate to Accessibility Settings. What should a learner take away from it? -**Jamie:** Then, you press the Tab key to move into the filtered results list, and use your Up and Down arrows to find the exact branch. Once you press Enter, the entire page reloads, and the files table will now show the code exactly as it exists on that specific branch. +**Alex:** First, press B repeatedly until you hear "Open user navigation menu, button" (top-right of the page) and press Enter. Then, navigate the menu with ↓ or K until you hear "Settings" and press Enter. After that, on the Settings page, press D to move through landmark regions until you reach the left sidebar navigation. Finally, press K or ↓ to navigate through sidebar links until you hear "Accessibility" and press Enter. 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 Settings to configure becomes real: all are on the Accessibility settings page unless noted. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed. -**Alex:** Let us talk about the history of those changes. When you are exploring the files table, you hear the message column. Those messages come from commits. A commit is a saved snapshot of your changes at a moment in time. +--- -**Jamie:** I like to think of the commit history as the ultimate project guestbook. If the repository is a magical filing cabinet, the commit history is the unalterable ledger sitting right on top of it. Every single time someone puts a file in or takes one out, they have to sign the ledger, write the exact date and time, and write a little note explaining exactly what they did and why. +**Jamie:** Let's pause on 1. Disable Hovercards (highest priority). What should a learner take away from it? -**Alex:** That is a great comparison. A commit is not just the code that changed. It is the who, the what, and the when. And you can read this entire ledger. On the Code tab, you can navigate to a link that says something like, one thousand commits. +**Alex:** Keep the learner anchored in 1. Disable Hovercards (highest priority). Hovercards are the most disruptive default setting for screen reader users on GitHub. This is the part to say slowly: When enabled, every link announces its hover keyboard shortcut (H) as you navigate past it, dramatically slowing page reading. -**Jamie:** When you activate that link, you are taken to the commit history page. The commits are grouped by date, and you can use your heading navigation, pressing the H key or the number three key, to jump through the dates. Then you use the I key to move through the individual list items, which are the commits themselves. It is fascinating to read through the history and see how a project evolved day by day. +**Alex:** First, on the Accessibility settings page, switch to Browse Mode if not already active. Then, press F or X to jump through form controls until you hear "Link previews" or "Hovercards". After that, if it is announced as checked or on, press Space to turn it off. Finally, the change saves automatically - no Submit button required. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. +**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:** So far, we have been browsing code on the GitHub website. But eventually, you will want to work on the code yourself. This brings us to two fundamental concepts, cloning and forking. Let us define cloning first. What does cloning mean? +**Jamie:** Let's pause on 2. Enable Link Underlines. What should a learner take away from it? -**Jamie:** Cloning means copying a remote repository from GitHub down to your local computer. You are making a full, working clone of the project on your own hard drive, including its entire history. +**Alex:** The reason 2. Enable Link Underlines matters is that find the Link underlines checkbox or toggle and turn it on. That gives the learner a simple foothold: this adds underlines to all links on GitHub, making them distinguishable without relying on colour alone. -**Alex:** Right. If the repository is a massive encyclopedia in the library, cloning is like checking that encyclopedia out and bringing it to your own desk at home. You can flip through all the pages, read the history, and work with the material entirely offline. +**Alex:** First, press F or X to navigate form controls until you hear "Link underlines". Then, if it is announced as unchecked, press Space to enable it. After that, the change saves automatically. The rhythm is simple: orient, act, verify, then continue. -**Jamie:** But what if I want to make changes and give them back to the project? I do not have permission to just change their official encyclopedia. This is where forking comes in. A fork is a personal copy of someone else's repository, but it lives in your own GitHub account in the cloud. +**Jamie:** Let's pause on 3. Character Key Shortcuts. What should a learner take away from it? -**Alex:** Exactly. You fork a project on GitHub to create your own copy where you have full control. +**Alex:** Start with 3. Character Key Shortcuts. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** My analogy for forking is business. Forking is like buying a franchise of a popular restaurant. You are given the exact blueprints, the menu, and the operations manual of the original restaurant. But this new building belongs to you. You can try out new recipes in your kitchen without affecting the original restaurant. But, if you invent a brilliant new dish, you can send a proposal back to headquarters, asking them to add it to the official menu. That proposal is your pull request. +**Alex:** The room should hear these as checkpoints. 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. -**Alex:** That is brilliant. So, to recap the workflow, you fork the original project to your GitHub account, and then you clone your personal fork down to your computer. +**Alex:** First, find "Character key shortcuts". Then, single-key shortcuts (H for next heading, I for next issue, etc.) speed up navigation but can conflict with screen reader quick-navigation keys. After that, leave at the default unless you have a reason to change it. Think of it as a rail line: each stop confirms you are still on the right route before the next one. -**Jamie:** OK that sounds like a lot of steps. I navigate to the repository, I fork it on the website, then I open my terminal, then I find the web address, and then I clone my fork to my computer? +--- -**Alex:** It does! But here is the thing, you have already done most of this on Day One. Same workflow, just with V S Code handling the heavy lifting. Once you understand the concepts, the actual execution becomes second nature. +**Jamie:** Let's pause on 4. Set Your Theme (Appearance Settings). What should a learner take away from it? +**Alex:** Here is the plain-English version of 4. Set Your Theme (Appearance Settings). Theme is on a separate page: GitHub Appearance Settings. It 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:** Let us talk about the actual mechanics of cloning. When you are on the Code tab, there is a very prominent button labeled simply, Code. +**Alex:** These are the details that keep the idea from floating away. 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. -**Jamie:** I usually navigate to the main repository heading by pressing the number one key, and then press the B key to move to the next button, which is the Code button. When you press Enter or Space to activate it, it opens a flyout panel. +**Alex:** First, navigate to that page. Then, find the "Theme mode" or "Theme" section. After that, options available. Finally, select your preferred theme and activate Save if prompted (some changes apply immediately). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. -**Alex:** This panel has a few different tabs for how you can get the code, specifically H T T P S, S S H, and GitHub C L I. +**Jamie:** What would you say to someone who is already bracing for this to be too much? -**Jamie:** If you are using standard Git in your terminal, you would make sure the H T T P S tab is selected, press the Tab key to find the copy url to clipboard button, and press Enter. Then you go to your terminal and type git clone, followed by a space, and paste that long web address. +**Alex:** Start with Learning Cards: Configure GitHub Accessibility Settings. There is something to understand, something to try, and something that proves the try worked. -**Alex:** But there is a faster way if you have the GitHub Command Line Interface installed. We call it the g h tool. +**Alex:** The practical takeaway is this. 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. 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. -**Jamie:** Oh I love the g h tool. In that same flyout panel, you can choose the GitHub C L I tab. The command it gives you is so much simpler. Instead of a long web address, you just type g h repo clone, followed by a space, and then the owner name, a slash, and the repository name. So to clone the learning room, you just type g h repo clone community dash access slash learning dash room. It is so clean. +**Alex:** Another way to ground it. Keep the learner anchored in Step 3 - Configure Your Profile. Your GitHub profile is your public identity in the open source community. This is the part to say slowly: Setting it up properly helps maintainers know who you are. -**Alex:** It really is. Now, what if someone just wants the files to read, and they do not care about the Git history or making contributions? +--- -**Jamie:** If you keep pressing the Tab key inside that Code flyout panel, you will eventually reach a button called Download zip. This gives you a compressed zip folder of the code exactly as it is right this second. +**Jamie:** Okay, set the room for us. What are we walking into? -**Alex:** Right. But remember, a downloaded zip folder is not tracked by Git. It is like printing out a physical photograph of the code instead of downloading the digital file. You can look at it, but you cannot push any changes back to GitHub from a downloaded zip file. You only use Download zip if you are just exploring. +**Alex:** The reason Who are maintainers? matters is that maintainers are the people who manage a repository -- they review contributions, respond to issues, merge pull requests, and keep the project running. That gives the learner a simple foothold: when you open an issue or submit a pull request, a maintainer is the person who will see it and respond. +**Jamie:** Let's pause on Update your profile. What should a learner take away from it? -**Alex:** Before we wrap up, we need to talk about one more important region on the repository page. The sidebar. +**Alex:** Start with Update your profile. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** Yes! After the read me section in the reading order, you will find the sidebar content. To get there quickly, I press the D key until I reach the Main landmark, and then I press the number two key or the H key to jump to the heading called About. +**Alex:** The practical takeaway is this. 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. -**Alex:** The About section is critical because it contains the project description, a link to the project website if they have one, and the repository topics. +**Alex:** First, navigate to Settings → Public profile. Then, fill in. Think of it as a rail line: each stop confirms you are still on the right route before the next one. -**Jamie:** Topics are essentially tags. They tell you what the project is built with or what it is for. You might hear topics like python, accessibility, screen reader, or machine learning. It is a great way to quickly understand the context of the code. +**Jamie:** Where do you want a learner to place their attention here? -**Alex:** And right next to the About section, you will find the license. The license is fundamentally what makes open source work. It is a legal document that tells you exactly what you are allowed to do with this code. If a repository does not have a license, you technically do not have permission to use, modify, or distribute it, even if it is completely public on GitHub. Always check the license. +**Alex:** Here is the plain-English version of Add a profile picture (strongly recommended). A profile picture is strongly recommended because it humanizes your contributions and helps maintainers and collaborators recognize you across issues, pull requests, and comments. Put another way, it can be a photo or any image that represents you. +--- -**Alex:** We have covered a massive amount of ground today. Let us review our main takeaways. +**Jamie:** Let's pause on Set your notification email. What should a learner take away from it? -**Jamie:** Takeaway number one. A repository is your main project container. You can navigate its different areas, like Code, Issues, and Pull Requests, by finding the Repository Navigation landmark. +**Alex:** Start with Set your notification email. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Takeaway number two. The Code tab contains the files table. You can use your screen reader table commands to read across the rows, checking file names, commit messages, and how long ago the file was changed. +**Alex:** First, navigate to Settings → Notifications. Then, add a custom routing email if you want GitHub notifications to go to a different address than your account email. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Jamie:** Takeaway number three. Branches let you work on parallel versions of the code safely, just like testing a recipe on a new card. The official, stable version is almost always kept on the default branch, which is called main. +**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:** Takeaway number four. Forking creates your own personal copy of a project in the GitHub cloud, like buying a franchise. Cloning downloads a working copy to your local computer, like checking a book out of the library. +**Jamie:** Give me the version that sounds like an instructor, not a manual. -**Jamie:** And takeaway number five. The commit history is the unalterable guestbook of the project. It tells you exactly who changed what, and when they did it. +**Alex:** Keep the learner anchored in Step 4 - Check GitHub Feature Preview Settings. GitHub continuously rolls out improvements to its interface. This is the part to say slowly: Some enhancements start as opt-in Feature Previews before becoming the standard experience. -**Alex:** Perfect summary. In our next episode, we are going to put all of this theory into practice. We will be entering The Learning Room, where you will navigate these tabs yourself and make your very first open source contribution. +**Alex:** The practical takeaway is this. 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. -**Jamie:** I cannot wait for that one. Thank you all for listening, and we will see you in the next episode! +**Jamie:** Let's pause on How to Check and Enable Feature Previews. What should a learner take away from it? -
+**Alex:** The reason How to Check and Enable Feature Previews matters is that source: accessibility.github.com/documentation/guide/issues/ and accessibility.github.com/documentation/guide/pull-requests/. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places. +**Alex:** First, sign in to GitHub and go to any page. Then, click your profile picture (avatar) in the top-right corner. After that, in the dropdown menu, click Feature preview. Finally, a panel opens on the right side of the screen listing available features. The rhythm is simple: orient, act, verify, then continue. -### Episode 4: The Learning Room +**Jamie:** Before we leave How to Check and Enable Feature Previews, what is the practical point? -Your shared practice environment: challenges, PR workflow, bot feedback, peer review. +**Alex:** First, click on New Issues Experience to expand its details. Then, if an Enable button appears, click it. If you see Disable, the feature is already active - no action needed. After that, return to the feature list and repeat for New Files Changed Experience. Think of it as a rail line: each stop confirms you are still on the right route before the next one. -Based on: [Chapter 3: The Learning Room](docs/04-the-learning-room.md) +--- - +**Jamie:** Let's pause on NVDA or JAWS (Windows). What should a learner take away from it? -[Download Episode 4 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep04-the-learning-room.mp3) +**Alex:** Start with NVDA or JAWS (Windows): Screen reader users (VoiceOver on macOS). -
-Read Transcript - Episode 4: The Learning Room +**Alex:** The practical takeaway is this. An "Enable" button - press Enter to enable the feature. A "Disable" button - the feature is already enabled; no action needed. -#### Transcript +**Alex:** First, sign into GitHub and open any page. Then, switch to Browse Mode if not already active (NVDA+Space / JAWS virtual cursor). After that, press H or Shift+H to navigate to the "Navigation Menu" heading, or press D to navigate landmark regions to the navigation section. Finally, 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. 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 Gitt Going with GitHub. This is episode four, titled The Learning Room. I am Alex, and I am here to guide you through the wonderful, sometimes chaotic, but always rewarding world of open source collaboration. +**Jamie:** Before we leave NVDA or JAWS (Windows), what is the practical point? -**Jamie:** And I am Jamie. I am relatively new to GitHub, having learned it just about two years ago. I am here to ask all the questions that you might be thinking, and hopefully help us all avoid the mistakes I made when I was first starting out. +**Alex:** First, press Enter to activate it - a dropdown menu opens. Then, press ↓ or K to move through the menu items until you hear "Feature preview". After that, press Enter to select it - the Feature Preview panel opens. Finally, navigate through the list of features with ↓ or I (list item navigation). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. -**Alex:** We are so glad to have you here. In this episode, we are talking about the Learning Room. This is a very special part of the GitHub workshop experience. But before we dive into that, let us do a quick recap. In episode three, we talked about navigating repositories. +**Alex:** Before the learner moves on. Here is the plain-English version of 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. Put another way, it means both features have graduated to the standard GitHub interface and are active automatically for every user. -**Jamie:** Right, we talked about how a repository is essentially the master project folder. It holds all the files, the history of changes, and the branches. And we talked about how a branch is like a parallel universe where you can safely make changes without breaking the main project. +**Jamie:** If I am listening before the workshop starts, what should settle in my mind first? -**Alex:** Exactly. If you are feeling a little fuzzy on how to move through a repository using your screen reader, or how to explore a file tree, you might want to pause this and go back to episode three. But if you are ready to keep going, let us talk about the Learning Room. +**Alex:** This is where What Each Feature Enables becomes real: 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. That matters in practice: Enabling them before you begin ensures everything works as documented. +--- -**Alex:** During your first day of learning GitHub, you are actually working on two parallel tracks. Track one is your individual skills track. This happens on your personal GitHub account. You work through modules at your own pace, and a friendly automated bot named Mona guides you step by step. +**Jamie:** Let's pause on NVDA (Windows). What should a learner take away from it? -**Jamie:** I like Mona. Mona is very patient when I forget to commit my changes. +**Alex:** Keep the learner anchored in NVDA (Windows). Install NVDA if you haven't already. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor. -**Alex:** Mona is great. But track one is private. It is just you and the bot. Track two is the Learning Room contribution sprint. And this is completely different. The Learning Room is a single, shared GitHub repository where all the workshop participants collaborate together at the exact same time. +**Alex:** First, download from the NVDA download page. Then, run the installer - you can install to your computer or run portably. After that, after launch, NVDA speaks "NVDA started" when running. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. -**Jamie:** Wait, all of us? In one repository? At the same time? That sounds like a recipe for overriding each other's work. +**Jamie:** Let's pause on Configure NVDA for web browsing. What should a learner take away from it? -**Alex:** It sounds like it, but that is the magic of GitHub. Think of the Learning Room like a large community kitchen. Track one, with Mona, is like practicing chopping vegetables in your own private kitchen at home. You can take your time, and nobody is watching. But the Learning Room is the community kitchen. You are at one prep station, someone else is at the stove, someone else is baking bread. You can all hear and interact with each other, you are all contributing to the same massive meal, but because everyone has their own specific task and their own branch, you do not bump elbows. +**Alex:** Start with Configure NVDA for web browsing. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** Okay, I love that analogy. But why do we do it this way? Why not just keep practicing in our private kitchens? +**Alex:** First, open NVDA Menu (NVDA+N). Then, go to Preferences → Settings → Browse Mode. After that, enable "Use screen layout" - this helps with GitHub's landmark navigation. Finally, under Document Formatting, disable announcements you find too verbose. The rhythm is simple: orient, act, verify, then continue. -**Alex:** Because open source is a community kitchen. Real open source projects are shared spaces. By putting everyone in one repository, we create a realistic environment. You get to see other people's work, you learn from the person sitting next to you, and we can practice peer review. +**Alex:** This is the part worth saying out loud. Start with Recommended NVDA voice settings: Your NVDA key: By default it is Insert. The next useful detail is this: It can also be set to Caps Lock in NVDA preferences if that is more comfortable. -**Jamie:** That makes sense. It bridges the gap between learning the buttons to press, and actually working with other human beings. +**Alex:** The practical takeaway is this. Rate: 60-75% (fast enough to be efficient, slow enough to be clear). Punctuation: "Most" (reads important symbols like and @ without reading every period). -**Alex:** Exactly. Now, to understand how we collaborate in this space, we need to talk about the workflow. Specifically, the fork, edit, and pull request workflow. +--- -**Jamie:** Oh, good. I hear the word fork all the time. I know what a branch is, but what is a fork? Is it just another utensil in our community kitchen? +**Jamie:** Let's pause on JAWS (Windows). What should a learner take away from it? -**Alex:** Great question. Let us define it. A fork is a complete, personal copy of someone else's repository, placed into your own GitHub account. Let us say you find an amazing open source project, but you do not have permission to change their files directly. You would create a fork. That makes a copy in your account where you have full control. You make your edits there. +**Alex:** Here is the plain-English version of JAWS (Windows). If using a trial: JAWS runs in 40-minute sessions without a license. -**Jamie:** Okay, so I fork the project, I make my changes in my copy. But how does the original project get those changes? +**Jamie:** Let's pause on Configure JAWS for web browsing. What should a learner take away from it? -**Alex:** That is where the Pull Request comes in. And I love that name because you are literally requesting that the original project owners pull your changes from your fork into their project. In standard open source, this fork, edit, and pull request workflow is how almost everything gets done. +**Alex:** Start with Configure JAWS for web browsing. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** So in the Learning Room, are we all forking the repository? +**Alex:** First, open JAWS Settings Center: Insert+F2 → Settings Center. Then, ensure "Virtual cursor" is active for web browsing. After that, in Chrome or Firefox, JAWS should automatically activate Virtual/Browse mode. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Alex:** In the Learning Room, we actually simplify it just a bit to keep us all in one space. Instead of everyone making their own separate fork, we give everyone permission to create branches directly inside the shared Learning Room repository. You will still create a branch, make your edit, and open a Pull Request. It is the exact same workflow you use with a fork, just contained within one big shared house so we can all see each other's pull requests easily. +**Jamie:** Let's pause on Recommended JAWS settings for GitHub. What should a learner take away from it? +**Alex:** Keep the learner anchored in Recommended JAWS settings for GitHub. Your JAWS key: Insert (or Caps Lock if using laptop layout). -**Jamie:** Okay, so we are in this shared community kitchen. What are we actually cooking? What are the tasks? +**Alex:** The practical takeaway is this. Verbosity → Links: Read link text only (disable "opens in new window" if too verbose). Verbosity → Punctuation: "Most" for same reason as NVDA. -**Alex:** We call them challenges. Inside the Learning Room repository, there is a folder called docs. Inside that folder, there is a file called CHALLENGES dot M D. M D stands for Markdown. This file is your menu. It lists twelve different challenges organized by skill level, from beginner to expert. +--- -**Jamie:** How do I find my challenge and know what to do? +**Alex:** Keep the teaching thread moving. The reason VoiceOver (macOS) matters is that activate VoiceOver: Command+F5 toggles VoiceOver on and off. -**Alex:** You will navigate to that challenges file and read through the options. Each challenge tells you exactly which file you need to edit, what skills you will practice, and what the success criteria are. And here is the fun part. The practice files you will be editing have intentional mistakes built into them. +**Jamie:** Let's pause on Essential VoiceOver setup for web. What should a learner take away from it? -**Jamie:** Intentional mistakes? Like a scavenger hunt? +**Alex:** Start with Essential VoiceOver setup for web: Your VoiceOver modifier key: VO = Control+Option by default. -**Alex:** Exactly like a scavenger hunt. Let me give you an example. There is a file called welcome dot M D. It is supposed to be an introduction to open source for newcomers. But it has three sections marked with the word TODO in capital letters, where the content is just missing. +**Alex:** First, open VoiceOver Utility: VO+F8. Then, go to Web category → Web Rotor. After that, ensure these are checked: Headings, Landmarks, Links, Buttons, Form Controls, Tables. Finally, recommended browser: Safari (best VoiceOver integration on macOS). Think of it as a rail line: each stop confirms you are still on the right route before the next one. -**Jamie:** Oh, I have seen those in real projects. Someone writes a document, gets tired, types TODO, and leaves it for someone else. +**Jamie:** Before we leave Essential VoiceOver setup for web, what is the practical point? -**Alex:** Precisely. One of the beginner challenges is to find those TODO markers, delete them, and write the missing paragraphs. Another file is called keyboard dash shortcuts dot M D. This is a reference guide for screen reader shortcuts. It has tables for N V D A, JAWS, and VoiceOver. But we purposely put incorrect shortcuts in those tables. +**Alex:** First, firefox on macOS also has good VoiceOver support. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. -**Jamie:** Oh, that is devious. I love it. So we have to find the wrong shortcut and fix it? +**Alex:** Keep the teaching thread moving. Start with Turn on Quick Nav for fast navigation. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Yes, and you have to do it without breaking the structure of the Markdown table. It is fantastic practice. There is also a setup guide file with broken links that point to nowhere. Your job might be to track down the broken links and update them to the correct web address. +**Alex:** The practical takeaway is this. 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). -**Jamie:** Okay, that sounds like a lot of fun, actually. But how do I know when I am done? Do I just save the file and yell across the room that I finished? +--- -**Alex:** Not quite. You know you are done when your Pull Request is merged into the main project. Merging means your changes are officially accepted and combined with the original file. When that happens, an automated bot will actually post a celebration comment on your pull request and award you a digital badge. +**Jamie:** Let's pause on A note for Mac users about keyboard shortcuts. What should a learner take away from it? +**Alex:** This is where A note for Mac users about keyboard shortcuts becomes real: throughout this documentation, Windows keyboard shortcuts for VS Code are frequently referenced. That matters in practice: In general, these keyboard shortcuts work on the Mac, however, Mac users should substitute Command whenever Ctrl is referenced. -**Jamie:** Alright, let us talk about opening that Pull Request. I remember the first time I had to open a Pull Request. I was terrified. I felt like I was standing on a stage and everyone was about to judge my code. +**Alex:** Keep the teaching thread moving. Keep the learner anchored in Browser Recommendations Summary. 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. -**Alex:** That is a very common feeling. It can feel incredibly intimidating. You are putting your work out there for public review. +**Jamie:** What stays the same when the tool changes? -**Jamie:** It really is intimidating! OK, that sounds like a lot of steps. Creating branches, making edits, opening this request for everyone to see. +**Alex:** Start with Learning Cards: Set Up Your Screen Reader and Browser. There is something to understand, something to try, and something that proves the try worked. -**Alex:** It does! But here is the thing. You have already done most of this on Day 1 in your private track. It is the exact same workflow. And remember, the Learning Room is a safe environment. Every single person in that repository is learning, just like you. And we have built safety nets into the process. +**Alex:** The practical takeaway is this. 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. 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. -**Jamie:** Safety nets? Like what? +--- -**Alex:** The first safety net is our automated bot. We call it the Learning Room PR Bot. The moment you open your Pull Request, within about thirty seconds, this bot springs into action. +**Alex:** Keep the teaching thread moving. Start with 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need. -**Jamie:** What does the bot do? Does it grade my work? +**Jamie:** Let's pause on Install Git First. What should a learner take away from it? -**Alex:** I prefer to think of it as a friendly automated building inspector who walks through the house before the open house begins. The bot checks to make sure you edited the correct file. It checks your Markdown formatting to ensure you used headings correctly. If you added an image, it checks to make sure you included alternative text for screen readers. It even checks to ensure you did not leave any broken links behind. +**Alex:** Here is the plain-English version of Install Git First. It detects whether Git is already on your system. Put another way, if Git is missing, the Source Control panel will display a warning, and all git commands in the terminal will fail. -**Jamie:** Wow, that is really thorough. What happens if I messed something up? Does it reject my Pull Request? +**Jamie:** Let's pause on Windows. What should a learner take away from it? -**Alex:** Never. The bot never fails your Pull Request or closes it. Instead, it posts a very detailed, educational comment on your Pull Request. It tells you exactly what it found, explains why it matters for accessibility or formatting, and gives you links to documentation so you can learn how to fix it. +**Alex:** Start with Windows. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** Oh, I wish I had known that when I started. An automated proofreader that explains things nicely instead of just yelling error messages at me. +**Alex:** First, download the Git for Windows installer from Git for Windows download page. Then, run the installer - default options are correct for most users. After that, on the "Adjusting your PATH environment" screen, keep the default: "Git from the command line and also from 3rd-party software". Finally, complete the installer and restart any open terminals. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Alex:** Exactly. It gives you instant feedback. And you can push a new commit to your branch to fix the issues, and the bot will run again and update its report. It is a completely low-stakes way to practice getting technical feedback. +--- +**Jamie:** Let's pause on Verify installation (Windows). What should a learner take away from it? -**Alex:** But the bot is only the first step. The second step is human peer review. And this is where the real magic of the Learning Room happens. +**Alex:** Start with Verify installation (Windows). There is something to understand, something to try, and something that proves the try worked. -**Jamie:** Peer review. So, reading and commenting on classmate work. How does that work? Do I just pick someone at random? +**Alex:** First, open PowerShell or Command Prompt. Then, type git --version and press Enter. After that, you should see a version number such as git version 2.47.0.windows.2 - any version is fine. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. -**Alex:** We have another automation called the pairing bot. When you open your Pull Request, the pairing bot looks at the roster of students and automatically assigns one of your classmates to be your reviewer. It tries to balance the workload so nobody gets overwhelmed. +**Jamie:** Let's pause on macOS. What should a learner take away from it? -**Jamie:** So someone else in the workshop gets a notification saying, Jamie needs you to review their work? +**Alex:** The reason macOS matters is that Git is often already present via Xcode Command Line Tools. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places. -**Alex:** Yes. And the bot even posts a comment giving the reviewer instructions on what to look for. It might say, please check that Jamie completed all three TODO sections, and that the new paragraphs read well. +**Alex:** First, open Terminal (Cmd+Space → type "Terminal"). Then, type git --version and press Enter. After that, 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. Finally, alternatively, install directly from Git for macOS download page or via Homebrew: brew install git. The rhythm is simple: orient, act, verify, then continue. -**Jamie:** Okay, so let us walk through this from the perspective of the reviewer. Let us say I get that notification. I have been assigned to review your Pull Request, Alex. How do I navigate that with my screen reader? Where do I go? +**Jamie:** Let's pause on Screen reader note (Windows terminal verification). What should a learner take away from it? -**Alex:** This is a great practical question. First, you will navigate to the Learning Room repository in your browser. From the main repository page, you need to navigate to the Pull Requests tab. +**Alex:** Start with Screen reader note (Windows terminal verification): Once Git is installed, you will configure your Git identity in Step 7 after VS Code is set up. -**Jamie:** How do I find that tab efficiently? +**Alex:** The practical takeaway is this. 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. -**Alex:** If you are using N V D A or JAWS on Windows, you can use GitHub's built-in keyboard shortcuts. Press the letter G, followed by the letter P. That stands for Go to Pull requests. +--- -**Jamie:** Oh, that is clever! G then P. Does that work for VoiceOver on Mac too? +**Alex:** Keep the teaching thread moving. Here is the plain-English version of Install Visual Studio Code. Visual Studio Code (VS Code) is the development environment used throughout this workshop. Put another way, it is free, open source, and has excellent built-in accessibility support. -**Alex:** Yes, those are GitHub specific shortcuts, so they work across platforms as long as your screen reader is passing the keystrokes through. Once you are on the Pull Requests page, you will be in a list of all open pull requests. If it is a busy workshop, there might be thirty pull requests in that list. +**Jamie:** Let's pause on Download and install. What should a learner take away from it? -**Jamie:** That sounds overwhelming. How do I find the one I am supposed to review? +**Alex:** Start with Download and install. There is something to understand, something to try, and something that proves the try worked. -**Alex:** You use the filter. Navigate to the filter text box. By default, it says something like, is open is PR. You can clear that and type a specific filter query. You will type, review dash requested, then a colon, then the at symbol, and the word me. So, review requested colon at me. Press Enter. +**Alex:** First, navigate to code.visualstudio.com. Then, select the download link for your operating system. After that, run the installer with default options. Finally, launch VS Code when the installer finishes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Jamie:** And that filters the list to only show the ones where I am the assigned reviewer? +**Jamie:** Let's pause on Enable Screen Reader Mode in VS Code. What should a learner take away from it? -**Alex:** Exactly. Now you can use your screen reader's heading navigation. Press the letter H to jump from one pull request title to the next. When you hear the title of the one you want, press Enter to open it. +**Alex:** Keep the learner anchored in Enable Screen Reader Mode in VS Code. Do this before anything else in VS Code. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor. -**Jamie:** Okay, I am on the Pull Request page. What am I looking at? Or rather, what am I listening to? +**Alex:** First, listen for the dialog - it will say something like "A screen reader is detected. Would you like to enable Screen Reader Optimized mode?". Then, press Enter to accept, or Tab to the Enable button and press Space. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. -**Alex:** A Pull Request page has a few different tabs, but the two most important ones are the Conversation tab, and the Files Changed tab. You land on the Conversation tab by default. +--- -**Jamie:** The Conversation tab. Is that where the bot leaves its report and where people leave comments? +**Jamie:** Let's pause on Option A - Keyboard shortcut. What should a learner take away from it? -**Alex:** Yes. You can use heading navigation here as well. Every comment is a heading. You will find the original description of the Pull Request, the automated bot's report, and any discussion that has happened so far. You will also find a section called Reviewers, usually marked as a heading level three, which confirms that you are assigned. +**Alex:** Start with Option A - Keyboard shortcut. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** So I read the conversation to get context. But how do I actually see the changes you made to the code or the text? +**Alex:** First, press Shift+Alt+F1. Then, VS Code toggles Screen Reader Optimized mode immediately. The rhythm is simple: orient, act, verify, then continue. -**Alex:** For that, you navigate to the Files Changed tab. Once you activate that tab, you are looking at the diff. +**Jamie:** Let's pause on Option B - Command Palette. What should a learner take away from it? -**Jamie:** The diff. Let us define that. A diff is short for difference. It is a special view that shows exactly what was added and what was removed from a file. +**Alex:** Start with Option B - Command Palette. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Right. Navigating a diff with a screen reader takes a little practice. GitHub presents the diff as a table or a structured list of lines. As you arrow down through the content, your screen reader will announce the state of each line. +**Alex:** The practical takeaway is this. Your screen reader will announce "Type to filter" or the palette input field. -**Jamie:** What does that sound like? +**Alex:** First, press Ctrl+Shift+P to open the Command Palette. Then, arrow down to "Accessibility: Toggle Screen Reader Accessibility Mode". 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. -**Alex:** If a line was added, your screen reader will usually say plus, or inserted, before reading the text. If a line was removed, it will say minus, or deleted. Unchanged lines, which are just there to give you context, are read normally without a prefix. +**Jamie:** Let's pause on How to confirm it is on. What should a learner take away from it? -**Jamie:** So if you were fixing a typo in the word GitHub, I would hear a minus line with the misspelled word, immediately followed by a plus line with the correctly spelled word? +**Alex:** Start with How to confirm it is on. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Exactly. You can read through the entire file this way, line by line, to see exactly what the author changed. +**Alex:** First, press Ctrl+Shift+P to open the Command Palette again. Then, if the status bar at the bottom of the window is accessible to you, it will read "Screen Reader Optimized". After that, alternatively: go to File → Preferences → Settings (Ctrl+,), type screenReaderOptimized in the search box, and verify the checkbox is ticked. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. -**Jamie:** Okay, so I have read your changes. I think they look great, but I want to suggest one small addition. How do I leave my review? +--- -**Alex:** On the Conversation tab, there is a large text area for adding a comment. If you are using N V D A, you might press N V D A plus Space to enter Focus Mode, or Forms Mode for JAWS, so you can type freely. If you are using VoiceOver on a Mac, you would navigate to the text area and press V O plus Shift plus Down Arrow to interact with it. +**Alex:** Keep the teaching thread moving. This is where What Screen Reader Mode changes becomes real: once Screen Reader Mode is on, you navigate the editor with Up and Down Arrow to move line by line. That matters in practice: Press Enter to open a folded section. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed. -**Jamie:** I type my feedback. Do I just say, looks good? +**Alex:** The practical takeaway is this. 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. -**Alex:** You could, but helpful peer review is specific. You might say, I love the paragraph you added about assistive technology. One suggestion, maybe we could add a link to the official documentation here. +**Jamie:** Let's pause on Learning Cards: Install Git and Visual Studio Code. What should a learner take away from it? -**Jamie:** That is a great way to phrase it. It is encouraging but offers a clear improvement. So I type that out. Then what? +**Alex:** Start with Learning Cards: Install Git and Visual Studio Code. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Then you navigate to the button called Review Changes. When you activate it, you get to choose the type of review. You can choose Comment, which is just leaving feedback without passing judgment. You can choose Approve, which means you think it is perfect and ready to be merged. Or you can choose Request Changes, which means there is something specific that must be fixed before it can be merged. +**Alex:** The practical takeaway is this. 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. 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. -**Jamie:** So if you missed one of the TODO markers, I would choose Request Changes and politely let you know. +**Alex:** Keep the teaching thread moving. The reason Step 7 - Configure Git Identity matters is that now that Git is installed, tell it who you are. That gives the learner a simple foothold: Git embeds your name and email in every commit you make, and this affects how your contributions appear in project history. -**Alex:** Exactly. Once you select your option, you navigate to the Submit Review button and press Enter. The author gets a notification, and they can push a new commit to address your feedback. +--- +**Jamie:** Let's pause on Configure in VS Code. What should a learner take away from it? -**Jamie:** I really like this process. But I have to ask, what if I am assigned to review someone's work, and I do not know if their code is right? I am a beginner too. I might approve something that is actually broken. +**Alex:** Start with Configure in VS Code. There is something to understand, something to try, and something that proves the try worked. -**Alex:** That is the beauty of the Learning Room. It is completely low stakes. Remember the flight simulator analogy? +**Alex:** The practical takeaway is this. Menu: Terminal → New Terminal. Keyboard: Ctrl+ (Windows) or Cmd+ `` (Mac). -**Jamie:** A flight simulator. Where you can crash the plane without actually hurting anyone. +**Alex:** First, open Visual Studio Code. Then, open the integrated terminal. After that, type the following commands, replacing with your information. Think of it as a rail line: each stop confirms you are still on the right route before the next one. -**Alex:** Exactly. We want you to make mistakes here. If you approve a Pull Request that has a formatting error, the automated bot will probably catch it anyway. And even if the bot misses it, and it gets merged into the repository, that is fine! It just becomes a new challenge for the next student to fix. +**Alex:** Treat examples as spoken recipes, not decorations. You may hear something like git config --global user.name "Your Name"; git config --global user.email "your-email@example.com". Read the command, understand what it changes, then run it only when the repository state matches the lesson. -**Jamie:** Oh, I never thought of it that way. A mistake just creates more open source work for the community. +**Alex:** Keep the teaching thread moving. Here is the plain-English version of What to use. The terminal in VS Code is accessible with all major screen readers. Put another way, press Ctrl+ to move focus to the terminal, type your commands, and press Enter`. It 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:** Right. The goal here is not perfect code. The goal is building confidence. When you practice this fork, edit, and pull request workflow in a safe environment, you are building muscle memory. +**Alex:** The practical takeaway is this. 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). -**Jamie:** So when I go to contribute to a huge project like N V D A or React, my hands will already know the keyboard shortcuts. I will already know how to filter for my reviews. +**Jamie:** Let's pause on Why This Matters. What should a learner take away from it? -**Alex:** Precisely. Because the steps you take in the Learning Room are the exact same steps you take on the biggest open source projects in the world. And I want to emphasize this. When you merge a Pull Request in the Learning Room, it is a real contribution. +**Alex:** This is where Why This Matters becomes real: if Git isn't configured, it will either. -**Jamie:** It is not a simulation? +**Alex:** The practical takeaway is this. Use a default name like "Unknown" (looks unprofessional in project history). Refuse to create commits with an error message. -**Alex:** The environment is designed for learning, but the technology is real. You found an issue, you made a meaningful change, you received technical feedback from a bot, you received human feedback from a peer, you incorporated their suggestions, and you merged your work. That is open source contribution in its purest form. You will have a merged commit in your GitHub history to prove it. +--- -**Jamie:** That is incredibly motivating. It takes the fear out of the process and replaces it with a sense of community. +**Jamie:** What should happen before anyone copies and runs it? +**Alex:** Keep the learner anchored in Verify Your Configuration. Run this command to see your current settings. -**Alex:** Let us wrap up with a few key takeaways from our discussion today. First, the Learning Room is a shared repository where everyone collaborates together. It is designed to simulate the bustling, collaborative nature of a real open source project. +**Alex:** Treat examples as spoken recipes, not decorations. You may hear something like git config --global --list. Read the command, understand what it changes, then run it only when the repository state matches the lesson. -**Jamie:** Second, the practice challenges are real files with intentional mistakes. You find your challenge in the docs folder, make your fixes on a branch, and open a Pull Request. +**Jamie:** Let's pause on Using the Correct Email. What should a learner take away from it? -**Alex:** Third, you are supported by two types of feedback. The automated bot gives you instant, low-stakes technical feedback on accessibility and formatting. And your peers give you human feedback on your content. +**Alex:** The reason Using the Correct Email matters is that use the same email you registered with GitHub. That gives the learner a simple foothold: 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. -**Jamie:** And finally, leaving a peer review is just as important as writing the code. You use the filter review requested colon at me to find your assignments, read the diff to see what changed, and leave constructive, encouraging comments. +**Alex:** Keep the teaching thread moving. Start with Step 8 - Install VS Code Extensions: This workshop uses two VS Code extensions. The next useful detail is this: GitHub Copilot is built into VS Code automatically. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need. -**Alex:** Beautifully summarized. In our next episode, we are going to dive deeper into how projects organize all of this work. We will be talking about Working with Issues. Issues are how we track bugs, plan features, and figure out what to work on next. +--- -**Jamie:** I cannot wait. Tracking tasks is my favorite kind of organizing. +**Jamie:** Let's pause on GitHub Copilot (Built In). What should a learner take away from it? -**Alex:** Thank you all for listening to Gitt Going with GitHub. Take a deep breath, go open that first Pull Request in the Learning Room, and we will see you in the next episode. +**Alex:** Here is the plain-English version of GitHub Copilot (Built In). GitHub Copilot is automatically included with Visual Studio Code. Put another way, there is no extension to install separately. -
+**Jamie:** Let's pause on Activate Copilot. What should a learner take away from it? +**Alex:** This is where Activate Copilot becomes real: you do not need to use the Command Palette to sign in. That matters in practice: If you are logged into GitHub in your browser, VS Code handles authentication automatically when you first interact with the agent. -### Episode 5: Working with Issues +**Alex:** The practical takeaway is this. Your screen reader should announce the chat input field. -Filing, searching, filtering, commenting on, and managing GitHub issues. +**Alex:** First, make sure Screen Reader Mode is enabled (see above). Then, make sure you are signed into GitHub in your web browser. After that, press Ctrl+Shift+I to open Agent mode. Finally, VS Code will automatically sign you into GitHub Copilot using your browser session - no manual sign-in command is needed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -Based on: [Chapter 4: Working with Issues](docs/05-working-with-issues.md) +**Jamie:** Before we leave Activate Copilot, what is the practical point? - +**Alex:** First, a response will appear in the chat history above the input field. Then, navigate up with Shift+Tab or Up Arrow to read the response. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. -[Download Episode 5 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep05-working-with-issues.mp3) +**Jamie:** Let's pause on Extension 2 - GitHub Pull Requests. What should a learner take away from it? -
-Read Transcript - Episode 5: Working with Issues +**Alex:** Keep the learner anchored in Extension 2 - GitHub Pull Requests. This extension lets you review and manage pull requests without leaving VS Code. This is the part to say slowly: It is used in the code review chapters. -#### Transcript +--- -**Alex:** Welcome to Gitt Going with GitHub. This is episode 5, Working with Issues. I am Alex, and I am here to guide you through the accessibility and workflow concepts that will help you thrive in open source. +**Jamie:** Let's pause on Install. What should a learner take away from it? -**Jamie:** And I am Jamie. I am a blind developer who started learning GitHub about two years ago, and I am here to ask all the questions that you are probably thinking right now. +**Alex:** The reason Install matters is that extension imposter warning: The VS Code Marketplace contains third-party extensions with similar names. That gives the learner a simple foothold: always verify the publisher before installing. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places. -**Alex:** It is great to have you here, Jamie. In episode 3, we covered repository navigation and how to move between the different tabs of a project. Today, we are diving deep into one of those specific tabs, the Issues tab. We will cover what issues are, how to read them, how to file them, and how to manage them. +**Alex:** The practical takeaway is this. This extension was formerly named "GitHub Pull Requests and Issues" - either name is correct. -**Jamie:** I remember when I first heard the word issue in the context of programming. In everyday life, having an issue sounds like a bad thing. Like a problem. I thought it meant I broke something. +**Alex:** First, press Ctrl+Shift+X to open the Extensions panel. Then, press Tab to move into the results list. After that, arrow down to find "GitHub Pull Requests" with publisher "GitHub". Finally, press Enter to open the details page. The rhythm is simple: orient, act, verify, then continue. -**Alex:** That is such a common reaction! But in GitHub, an issue is not necessarily a bad thing at all. Think of an issue simply as a unit of work. It is a dedicated discussion thread attached to a repository. Yes, it can be a bug report, but it can also be a feature request, a question, a task, or an accessibility report. +**Jamie:** Before we leave Install, what is the practical point? -**Jamie:** So it is basically a digital manila folder for a specific topic. +**Alex:** First, press Tab to the Install button and press Enter or Space. Then, VS Code will announce when installation is complete. Think of it as a rail line: each stop confirms you are still on the right route before the next one. -**Alex:** Exactly. That is a perfect analogy. If you want to add a new button to your application, you open a manila folder, write Add New Button on the tab, and put all your notes, questions, and checklists inside that folder. On GitHub, that folder is an issue. It keeps the conversation focused and gives everyone a place to collaborate before any code is actually written. +**Jamie:** Let's pause on Verify it is working. What should a learner take away from it? +**Alex:** Start with Verify it is working: The Pull Requests panel is a tree view. The next useful detail is this: Navigate it with Up and Down Arrow. -**Jamie:** Okay, so how do I actually find these manila folders? Say I am on a repository page right now. +**Alex:** The practical takeaway is this. If you are already signed in from the earlier step, this command may not appear - that means you are already authenticated. The Pull Requests panel should open in the sidebar. If your repository has open pull requests, they will appear here. -**Alex:** If you are using a screen reader, you can navigate by landmarks to the Repository navigation region, then press your Tab key until you reach the Issues tab. Your screen reader will usually announce the word Issues followed by the number of open issues, like, Issues, 14 open. Then you just press Enter. +**Alex:** First, press Ctrl+Shift+P and type: GitHub Pull Requests: Sign in. Then, to confirm the extension loaded: press Ctrl+Shift+P, type GitHub Pull Requests: Focus on Pull Requests View. Think of it as a rail line: each stop confirms you are still on the right route before the next one. -**Jamie:** Is there a faster way? You know I love keyboard shortcuts. +**Alex:** Keep the teaching thread moving. Here is the plain-English version of Copilot Free tier. Copilot Free is available to all GitHub users at no cost. Put another way, for this workshop, Free tier is sufficient. -**Alex:** There is! If you are in Focus Mode, you can press the letter G, release it, and then press the letter I. G stands for Go, and I stands for Issues. That will jump you straight to the Issues tab from anywhere in the repository. +**Alex:** The practical takeaway is this. Limited inline code completions per month. Limited Copilot Chat messages per month. -**Jamie:** Oh, that is clever. Go to Issues. G then I. I will definitely use that. So once I am on the Issues page, what does the structure look like? +--- -**Alex:** The page is built around a search and filter bar at the top, followed by some buttons to switch between Open and Closed issues, and then the main event, which is the issues list itself. +**Jamie:** There are a lot of tools in play. How do we keep that from feeling like a contest? -**Jamie:** How should I navigate that list with my screen reader? +**Alex:** Start with Learning Cards: Install VS Code Extensions. There is something to understand, something to try, and something that proves the try worked. -**Alex:** The best way is to use your heading navigation. Every issue title in the list is a heading level 3 link. So if you press the number 3 on your keyboard, you will jump from issue to issue. Your screen reader will announce the title, the issue number, any labels attached to it, who opened it, and how many comments it has. +**Alex:** The practical takeaway is this. 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. 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. -**Jamie:** That sounds like a lot of information. Does it read it all at once? +**Jamie:** How do you keep commands from becoming magic words? -**Alex:** It usually reads it as a single block of text when you land on the heading. If you want to explore a specific issue in more detail before opening it, you can use your down arrow to read the individual elements like the author and the timestamp. +**Alex:** Keep the learner anchored in 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). This is the part to say slowly: 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. 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 --version; git config user.name; git config user.email; gh auth status if GitHub CLI is installed. 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; [ ]. Read the command, understand what it changes, then run it only when the repository state matches the lesson. -**Jamie:** Let us talk about that search and filter bar you mentioned. If a project has hundreds of open issues, pressing the number 3 to read all of them is going to take all day. +**Jamie:** If setup starts to feel like a barrier, how should a learner think about it? -**Alex:** You are absolutely right. That is where filtering comes in. It is like having an assistant who can instantly pull only the manila folders you care about from a massive filing cabinet. To reach the search bar, you can navigate to it using your form field shortcut, which is usually the letter E or F depending on your screen reader. +**Alex:** The reason What Happens at the Start of Day 1 matters is that 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. That gives the learner a simple foothold: when the workshop opens, the facilitator will paste a GitHub Classroom assignment link in the chat. -**Jamie:** And when I get there, I need to switch to Focus Mode to type, right? +--- -**Alex:** Yes, exactly. Switch to Focus Mode, which is Insert plus Space for NVDA, or Insert plus Z for JAWS. Once you are in the text field, you can type qualifiers to filter the list. For example, if you want to find bugs, you type the word is, followed by a colon, followed by the word open, then a space, then the word label, a colon, and the word bug. +**Alex:** Keep the teaching thread moving. Start with Other GitHub Access Methods (Reference Only): This workshop focuses entirely on GitHub.com in the browser and VS Code. The next useful detail is this: However, you should be aware that other ways to work with GitHub exist. -**Jamie:** So, is colon open space label colon bug. +**Jamie:** What should someone listen for when a lesson offers more than one tool path? -**Alex:** Correct. When you press Enter, the page updates instantly to show only open issues that have the bug label. +**Alex:** Here is the plain-English version of GitHub Desktop. A graphical desktop application for managing repositories, branches, and commits without using the command line. -**Jamie:** What if I want to find issues that are assigned to me? +**Alex:** The practical takeaway is this. 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. -**Alex:** You would type assignee colon at me. The at symbol followed by the word me is a special shortcut in GitHub that always refers to your own username. You can also type author colon at me to find issues you originally filed. +**Jamie:** What is the safe way to learn from that example? -**Jamie:** That is really powerful. Are there other ways to filter besides typing these queries out? Sometimes I forget the exact syntax. +**Alex:** This is where GitHub CLI (gh) becomes real: a command-line tool that lets you perform nearly any GitHub action directly from your terminal. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed. -**Alex:** Absolutely. Right near the search bar, there is an actions toolbar with dropdown buttons for Labels, Milestones, and Assignees. You can Tab to the Label button, press Enter to open the dropdown, use your up and down arrows to find the label you want, and press Enter to select it. When you press Escape to close the dropdown, the list filters automatically. +**Alex:** The practical takeaway is this. 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. -**Jamie:** You mentioned milestones. What is a milestone? +**Alex:** Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson. -**Alex:** A milestone is just a way to group issues together by a target date or a specific release. For example, a project might have a milestone called Version 2 point 0. Filtering by that milestone shows you all the issues that need to be finished before Version 2 point 0 can launch. +--- +**Jamie:** What should they understand before typing anything? -**Jamie:** Okay, so I have filtered the list, I found an issue that sounds interesting, and I pressed Enter on the heading to open it. What does the actual issue page look like? +**Alex:** Keep the learner anchored in GitHub Copilot CLI (gh copilot). An extension to the GitHub CLI that brings Copilot assistance to the terminal. This is the part to say slowly: You can ask it to explain or suggest shell commands in plain English. -**Alex:** The page has a very specific anatomy. At the very top, you have the issue title as a heading level 1. Right below that, your screen reader will announce a status badge, telling you if the issue is Open or Closed. +**Alex:** The practical takeaway is this. Install: gh extension install github/gh-copilot. Documentation: docs.github.com/en/copilot/github-copilot-in-the-cli. Particularly useful for users who prefer a terminal workflow. -**Jamie:** And then comes the description? +**Alex:** Treat examples as spoken recipes, not decorations. You may hear something like Reference examples only; gh copilot suggest "how do I undo my last commit"; gh copilot explain "git rebase -i HEAD 3". Read the command, understand what it changes, then run it only when the repository state matches the lesson. -**Alex:** Yes. The original post, which we call the issue body or description, comes next. But before you read it, it helps to know about the sidebar. On the right side of the screen visually, there is a sidebar containing metadata. It has sections for Labels, Assignees, and the Milestone. These are marked as heading level 3s. +**Alex:** Keep the teaching thread moving. The reason Git (the version control system itself) matters is that GitHub is a platform built on top of Git, which is the underlying version control system. That gives the learner a simple foothold: Git runs locally on your computer via a terminal. -**Jamie:** So if I want to quickly check who is assigned to an issue, I can just press the number 3 until I hear Assignees? +**Alex:** The practical takeaway is this. Git Handbook. Pro Git book (free). GitHub Skills: Introduction to GitHub. -**Alex:** Exactly. It is a great way to orient yourself. But for reading the main description, you want to stay in Browse Mode. The description is usually formatted using Markdown, which means GitHub turns it into proper HTML. Headings are real headings, bullet points are real lists, and code blocks will actually announce as code. +**Jamie:** Let's pause on Getting Help Before the Event. What should a learner take away from it? -**Jamie:** I love that. There is nothing worse than reading a wall of unformatted text. So I can just use my normal screen reader commands to read the description line by line. +**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:** Yes. And below the description is the timeline. This is the activity stream of the issue. Every comment left by another person is a heading level 3. So to read a conversation, you just press the number 3 to jump from comment to comment. +**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. -**Jamie:** Does the timeline only show comments? +--- -**Alex:** Good question. No, it shows events too. If someone adds a label, or assigns someone, or references a pull request, those events appear in the timeline chronologically between the comments. They usually read as simple text paragraphs, like, Jamie added the bug label 2 days ago. +**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:** Let us flip the script. Instead of reading an issue, I want to file a new one. I found a bug where my screen reader is not announcing a button state, and I want to report it. +**Jamie:** That is a better way to say it than just follow the steps. -**Alex:** That is a perfect use case. From the issues list page, you will want to navigate to the New Issue button. You can use the letter K to move through links until you find it, or use your buttons shortcut. Press Enter to activate it. +**Alex:** Right. Steps matter, but understanding wins. That is episode 1. Next in the series is episode 2, where we keep building the same contributor muscles. -**Jamie:** Does it just give me a blank text box? +
-**Alex:** Sometimes. But many open source projects use Issue Templates. If they do, you will land on a page asking you to pick a template. You might hear options like Bug Report, Feature Request, or Accessibility Issue. You just find the one you want and press Enter on its Get Started button. +--- -**Jamie:** Okay, I picked the Bug Report template. Now I am on a form with a title and a body. I remember when I filed my first issue, I just made the title, Screen reader bug. Was that a bad title? +### 4. Episode 44: Choose Your Tools -**Alex:** It is not terrible, but it is not very helpful to the maintainers. Think of the title like a news headline. It needs to be specific. A much better title would be, Screen reader does not announce expanded state on the main navigation menu. +A guided tour of browser GitHub, github.dev, VS Code, GitHub Desktop, and the CLI. -**Jamie:** That makes sense. It tells them exactly what is wrong and where. So I type that into the title field using Focus Mode. Then I Tab to the description field. +Based on: [Chapter 1: Choose Your Tools](docs/01-choose-your-tools.md) -**Alex:** Right. And this is where you write the body of your issue. If you selected a template, the text area might already have some headings in it, like What Happened, What I Expected, and Steps to Reproduce. You just fill in the details under each heading. +Audio and transcript are being regenerated for this episode. -**Jamie:** Can I use formatting here? Like making the steps an actual numbered list? +
+Read Transcript - Episode 44: Choose Your Tools -**Alex:** Absolutely. The text area supports Markdown. Because you are in Focus Mode while typing, you can use keyboard shortcuts. Control plus B makes text bold. Control plus E formats text as a code block. And Control plus Shift plus the number 7 creates a numbered list. +#### Transcript -**Jamie:** Oh, I did not know about Control plus Shift plus 7. That is way faster than typing out the numbers manually. What about task lists? I have seen issues that have actual checkboxes in them. +**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. -**Alex:** Task lists are incredibly useful! You can create them by typing a hyphen, a space, a left bracket, a space, a right bracket, and another space. It looks a bit like a little text drawing of an empty box. When you submit the issue, GitHub renders that as a real, interactive checkbox. +**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:** That sounds like a lot of steps. Hyphen, space, bracket, space, bracket. +--- -**Alex:** It does! But here is the thing, you have already done most of this on Day 1 of your programming journey. It is just typing characters. And if you use VS Code to write your issue drafts, you can use extensions that handle the heavy lifting for you. +**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:** That is a relief. So I have written my steps to reproduce. Is there anything specific I should include because it is an accessibility bug? +**Jamie:** So the episode should work even if someone has not read the chapter yet. -**Alex:** Yes, always include your environment details. Tell them exactly which screen reader and version you are using, like NVDA 2025 point 3. Tell them your browser and your operating system. A bug might happen on Firefox but not on Chrome, so that context is crucial for the maintainer trying to fix it. +**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, the issue is filed. What happens when someone replies? How do I comment back? +**Jamie:** Okay, set the room for us. What are we walking into? -**Alex:** When you open the issue, you can jump straight to the comment box by navigating to the landmark called Add a comment. Or, if you prefer shortcuts, you can just press the letter R while reading a previous comment to reply and automatically quote their text. +**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. -**Jamie:** I love the R shortcut. Once I am in the text area, it is just like writing the issue body, right? Focus mode, type my reply, use markdown if I want to. +**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. -**Alex:** Exactly. And when you are ready to post it, you do not even need to Tab to the submit button. You can just press Control plus Enter from right inside the text area to submit your comment. +**Jamie:** What stays the same when the tool changes? -**Jamie:** What if someone leaves a comment that just says, I will look into this today. I want to acknowledge it, but leaving a comment that just says Thanks feels like it might clutter the timeline. +**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:** That is a brilliant observation. Open source maintainers get a lot of notifications, so adding a comment just to say thanks or I agree can sometimes be overwhelming. Instead, you should use Reactions. +--- -**Jamie:** Reactions? Like emojis? +**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:** Yes. Reactions are a form of lightweight feedback. Every comment has a button to add a reaction. You can add a thumbs up, a heart, a smile, or even a rocket ship. It communicates your acknowledgement without sending an email notification or cluttering the thread. +**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:** Analogy time! It is like nodding your head in a meeting. You are showing you understand and agree, without actually interrupting the speaker to say the word yes. +**Jamie:** What would you say to someone who is already bracing for this to be too much? -**Alex:** That is perfectly stated. Nodding in a meeting. Use reactions to nod. +**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. -**Jamie:** Let us talk about connecting things together. I have noticed people typing the number sign, or the hash symbol, followed by a number in their comments. What does that do? +**Alex:** The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work. -**Alex:** That is how you cross-reference issues. Every issue and pull request has a unique number. If you are typing a comment and you type the number sign followed by 42, GitHub automatically turns that into a link pointing to issue number 42. +**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. -**Jamie:** Does it do anything besides make a link? +**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:** It does! It creates a two-way connection. If you mention issue 42 in your new issue, a timeline event automatically appears over on issue 42 saying that you referenced it. It is like a digital string tying the two documents together, so anyone reading either issue can find the other. +--- -**Jamie:** That is so helpful for keeping track of related bugs. I also read something about magic closing keywords. What are those? +**Jamie:** How would you walk the room through that step by step? -**Alex:** This is one of the best automations in GitHub. Let us say you open a pull request with code that fixes issue number 42. In the description of your pull request, you type the word Closes, followed by the number sign, and the number 42. +**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. -**Jamie:** Closes number 42. +**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:** Right. When your pull request is approved and merged into the project, GitHub sees that keyword and automatically closes issue 42 for you. You do not have to go back and do it manually. You can also use words like Fixes or Resolves. +**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:** You mentioned closing an issue. As a beginner, closing an issue sounds scary. Like I am deleting it forever. +**Jamie:** What is the common workflow underneath the different interfaces? -**Alex:** I completely understand that fear. But closing an issue does not delete anything. It just changes its state from Open to Closed. It is like crossing a task off your paper to-do list. You did not shred the paper, you just drew a line through the text. The history, the comments, and the decisions are all preserved permanently. +**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:** So if I realize a bug is actually not fixed, can I un-cross it off the list? +--- -**Alex:** Yes, you can. At the bottom of any closed issue, the Close Issue button changes into a Reopen Issue button. You just navigate to it, press Enter, and the issue is back in the Open state. +**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. -**Jamie:** Who normally closes issues? Can I close someone else's issue? +**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. -**Alex:** Usually, only the repository maintainers, or the person who originally opened the issue, have the permission to close it. This brings us to issue management. If you are a maintainer, or if you have write access to a repository, you can manage issues by assigning them and labeling them. +**Jamie:** Give me the version that sounds like an instructor, not a manual. -**Jamie:** How do I assign an issue to myself so people know I am working on it? +**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:** You go to the issue sidebar. Remember those heading level 3s? You navigate to the Assignees heading. Right next to it is a button to manage assignees. Press Enter to open it, type your username, and select yourself from the dropdown. +**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:** And applying labels works the same way? +--- -**Alex:** Exactly the same. Navigate to the Labels heading, open the menu, select the labels you want, and press Escape to close. Labels are crucial for organizing work. In fact, there is one specific label every beginner should know about. It is called good first issue. +**Jamie:** If I am listening before the workshop starts, what should settle in my mind first? -**Jamie:** Oh, I have seen that one! +**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:** Maintainers use the good first issue label to mark bugs or tasks that are perfect for people who are new to the project. The scope is usually small, and the maintainer is willing to mentor whoever picks it up. If you are looking to make your first open source contribution, searching for is colon open label colon quote good first issue unquote is the best way to start. +**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? -**Jamie:** Everything we have talked about so far has been in the browser. But in earlier episodes, you showed me how to do things from my computer's terminal. Can I manage issues from the command line too? +**Alex:** Start with What you can do here. There is something to understand, something to try, and something that proves the try worked. -**Alex:** You absolutely can, using the GitHub CLI. The command is g h space issue. +**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 kind of things can I do with it? +--- -**Alex:** Almost everything. If you open your terminal and type g h space issue space list, it prints out a list of all open issues right in your console. You can even filter it by typing g h issue list dash dash label bug. +**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. -**Jamie:** That is so fast. What if I want to read one? +**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). -**Alex:** You type g h issue view followed by the issue number. It will print the title, the description, and all the comments into your terminal. Because it is just plain text in your console, your screen reader will read it flawlessly without needing to navigate complex web page structures. +**Jamie:** Where do you want a learner to place their attention here? -**Jamie:** Can I create an issue from the terminal too? +**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:** Yes, by typing g h issue create. It will launch an interactive prompt that asks you for the title, and then opens your default text editor so you can write the body. It is a fantastic alternative if you find web forms tedious. +**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:** This has been incredibly helpful, Alex. I feel like I understand the flow of conversation on GitHub so much better now. +--- -**Alex:** I am glad to hear that, Jamie. Let us recap the key takeaways for today. First, an issue is a dedicated discussion thread for a unit of work, like a bug report or a feature request. +**Jamie:** There are a lot of tools in play. How do we keep that from feeling like a contest? -**Jamie:** Second, use the search bar and filters to find what you need. Typing is colon open label colon bug will save you from reading through hundreds of irrelevant headings. +**Alex:** Start with Learning Cards: VS Code (Desktop). There is something to understand, something to try, and something that proves the try worked. -**Alex:** Third, when reading an issue, use your heading navigation. The title is a level 1, sidebar sections and comments are level 3s. Stay in Browse mode to read, and switch to Focus mode when typing your comments. +**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. -**Jamie:** Fourth, when filing an issue, be specific! Write a headline, not just a vague category. And remember to use Markdown to format your steps to reproduce clearly. +**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. -**Alex:** And finally, use the magic keywords like Closes number 42 in your pull requests to automatically close issues when your work is done. Connecting your work creates a clear history for everyone. +**Jamie:** Let's pause on What you can do here. What should a learner take away from it? -**Jamie:** Speaking of pull requests, I hear that is what we are covering next. +**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:** We certainly are. In our next episode, Working with Pull Requests, we will take the code you have written and learn how to propose it to a project. We will cover the review process, leaving inline comments, and finally getting that code merged. You will not want to miss it. +--- -**Jamie:** I am looking forward to it. Thanks for listening, everyone! +**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:** See you next time on Gitt Going with GitHub. +**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. -### Episode 6: Working with Pull Requests +**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. -Creating, reviewing, commenting on, and merging pull requests. +--- -Based on: [Chapter 6: Working with Pull Requests](docs/06-working-with-pull-requests.md) +**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. -[Download Episode 6 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep06-working-with-pull-requests.mp3) +**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. -
-Read Transcript - Episode 6: Working with Pull Requests +**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. -#### Transcript +**Jamie:** Let's pause on What you cannot do here. What should a learner take away from it? -**Alex:** Welcome to Gitt Going with GitHub. This is episode six, Working with Pull Requests. I am Alex, and I am here to guide you through the accessibility of open source collaboration. +**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:** And I am Jamie! I am here to ask the questions, share my own learning curve, and hopefully prevent you from making the same mistakes I did when I first started using GitHub a couple of years ago. +--- -**Alex:** In our previous episodes, we covered a lot of foundational ground. In episode three, we talked about branches, which are safe parallel universes where you can experiment with code. And in episode five, we talked about issues, which are where we track bugs, feature requests, and discussions. +**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:** Right. Issues are the conversation about the work that needs to be done, and branches are where you actually do the work. But that leaves a pretty big gap. How do we get the work from our experimental branch back into the main project? +**Jamie:** Let's pause on When to choose GitHub CLI. What should a learner take away from it? -**Alex:** That is exactly what a pull request is. A pull request, often just called a P R, is a formal proposal to merge the changes from your branch into another branch. I love the name because it is literal. You are requesting that the project maintainers pull your changes into their code. +**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. -**Jamie:** When I first started, I was constantly confusing issues and pull requests. They felt like the same thing because they both have titles, descriptions, and comment threads. +**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:** That is a very common point of confusion. Think of it like a restaurant. An issue is the order ticket. It says, we need a vegetarian pizza at table four. It describes the problem or the requirement. The pull request is the chef putting the finished pizza on the counter and saying, here is the food, can the manager verify it is vegetarian before we serve it? +**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:** Oh, I like that. The issue is the work order. The pull request is the finished product waiting for inspection. +--- -**Alex:** Exactly. An issue is just text and ideas. A pull request contains actual, modified code. +**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:** Before we talk about creating one, let us understand the anatomy of a pull request page on GitHub. When you navigate to a pull request, the page is divided into three main tabs. +**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:** I use the landmarks for this. I press the D key to move through my ARIA landmarks until I hear Pull request navigation tabs. +**Jamie:** Let's pause on Switching paths is normal. What should a learner take away from it? -**Alex:** Perfect. Inside that landmark, you will find three tabs. The first is the Conversation tab. This is where you will find the pull request description, the timeline of all comments, any automated status checks, and the merge button. It is the history of the proposal. +**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. -**Jamie:** The second tab is Commits. This is just a chronological list of the individual commits that make up your pull request. It is handy if you want to step through the author's thought process commit by commit. +**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:** And the third tab is Files changed. This is the heart of the pull request. It is where you go to read the diff. A diff is the before and after comparison of every single file that was modified. We are going to spend a lot of time talking about how to read a diff with a screen reader later in this episode. +--- -**Jamie:** So, Conversation, Commits, and Files changed. That is the anatomy. How do we actually create one of these? +**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:** There are two main scenarios for creating a pull request. You are either creating it from a branch within the same repository, or you are creating it from a fork. +**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:** Let us define those. A branch in the same repository is what we do at my company. We all have write access to the main repository, so I just create a branch called jamie dash new dash feature, do my work, and open a pull request. +**Jamie:** What should the learner prove to themselves after each small task? -**Alex:** Right. The analogy there is that you and your team all live in the same house. You are building a new cabinet in the garage, which is your branch. When it is done, you ask your roommates to help you move it into the living room, which is the main branch. +**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. -**Jamie:** But open source does not work like that, right? I cannot just go create a branch on the official Microsoft accessibility repository. They do not know me. They are not going to give me write access to their house. +**Alex:** Keep the teaching thread moving. Start with The task: Open the public workshop curriculum repository and find the README file. -**Alex:** Exactly. That is where forks come in. A fork is a complete, personal copy of someone else's repository that lives on your own GitHub account. You have full control over your fork. You can create branches there, commit code there, and break things there. +--- -**Jamie:** So if the same repository branch is building a cabinet in the garage, a fork is building the cabinet at my own house across town. +**Jamie:** What does the learner do first, second, and then after that? -**Alex:** Yes. And when the cabinet is finished, you load it into a truck, drive it over to the open source project's house, and submit a pull request asking if they want it. That is a cross-repository pull request. The beauty of GitHub is that the creation process is almost identical for both. +**Alex:** Start with Path 1: GitHub.com. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** When you push a new branch to GitHub, whether it is to your fork or the main repository, GitHub is pretty smart. If you navigate to the repository homepage shortly after pushing, you will usually find a banner with a button that says Compare and pull request. I just press Enter on that button. +**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. -**Alex:** That button is a fantastic shortcut. If you do not catch the banner in time, you can always navigate to the Pull requests tab and activate the New pull request button. When you do that, you have to select two things from a set of dropdown menus. The base branch, and the compare branch. +**Jamie:** Turn that into a path someone can follow. -**Jamie:** I always used to mix those up. Base and compare. +**Alex:** Start with Path 2: github.dev. There is something to understand, something to try, and something that proves the try worked. -**Alex:** It helps to read it as a sentence. You want to merge your compare branch into the base branch. The base is the foundation. It is the destination. Usually, this is the main branch of the project. The compare branch is your new work. You are asking GitHub to compare your work against the base. +**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:** Once you select those, you land on the pull request form, which looks exactly like the form for creating a new issue. You have a title field and a description text area. +**Jamie:** What is the ordered workflow? -**Alex:** Writing a good pull request description is an art form. This is your chance to explain what changed, why it changed, and how the reviewer can test it. +**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. -**Jamie:** Please, please do not just name your pull request Fix bugs, and leave the description blank. I have been asked to review pull requests like that, and it is infuriating. I have no idea what I am supposed to be looking at. +**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. -**Alex:** A good title should be descriptive. Something like, Add keyboard navigation for the carousel component. For the description, many repositories provide a pull request template. If you tab into the description field and switch to Focus mode, you might find a checklist already waiting for you. +**Jamie:** Give me the sequence, because order matters here. -**Jamie:** If there is no template, I always try to include three things. First, a summary of what I did. Second, instructions on how to test my changes. And third, a link to the original issue. +**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. -**Alex:** Linking the issue is critical. If your pull request solves issue number forty two, you should type the word Closes, followed by a space, followed by the number sign, and the number forty two. Closes number forty two. +--- -**Jamie:** GitHub has a magic feature where if you use that exact phrasing, the moment your pull request is merged, GitHub will automatically close issue forty two for you. It keeps the project so tidy. +**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. -**Jamie:** Okay, so what if I am working on that carousel keyboard navigation, and I have made some good progress, but I am stuck. The escape key is not closing the modal. I want to push my code and get your opinion, but I do not want you or the project maintainers to accidentally merge it, because it is broken. +**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. -**Alex:** This is the perfect time to use a draft pull request. A draft pull request is a way of putting a big, virtual Work In Progress sign on your code. It signals to the team that you are actively working on it, it allows you to ask for feedback, but the merge button is completely disabled. No one can merge it, not even the repository owner. +**Jamie:** Before we leave Path 4: GitHub Desktop, what is the practical point? -**Jamie:** How do I create a draft? +**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. -**Alex:** When you are on the form to create a new pull request, do not just activate the default Create pull request button. Next to it, there is a dropdown arrow button. If you activate that, you can select Create draft pull request instead. +**Jamie:** Let's pause on Path 5: GitHub CLI. What should a learner take away from it? -**Jamie:** And when I finally figure out that escape key bug and I am ready for a real review, how do I remove the draft status? Do I have to open a new pull request? +**Alex:** Start with Path 5: GitHub CLI. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Not at all. You just open your existing draft pull request, navigate to the Conversation tab, and scroll toward the bottom. You will find a button called Ready for review. Activating that button removes the draft status, turns on the merge button, and notifies everyone that you are ready for formal feedback. +**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. -**Jamie:** That is a relief. Okay, so my pull request is out of draft mode. It is open. But no one is looking at it. How do I get someone's attention? +**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:** You need to request a review. On the pull request page, there is a sidebar region. You can navigate to the Reviewers heading, which is a level three heading. Right below that, there is a button to request reviewers. Activating it opens a search field where you can type a teammate's username and select them. +**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:** Sometimes I will open a pull request and I will notice that two people have already been requested as reviewers, and I did not even do it. It just happened automatically. +--- -**Alex:** That is usually because of a file called CODEOWNERS. Many large repositories use this file to map specific folders to specific people. If you modify a file in the accessibility folder, GitHub automatically requests a review from the accessibility team. You cannot remove them; their approval is required. +**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:** So far, we have been the author. Now, let us flip the script. Jamie, I just requested your review on my pull request. You get an email notification, you follow the link, and you are on my pull request page. What is your workflow? +--- -**Jamie:** The first thing I do is read your description on the Conversation tab so I know what you are trying to achieve. But then, I immediately move to the Files changed tab. That is where the truth is. The description is what you think you did. The Files changed tab is what you actually did. +**Jamie:** What should people carry with them after this? -**Alex:** And this is where we need to talk about screen reader navigation, because reading a code diff can be intimidating at first. When you activate the Files changed tab, GitHub presents a file tree on the left, and the actual diffs on the right. +**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:** I love the file tree. I press D to navigate to the File tree region. It is a list of every file you modified. I can use my up and down arrows to hear the file names. It gives me a high level map of the damage you did to the codebase. +**Jamie:** That is a better way to say it than just follow the steps. -**Alex:** Once you are ready to read the code, you can use heading navigation. Every changed file is a level three heading. So you can press the number 3 to jump from file to file. +**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:** When I land on a file heading, how do I actually read the changes? +
-**Alex:** Each file's diff is structured as an HTML table. So, from the file heading, press T to jump into the diff table. Then, switch your screen reader to Focus mode, or Forms mode. If you are using NVDA, that is Insert plus Space. For JAWS, it is Insert plus Z. For VoiceOver, you interact with the table. +--- -**Jamie:** Once I am in the table in Focus mode, I just use my down arrow to read line by line. +### 5. Episode 2: Understanding GitHub on the Web -**Alex:** Exactly. And the screen reader will announce the changes. Because we cannot rely on the visual layout, we listen for specific prefixes. If a line was added, your screen reader will announce a plus sign, or the word inserted, followed by the code. If a line was removed, it will announce a minus sign, or the word deleted. +How GitHub organizes its web pages, heading structure, landmarks, and keyboard shortcuts. -**Jamie:** And if a line has no plus or minus, it is just context. It is unchanged code that GitHub shows you so you know where you are in the file. +Based on: [Chapter 2: Understanding GitHub on the Web](docs/02-understanding-github.md) -**Alex:** So you are arrowing down through the table, and you hear a minus sign followed by an old heading level, and then a plus sign followed by a new heading level. You realize I made a mistake. How do you tell me? + -**Jamie:** I leave an inline comment. This is so much better than just leaving a generic comment at the bottom of the page saying, hey Alex, on line forty two of that one file, you messed up. Instead, while my focus is on the specific line in the diff table, I press the Tab key. +[Download Episode 2 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep02-github-web-structure.mp3) -**Alex:** When you press Tab from a focused line in the diff table, you will land on a button called Add a comment to this line. +
+Read Transcript - Episode 2: Understanding GitHub on the Web -**Jamie:** I press Enter on that button, and a text area opens right there in the middle of the code. I switch back to Focus mode, and type my comment. I will say, Alex, this heading level skips from a level two to a level four. We need a level three here for screen reader users. +#### Transcript -**Alex:** Now, this next part is crucial. Once you type your comment, you will see two buttons. One says Add single comment. The other says Start a review. Always, always choose Start a review. +**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:** I learned this the hard way! When I first started, I was using Add single comment for everything. I reviewed a massive pull request and left twenty inline comments. +**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:** And because you used Add single comment, GitHub sent the author twenty separate email notifications, one after another. Ding, ding, ding. +--- -**Jamie:** They were not happy with me. When you choose Start a review, GitHub saves your comment as pending. It batches them all together. You can go through the rest of the files, leave five more comments, and the author hears nothing. +**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. -**Alex:** Once you have finished reading all the files and leaving your pending comments, you need to submit the review. You navigate to the Review changes button. It is usually at the top of the Files changed tab, or at the bottom of the Conversation tab. +**Jamie:** So the goal is understanding first, then action, then confirmation. -**Jamie:** When you activate the Review changes button, a dialog opens. You can type an overall summary, like, Great work, just a few heading issues to fix. And then you have to choose a verdict using a set of radio buttons. +**Alex:** Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on. -**Alex:** The three radio buttons are Comment, Approve, and Request changes. Comment means you are just leaving general feedback, but you are not blocking the merge. Approve means the code looks great and you are giving it a green light. Request changes means you found a blocking issue, and the pull request cannot be merged until the author fixes it. +--- -**Jamie:** I select Request changes, tab to the Submit review button, and press Enter. At that exact moment, GitHub bundles all my inline comments and my summary into one single email notification and sends it to you. +**Jamie:** Okay, set the room for us. What are we walking into? -**Alex:** It is a much kinder workflow. Now, I want to take a brief detour, because there is an alternative way to review code that is incredibly popular among screen reader users. +**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. -**Jamie:** Yes! VS Code! +**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. -**Alex:** Right. Reading diffs in a web browser table works, but it can be tedious. If you use Visual Studio Code and install the GitHub Pull Requests extension, you can check out the pull request locally. +**Jamie:** What is the one idea that makes the next few steps less mysterious? -**Jamie:** And the best part of doing it in VS Code is the Accessible Diff Viewer. When you have a diff open in VS Code, you just press F 7. +**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:** F 7 opens a dedicated panel designed specifically for screen readers. Instead of making you navigate a complex table, it extracts every change into a linear list. You just press F 7 to jump from change to change. +--- -**Jamie:** It is so clean. It literally announces, Change one of three. Removed, heading level two. Added, heading level three. It takes all the mental gymnastics out of reading a diff. You can still leave inline comments right from VS Code, and they sync perfectly back to GitHub. +**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:** It is a phenomenal feature. Another alternative, if you are a terminal power user, is the GitHub CLI. You can type g h space p r space list to see all open pull requests. You can type g h space p r space diff to output the code changes straight to your terminal, which is very easy for a screen reader to read sequentially. You can even approve a pull request by typing g h space p r space review dash dash approve. +**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:** I love having options. Browser, VS Code, or Terminal. You use whatever fits your brain best. +**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:** Okay, so let us look at the timeline. I opened the pull request. You reviewed it and requested changes. I fixed the heading levels and pushed a new commit. You reviewed it again, and this time, you selected Approve. Are we ready to merge? +**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:** Almost. We have to check the bots first. +**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:** Ah yes, the Status Checks. On the Conversation tab, right below the description, there is a section for status checks. These are automated scripts that run every time you push code. They might run accessibility linters, unit tests, or security scanners. +**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. -**Jamie:** You can navigate to the Status checks heading to read the results. You want to hear All checks have passed. If you hear Some checks failed, the merge button might be blocked. You have to navigate to the specific failing check, open its logs, and figure out what broke. +**Alex:** The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work. -**Alex:** Assuming your review is approved and all status checks have passed, it is time to merge. If you are a project maintainer, you will navigate to the bottom of the Conversation tab to the merge controls. But you have a choice to make. There are three different merge strategies. +--- -**Jamie:** This used to terrify me. The dropdown gives you three options: Create a merge commit, Squash and merge, or Rebase and merge. What is the difference? +**Jamie:** If I am listening before the workshop starts, what should settle in my mind first? -**Alex:** Let us use an analogy. Imagine your pull request is a business trip, and your commits are the receipts. You have a commit for your flight, a commit for your hotel, a commit for a coffee, and a commit where you bought a pen. +**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. -**Jamie:** Okay, I have four commits. Four receipts. +**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). -**Alex:** If you choose Create a merge commit, you are taking all four individual receipts, putting them in an envelope, writing Business Trip on the envelope, and handing it to accounting. The main branch keeps every single commit exactly as you wrote it, plus one extra commit, the envelope, that ties them together. +**Jamie:** What stays the same when the tool changes? -**Jamie:** So the history shows all the messy details. The coffee, the pen, everything. +**Alex:** Keep the learner anchored in Signal 2: The browser tab title. GitHub formats page titles consistently. -**Alex:** Right. The second option is Squash and merge. If you choose squash, you take all four receipts, add up the total, throw the individual receipts in the trash, and hand accounting a single piece of paper that says Business Trip Total: eight hundred dollars. +--- -**Jamie:** Oh, I see. It squashes all my messy, incremental commits into one single, polished commit on the main branch. I use this all the time because my commit history is usually terrible. I will have commits named oops, and fixed typo again. Squashing hides my shame. +**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:** Exactly. Squash and merge keeps the main project history incredibly clean. One pull request equals one commit. +**Jamie:** Give me the version that sounds like an instructor, not a manual. -**Jamie:** What about Rebase and merge? +**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:** Rebase is like a time machine. Imagine you started your business trip a month ago, but accounting only wants receipts from this week. Rebase takes your four individual receipts, erases the dates, and stamps today's date on all of them. It replays your commits one by one onto the tip of the main branch, as if you had just written them today. +**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. -**Jamie:** No envelope, no squashing. Just taking my work and sticking it perfectly at the end of the line. +**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. -**Alex:** Exactly. Which strategy you use depends on the repository. Many open source projects enforce Squash and merge to keep their history readable. Just check the dropdown, select the strategy the project prefers, and activate the button. +--- -**Jamie:** And just like that, the pull request status changes to Merged. The code is officially part of the project. +**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:** We have covered the entire lifecycle of a pull request today. Let us recap the key takeaways. First, a pull request is a proposal to merge code, while an issue is a discussion about work to be done. +**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:** Second, use Draft pull requests when your work is not ready for review. It tells the team you are experimenting, and prevents accidental merges. +**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:** Third, when reviewing code in the browser, use the T key to jump to the diff table, and use Focus mode to read the changes line by line. Listen for the plus and minus announcements. And remember, always use Start a review to batch your inline comments, rather than sending a notification for each one. +**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:** And finally, do not forget about the F 7 Accessible Diff Viewer in VS Code. If navigating browser tables is giving you a headache, the VS Code extension is an absolute game changer for screen reader users. +**Jamie:** Let's pause on Page Type 3: Issue Detail. What should a learner take away from it? -**Alex:** In our next episode, we are going to tackle the one topic that strikes fear into the heart of every developer, blind or sighted. We are going to talk about Merge Conflicts. What they are, why they happen, and how to resolve them accessibly without panicking. +**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. -**Jamie:** I have panicked many times. I am looking forward to learning how not to. +--- -**Alex:** Until then, keep exploring, keep committing, and we will see you next time on Gitt Going with GitHub. +**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. +**Jamie:** Let's pause on Page Type 4: Pull Request Detail. What should a learner take away from it? -### Episode 7: Merge Conflicts Are Not Scary +**Alex:** Here is the plain-English version of 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. -Why conflicts happen, how to read conflict markers, and resolving them confidently. +**Alex:** Keep the thread going. Start with What to expect. There is something to understand, something to try, and something that proves the try worked. -Based on: [Chapter 7: Merge Conflicts Are Not Scary](docs/07-merge-conflicts.md) +**Alex:** The room should hear these as checkpoints. 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. - +--- -[Download Episode 7 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep07-merge-conflicts.mp3) +**Jamie:** Let's pause on Page Type 5: Your Personal Feed and Profile. What should a learner take away from it? -
-Read Transcript - Episode 7: Merge Conflicts Are Not Scary +**Alex:** Keep the learner anchored in Page Type 5: Your Personal Feed and Profile. Your personal home (github.com) shows activity from repositories you follow. This is the part to say slowly: Your profile (github.com/username) shows your contribution graph, pinned repos, and bio. -#### Transcript +**Alex:** Another way to ground it. Start with What to expect on your feed. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Welcome to Gitt Going with GitHub, the audio series for blind and low-vision developers learning the ins and outs of open source collaboration. I am Alex, and I am here with Jamie. +**Alex:** That becomes easier when you listen for these cues. A "For you" activity stream - recent activity from repos you watch. A sidebar of suggested repositories and topics. -**Jamie:** Hi everyone! I am so ready for this one. +**Jamie:** Let's pause on What to expect on your profile. What should a learner take away from it? -**Alex:** Today we are on episode seven, and the title of this episode is Merge Conflicts Are Not Scary. +**Alex:** Start with What to expect on your profile. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** I am going to hold you to that title, Alex. Because when I was learning GitHub two years ago, the phrase merge conflict literally made my stomach drop. It sounds like an error. It sounds like I broke the project and now the developers are fighting. +**Alex:** A few details make that real. 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:** That is exactly why we named the episode this way. A merge conflict is not an error, it is not a failure, and it definitely does not mean anyone is fighting. It is just a normal, everyday part of writing code with other people. Before we dive into what they are, let us quickly recap where we are in the workflow. In episode three, we talked about branches and commits, which is how you save your own independent line of work. Then in episode six, we talked about pull requests and merging, which is how you ask to bring your work into the main project. +--- -**Jamie:** Right. A pull request is you saying, here are my changes, please pull them into the main branch. And usually, you hit the merge button, and GitHub just combines everything perfectly. +**Alex:** This is the part worth saying out loud. 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:** Exactly. Git is incredibly smart. If you edit a file at the top, and I edit the same file at the bottom, Git just quietly combines them. No problem. But a merge conflict happens when two people change the exact same lines of the exact same file in different ways. Git is smart, but it is not going to guess which version is the correct one. So it stops and asks a human to decide. +**Alex:** That shows up in the workshop in a few specific ways. 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. -**Jamie:** I always think of it like two people editing the same paragraph of a shared document. Let us say we have a workshop welcome document. I go in and change the opening sentence to say, Welcome to the GitHub Workshop. But before I save and share my version, you go in and change that exact same sentence to say, Welcome Developers. If we try to combine our documents, the system throws its hands up. It cannot keep both sentences without it sounding like nonsense, and it does not want to automatically delete someone's work. +**Jamie:** Let's pause on 5. Visual Map of a Repository Page. What should a learner take away from it? -**Alex:** That is a perfect analogy. Git is doing the exact same thing. It is pausing the merge and saying, hey, I have two different versions of line twelve. Which one do you want? Or do you want to combine them yourself? That pause, that request for human intervention, is all a merge conflict is. +**Alex:** This is where 5. Visual Map of a Repository Page becomes real: see also: Appendix A: Glossary defines every term used in this course. That matters in practice: Appendix B: Screen Reader Cheat Sheet has quick-reference keyboard shortcuts for navigating headings and landmarks. +**Alex:** Keep the teaching thread moving. Keep the learner anchored in Description. A repository home page is laid out from top to bottom as follows. This is the part to say slowly: The Global Navigation bar (landmark: "Navigation Menu") contains the GitHub logo, Search, Copilot, Pull Requests, Issues, Notifications bell, and your avatar. -**Jamie:** Okay, so it is not an error. It is just Git asking a question. But how does it actually ask? When I am working on a pull request, how do I even know a conflict happened? +--- -**Alex:** If you are on the GitHub website, navigating through your pull request, you will move to the Conversation tab. Usually, at the bottom of that tab, you find the button to merge your pull request. But if there is a conflict, that merge button will be disabled. Instead, your screen reader will announce a section that says, this branch has conflicts that must be resolved. +**Jamie:** Let's pause on Screen reader navigation of this page. What should a learner take away from it? -**Jamie:** I remember hearing that for the first time. It feels like a roadblock. But right next to that message, there is a button called Resolve conflicts. +**Alex:** The reason Screen reader navigation of this page matters is that press 1 to hear "owner/repo-name" (the H1, confirms you are on the right repo). That gives the learner a simple foothold: press D to hear "Navigation Menu," then D again for "Repository navigation," then D again for "Main" (the file tree area). -**Alex:** Yes. And activating that Resolve conflicts button takes you into the GitHub web editor. This is a built in tool that lets you fix the conflict right there in your browser, without needing any terminal commands or local software. +**Jamie:** Give me the sequence, because order matters here. -**Jamie:** So what actually happens when I activate that button? I know it opens an editor, but what does the text inside look like? How does Git show me the two different versions? +**Alex:** Start with 6. Screen Reader Orientation Sequence: Do this every time you land on a new GitHub page. The next useful detail is this: It takes about 10 seconds once you are practiced. 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 we need to talk about conflict markers. When Git finds a conflict, it actually edits the file for you to inject both versions of the code, separated by very specific markers. These markers are just plain text characters. +**Alex:** These are the details that keep the idea from floating away. 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). -**Jamie:** And they can sound really weird the first time a screen reader reads them out to you. +**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). Think of it as a rail line: each stop confirms you are still on the right route before the next one. -**Alex:** They really can. There are three markers you need to know. The first marker indicates the start of your version of the code. It is seven less than signs, followed by a space, and the word HEAD. H E A D. +**Jamie:** How would you walk the room through that step by step? -**Jamie:** So your screen reader might literally say, less than less than less than less than less than less than less than HEAD. Or if your punctuation level is set lower, it might just say HEAD. That is why it is good to navigate line by line and examine the characters if something seems strange. +**Alex:** First, main content area - file tree, issue list, PR diff, etc. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. -**Alex:** Exactly. The word HEAD in Git just means your current location, the branch you are currently working on. So right below that less than HEAD marker, you will find your code. The code you wrote. +**Jamie:** Let's pause on Learning Cards: Screen Reader Orientation Sequence. What should a learner take away from it? -**Jamie:** Okay, so that is my version. What comes next? +**Alex:** Start with Learning Cards: Screen Reader Orientation Sequence. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Next is the dividing line. It is seven equals signs. Just a row of equals signs. This separates your version from the other person's version. +**Alex:** The parts worth keeping in working memory are these. 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:** Equals equals equals equals equals equals equals. Got it. And below the equals signs? +--- -**Alex:** Below the equals signs is the incoming version. The code coming from the main branch, or from whoever else edited the file. And finally, to mark the end of the conflict area, there is a third marker. It is seven greater than signs, followed by a space, and the name of the branch that the incoming code is coming from. +**Alex:** Keep the teaching thread moving. This is where 7. Landmark Structure by Page Type becomes real: each GitHub page type has a consistent landmark pattern. That matters in practice: Knowing the pattern means you can skip steps 2 and 3 above for familiar pages. -**Jamie:** So greater than greater than greater than, and then maybe the word main, or the name of my teammate's feature branch. +**Jamie:** Let's pause on 8. GitHub's Heading Hierarchy in Practice. What should a learner take away from it? -**Alex:** Exactly. So the structure is always the same. Less than signs for the start of your code. Your code. Equals signs for the divider. Their code. Greater than signs for the end of the conflict. +**Alex:** Keep the learner anchored in 8. GitHub's Heading Hierarchy in Practice. GitHub uses a predictable heading structure. This is the part to say slowly: Learning this pattern means you can navigate any page by heading level alone. +**Alex:** Keep the teaching thread moving. The reason Pull request detail - Files Changed tab matters is that 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places. -**Jamie:** So let us make this concrete. Imagine we are editing an HTML file. I am working on a button. Originally, the button just said Submit. On my branch, I changed the button text to say Send message. But someone else on the team added an accessibility label to the original button. They added an aria label that says Submit form. +--- -**Alex:** That is a very realistic scenario. Since you both changed the exact same line of HTML, you get a conflict. When you open the web editor and navigate line by line, here is what you will read. First, the less than signs and the word HEAD. Next line, your code, which is the button with the text Send message. Next line, the seven equals signs. Next line, the incoming code, which is the button with the aria label Submit form. And finally, the greater than signs and the branch name. +**Jamie:** Let's pause on Learning Cards: GitHub's Heading Hierarchy. What should a learner take away from it? -**Jamie:** So my job is to just edit this text file, right? +**Alex:** Start with Learning Cards: GitHub's Heading Hierarchy. There is something to understand, something to try, and something that proves the try worked. -**Alex:** That is the entire job. You are just in a text editor. You need to look at both versions and decide what the final code should be. In this case, you probably want both improvements. You want the new text, and you want the aria label. +**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:** So I would just type out a new line of code that combines them. A button with the aria label Submit form, and the text Send message. +**Alex:** Keep the teaching thread moving. Here is the plain-English version of 9. How GitHub's Layout Changes by Viewport. GitHub is a responsive web application. Put another way, the layout shifts at different screen widths, and this affects what landmarks and headings you encounter. -**Alex:** Perfect. And then, this is the most important part, you must delete the conflict markers. You have to delete the line with the less than signs, the line with the equals signs, and the line with the greater than signs. You also delete the old versions of the code that you no longer need. When you are done, the file should just look like normal, working code. +**Jamie:** What is the common workflow underneath the different interfaces? -**Jamie:** That is a huge aha moment for a lot of people. The markers are not special protected code. They are literally just text that Git temporarily typed into your document so you could find the conflict. You just delete them when you are done. +**Alex:** Start with At full desktop width (1200px+). There is something to understand, something to try, and something that proves the try worked. -**Alex:** Exactly. Once you have deleted the markers and the code looks correct, you navigate to the top of the file in the GitHub web editor and activate the Mark as resolved button. If you have multiple files with conflicts, there is a file navigation panel you can reach with your screen reader commands, like N V D A plus F seven, or VoiceOver plus U, to move to the next file. Once all files are marked as resolved, you activate the Commit merge button. And you are done. The conflict is gone. +**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:** Okay, that is the web editor. But what if I am working locally on my own computer, using the command line? I know a lot of developers prefer to handle things in their terminal. +**Alex:** Keep the teaching thread moving. Start with At tablet width (768-1199px). There is something to understand, something to try, and something that proves the try worked. -**Alex:** The concept is exactly the same, but the steps are a bit different. Let us say you are in your terminal and you type git space merge space main, to bring the main branch into your feature branch. Git will try to merge, but then it will output a message that says, Automatic merge failed. Fix conflicts and then commit the result. +**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. -**Jamie:** Hearing automatic merge failed definitely sounds scary the first time. +**Jamie:** Let's pause on At mobile width (below 768px). What should a learner take away from it? -**Alex:** It does! But again, it is just Git saying it needs a human. If you type git space status, it will list your files and tell you which ones are in conflict. It will say, both modified, and then the file name. +**Alex:** The reason At mobile width (below 768px) matters is that consistent experience recommendation: Use your browser maximized or at full desktop width during this workshop. That gives the learner a simple foothold: GitHub's landmark and heading structure is most consistent at desktop width. -**Jamie:** So if I see both modified, I just open that file in my normal code editor, like VS Code or Notepad? +**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. -**Alex:** Exactly. You open the file, and you will find those exact same conflict markers. The less than signs, the equals signs, and the greater than signs. You edit the text, combine the changes, and delete the markers, just like we discussed. +**Jamie:** What does the learner do first, second, and then after that? -**Jamie:** And since I am doing this on the command line, how do I tell Git that I finished fixing it? There is no Mark as resolved button in my terminal. +**Alex:** Start with 10. The Mental Model - Building Your Internal Map: After your first day of using GitHub, you will have an internal map. The next useful detail is this: Here is what that map should look like. -**Alex:** Great question. On the command line, marking a file as resolved is done by staging it. You just type git space add space, and then the file name. That tells Git, hey, I fixed this file, it is ready to go. Once you have used git add on all the conflicted files, you just type git space commit. Git will automatically create a message saying it is a merge commit, and you just save and close it. +**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. Think of it as a rail line: each stop confirms you are still on the right route before the next one. -**Jamie:** So the workflow is git merge, which triggers the conflict. Then git status to find the files. Open the files and delete the markers. Then git add to mark them as resolved. And finally git commit to seal the deal. +--- -**Alex:** You got it. And for those of you who will be using VS Code on day two of the workshop, it gets even easier. VS Code has built in tools for this. When you open a conflicted file, it adds invisible action links right above the conflict, which you can reach by pressing Tab. These links are called CodeLens actions. +**Jamie:** Let's pause on Learning Cards: Building Your Internal Map. What should a learner take away from it? -**Jamie:** Oh, I love CodeLens. It is so much faster. +**Alex:** Start with Learning Cards: Building Your Internal Map. There is something to understand, something to try, and something that proves the try worked. -**Alex:** It really is. Your screen reader will read options like Accept Current Change, which keeps your code. Accept Incoming Change, which keeps their code. Or Accept Both Changes. You just press Enter on the one you want, and VS Code automatically deletes the markers and formats the code for you. You just save with Control plus S, stage the file with Control plus Shift plus G, and commit. +**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:** And if you are using GitHub Copilot, you can press Control plus Shift plus I to open Copilot Chat and ask it to explain the conflict to you. You can say, explain what these two changes are trying to do. But a quick warning here, you should always understand how to read the markers yourself before relying on AI. You need to verify that the final code actually makes sense. +**Jamie:** Turn that into a path someone can follow. +**Alex:** This is where Try It: The 60-Second Orientation becomes real: time: 1 minute What you need: A browser with your screen reader running. That matters in practice: Open any GitHub repository - try github.com/community-access/accessibility-agents - and prove to yourself that the mental model works. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed. -**Alex:** Absolutely. Now, before we move on, I want to mention a couple of really handy commands if you are using the GitHub Command Line Interface, or the G H tool. Sometimes you want to check if a pull request has conflicts before you even try to merge it. +**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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Jamie:** Right, because maybe I am reviewing someone else's pull request from my terminal. +**Jamie:** Where does the workshop stop being a tour and start becoming contribution? -**Alex:** Exactly. You can type the command G H space P R space checks, followed by the pull request number. This will tell you the status of the pull request. You can also type G H space P R space view, which will output a summary, and it will clearly state if the branch has conflicts that must be resolved. If you want to see the actual changes, G H space P R space diff will show you line by line what was added and removed. +**Alex:** Keep the learner anchored in Day 2 Amplifier. Once you have this mental model solid, the Accessibility Agents make more sense. This is the part to say slowly: 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:** That is super helpful for staying in the terminal and not having to bounce back and forth to the browser just to check the status. +--- +**Jamie:** What should people carry with them after this? -**Alex:** So we have talked about how to resolve conflicts. But there is a famous saying in software development. Prevention is easier than resolution. +**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:** Yes! Let us talk about how to avoid these in the first place. Because while they are not scary, they do take time to fix. What is the best way to prevent merge conflicts? +**Jamie:** That is a better way to say it than just follow the steps. -**Alex:** The number one rule is to keep your branches short lived. If you create a branch and work on it for three weeks without merging it, the main branch is going to change dramatically in that time. When you finally try to merge, you are going to have a massive conflict. +**Alex:** Right. Steps matter, but understanding wins. That is episode 2. Next in the series is episode 3, where we keep building the same contributor muscles. -**Jamie:** So target one to three days. Keep your changes small and focused. If you are building a huge feature, break it down into smaller pull requests. A pull request that changes five files merges easily. A pull request that changes fifty files is almost guaranteed to conflict with something. +
-**Alex:** Rule number two is to sync with the main branch frequently. If you are working on a branch for a few days, start your morning by pulling the latest changes from main into your branch. You can do this with git space pull space origin space main. This brings in everyone else's approved work. If there is a small conflict, you catch it early and fix it locally, rather than waiting until the very end. +--- -**Jamie:** I also want to add communication to this list. Especially in our workshop environment. If you know you are going to be editing the workshop welcome document, leave a comment on your issue saying, heads up, I am working on the welcome document today. That way, if another student is also assigned a challenge that touches that file, they can coordinate with you. +### 6. Episode 19: Screen Reader Cheat Sheet -**Alex:** Communication is huge. Another common trap is mass reformatting. Let us say you open a file and notice the indentation is a bit messy, so you run a tool that reformats all five hundred lines of the file. +NVDA, JAWS, and VoiceOver commands for GitHub and VS Code. -**Jamie:** Oh no. I have done this. +Based on: [Appendix B: Screen Reader Cheat Sheet](docs/appendix-b-screen-reader-cheatsheet.md) -**Alex:** We all have! The problem is, Git sees that as you changing all five hundred lines. If anyone else on your team changed even one line of logic in that file, you will create a conflict. If you need to reformat a file, do it in a separate, dedicated pull request, announce it to your team, and get it merged immediately before anyone else does work in that file. +Audio and transcript are being regenerated for this episode. -**Jamie:** That makes so much sense. What about fast forward merges? I have heard that term thrown around. +
+Read Transcript - Episode 19: Screen Reader Cheat Sheet -**Alex:** A fast forward merge is the ideal scenario. It happens when your branch is perfectly up to date with main, and you just added new commits on top. Because there are absolutely no diverging changes, Git does not even need to create a merge commit. It just fast forwards the main branch to point to your latest commit. Zero chance of conflicts. You can achieve this by rebasing your branch on main right before you merge, but rebasing is an advanced topic that rewrites history, so we will save the deep dive on that for another time. +#### 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:** Okay, Alex. I have tried to keep my branches small. I tried to communicate. But I still got a massive conflict, and I am sitting here looking at a file with ten different conflict markers, and I honestly do not understand what the incoming code is trying to do. I am stuck. What do I do? +**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 first thing you do is take a breath. The second thing you do is ask for help. It is completely normal and expected to ask for help with a merge conflict. You can go to your pull request on GitHub, leave a comment, and tag the author of the incoming changes. You can say, hey, I have a merge conflict in the index file, and I am not sure which version to keep. Could you help me understand the intent of your changes? +--- -**Jamie:** People love when you ask that, by the way. It shows you care about not breaking their code. +**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. -**Alex:** Exactly. And if the conflict is just completely overwhelming, maybe your branch is weeks old and everything has changed, there is always the nuclear option. +**Jamie:** So we should explain the why clearly enough that the steps make sense when the learner meets them later. -**Jamie:** The nuclear option? +**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:** Abandon the branch and start fresh. +--- -**Jamie:** Oh, wow. Is that allowed? +**Jamie:** Okay, set the room for us. What are we walking into? -**Alex:** It is absolutely allowed, and sometimes it is the smartest move. You just close your pull request without merging it. You switch back to the main branch, make sure it is up to date, and create a brand new branch. Then, you just manually apply your specific changes to the new branch. Sometimes copying your logic over to a fresh, up to date branch takes ten minutes, whereas untangling a massive merge conflict could take hours. Starting over is not a failure. It is a legitimate strategy. +**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. -**Jamie:** I love that. It takes so much pressure off. If I mess up resolving a conflict, or if it is too confusing, I can just close it and start over. I have not ruined the project. +**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:** You definitely have not. Your first conflict resolution is always the hardest. It feels abstract and dangerous. But once you resolve one, once you delete those less than and greater than signs and see your code merge successfully, you will realize it is just a text editing puzzle. +**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:** This has been incredibly helpful. Let us wrap up with some concrete takeaways for everyone listening. +**Jamie:** What is the one idea that makes the next few steps less mysterious? -**Alex:** Takeaway number one. A merge conflict simply means two people changed the same lines of the same file, and Git needs a human to pick the correct version. It is normal, healthy collaboration. +**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:** Takeaway number two. Conflict markers are just text injected into your file. Less than signs for your code, equals signs for the divider, and greater than signs for the incoming code. Your only job is to edit the text to look how you want, and delete the marker lines. +--- -**Alex:** Takeaway number three. You can resolve conflicts right in the browser using the GitHub web editor, or locally using git status, git add, and git commit. If you use VS Code, take advantage of the CodeLens features to accept changes with a single keystroke. +**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:** And takeaway number four. Prevention is the best medicine. Keep your pull requests small, sync with the main branch frequently, and communicate with your team about what files you are touching. And if you get stuck, it is always okay to ask for help or just start a fresh branch. +**Jamie:** What would you say to someone who is already bracing for this to be too much? -**Alex:** Perfectly summarized. That is all for episode seven. In our next episode, we are shifting gears to talk about Culture and Etiquette. We will cover how to write a great issue, how to review someone else's code kindly, and the unwritten rules of open source communication. +**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. -**Jamie:** I cannot wait for that one. See you all next time! +**Alex:** The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work. -**Alex:** Thanks for listening to Gitt Going with GitHub. Happy coding. +**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? -### Episode 8: Open Source Culture and Etiquette +**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. -Communication norms, code review etiquette, inclusive language, and asking questions. +**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.). -Based on: [Chapter 8: Open Source Culture and Etiquette](docs/08-open-source-culture.md) +**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. -[Download Episode 8 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep08-culture-and-etiquette.mp3) +--- -
-Read Transcript - Episode 8: Open Source Culture and Etiquette +**Jamie:** What is the ordered workflow? -#### Transcript +**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:** Welcome to Gitt Going with GitHub. This is Episode 8: Open Source Culture and Etiquette. I am Alex, and today we are shifting gears. Over the past few episodes, we have covered the mechanical side of GitHub. We talked about branches, commits, pull requests, and resolving merge conflicts. But today, we are focusing on the human side of open source software. +**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:** Hi everyone, Jamie here. And I have to admit, this is the topic that intimidated me the most when I was learning GitHub two years ago. The terminal commands were tricky, sure, but the idea of talking to strangers on the internet, asking them to accept my code, and worrying I might say the wrong thing or break some unwritten rule? That was terrifying. +--- -**Alex:** That is such a common feeling, Jamie. And it makes perfect sense. Technical skills get your code into a project, but communication skills are what keep you welcomed in the community. When you are contributing to open source, you are stepping into a pre-existing community. It is like walking into a crowded room where everyone already knows each other. You want to be polite, clear, and respectful. So today, we are going to demystify the unwritten rules of open source communication. +**Jamie:** Give me the sequence, because order matters here. -**Jamie:** I love that. Where do we start? +**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:** Let us start with the nature of the communication itself. Open source collaboration happens primarily in writing, asynchronously, and in public. Understanding those three characteristics shapes everything we do. Because we communicate entirely in writing, we have to think very carefully about how tone comes across in text without vocal cues. +**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. -**Jamie:** Right. There is no tone of voice, no body language, no immediate way to see if someone is confused or offended. It is like when you get a text message from a friend that just says, "Fine." with a period at the end. In person, they might say it with a smile, meaning "sounds good." But in text, that period makes it feel incredibly aggressive. +**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. -**Alex:** Exactly. A message that sounds perfectly neutral or just a bit brief in your head can read as hostile to the person on the other end. Sarcasm and irony are nearly impossible to convey safely, so it is best to avoid them entirely. The unwritten rule here is to be relentlessly explicit and assume good intent. Instead of saying, "This is problematic," you might write, "I think this approach might cause an issue with keyboard navigation because of the following reasons." +**Jamie:** Let's pause on Markdown formatting shortcuts in GitHub text areas. What should a learner take away from it? -**Jamie:** And because it is asynchronous, you are not having a real-time chat. When I first started, I would leave a comment and just sit there waiting for a reply, getting anxious. But the maintainer might live on the other side of the world and be asleep. +**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:** Precisely. Comments are not instant messages. You might be in a rush, but the reader is not receiving that urgency from your message. This means you need to provide all necessary context in every single message. Do not assume continuity. If you solved a problem, do not just write "Fixed it." Explain what you fixed and how, because the person reading it tomorrow will not have the context of what you were doing today. And finally, remember that everything is in public. Write as if your most supportive mentor and your most critical reviewer are both reading your comments, because anyone on the internet can find them. +**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. +--- -**Alex:** Now that we understand the environment, let us talk about the two main ways you will communicate: issues and pull requests. Let us start with writing a good issue description. Jamie, how would you define an issue? +**Jamie:** What is the safe way to learn from that example? -**Jamie:** An issue is basically a ticket. It is how you report a bug, request a new feature, or ask a question about the project. +**Alex:** Start with VoiceOver users. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Perfect. And writing a good issue description comes down to three things: context, steps to reproduce, and expected versus actual behavior. Think of it like taking your car to a mechanic. If you just drop the car off and say, "It makes a noise," the mechanic has no idea where to start. But if you say, "When I am driving over forty miles per hour and I press the brake pedal, the front left tire makes a grinding noise," the mechanic can replicate the exact conditions to find the problem. +**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. -**Jamie:** That makes so much sense. So for a software bug, context means explaining your environment. Like, "I am using Windows Eleven, with the NVDA screen reader, on the latest version of Firefox." +**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. -**Alex:** Exactly. Then you list the exact steps to reproduce the problem. For example, "Step one: Navigate to the login page. Step two: Enter a valid username but leave the password field blank. Step three: Press the Submit button." +**Jamie:** Let's pause on Using GitHub shortcuts alongside a screen reader. What should a learner take away from it? -**Jamie:** And then the expected versus actual behavior. So I would say, "Expected behavior: The screen reader announces 'Password is required'. Actual behavior: The screen reader announces nothing, and focus is lost." +**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:** You nailed it. That level of detail saves the project maintainer hours of debugging time. Even if you do not know how to fix the bug yourself, writing an issue description that clear is a massive contribution to the project. +--- -**Jamie:** Okay, so that is issues. What about writing a good PR description? Remind me, PR stands for pull request, right? +**Jamie:** How do you keep commands from becoming magic words? -**Alex:** Yes. A pull request, and I love that name because you are literally requesting that someone pull your changes into their project. When you open a PR, you need to provide a description. A good PR description needs to answer three questions: what did you change, why did you change it, and how can the reviewer test it. +**Alex:** Start with Practical sequence for G shortcuts. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** I remember my very first PR. I fixed a typo in a documentation file. My description just said, "Fixed typo." I thought I was being efficient! +**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. -**Alex:** It is a common mistake! But remember, the maintainer might be reviewing twenty pull requests that day. A better description would be: "What: Fixed a spelling error in the installation guide. Why: The command to install the package was missing a letter, which caused an error when users copied and pasted it. How to test: Read the installation section and verify the command is now correct." +**Jamie:** Let's pause on Discover shortcuts on any page - The? Key. What should a learner take away from it? -**Jamie:** That is so much better. It is like handing over your shift at a job. You do not just hand the next person the keys and walk away. You tell them what happened during your shift, why you made certain decisions, and what they need to check on next. +**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:** That is a brilliant analogy. And here is a quick tip for our listeners using screen readers. When you are writing these descriptions on GitHub, you are often typing the same phrases over and over. GitHub has a feature called Saved Replies. You can save text snippets and insert them into any comment box. You just navigate to the comment text area, activate the Saved Replies button in the toolbar, or press Control plus period, and you can filter through your saved templates. It is a huge accessibility win to avoid retyping standard issue formats. +**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:** Okay, so we know how to write issues and pull requests. Let us talk about the rules of the community itself. When I look at an open source project, I almost always see a file called Code of Conduct. What exactly is that, and why does it exist? +--- -**Alex:** The Code of Conduct is essentially the social contract of the project. It is the house rules for a community center. It outlines what behavior is expected and what behavior is unacceptable. It exists to protect contributors, especially those from marginalized groups, from harassment, discrimination, or abuse. When you see that file, it signals that the maintainers take community health seriously and that there is a formal process for reporting violations. +**Jamie:** Let's pause on Repository navigation - on any repository page. What should a learner take away from it? -**Jamie:** It is reassuring to know it is there. And I imagine a big part of following the Code of Conduct is using inclusive language. Why does inclusive language matter so much in open source? +**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:** Open source is global. You are collaborating with people from different cultures, people who speak different languages, and people with different life experiences. Inclusive language ensures we do not accidentally alienate or demean anyone. For example, using words like "crazy" or "insane" to describe a piece of code can be stigmatizing. Instead, we can use precise words like "complex", "unpredictable", or "difficult to maintain." +**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. -**Jamie:** Oh, I have another example! When I was starting out, I hated reading documentation that said, "Obviously, you just run this command," or "Simply do this." When it did not work for me, or I did not understand it, the word "obviously" made me feel like I was stupid. +**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:** Yes! Words like "obviously", "simply", or "just" are alienating. What is obvious to a senior developer is not obvious to a beginner. The easiest fix is to just omit those words entirely. Instead of "Obviously, this function returns a string," you write, "This function returns a string." It is cleaner and kinder. +**Jamie:** Let's pause on Issue and pull request detail pages. What should a learner take away from it? -**Jamie:** Another thing I learned is to focus on the code, not the person. Instead of saying, "You made a mistake here," you say, "There is an error on line forty." It takes the ego out of 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:** Exactly. Preferring the word "we" is also a great strategy. "We need to update this logic," rather than "You need to update this logic." It frames the project as a collaborative effort. And when it comes to inclusive commenting specifically for accessibility issues, precision is key. Do not generalize and say, "This website is completely unusable for blind people." That might not be accurate, and it can sound dismissive. Instead, represent the specific gap. Frame it as, "Because the submit button lacks an accessible name, users relying on screen readers cannot determine its purpose." Quote your exact screen reader output, and specify whether you are using JAWS, NVDA, or VoiceOver, because the experiences can differ. +--- +**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 us move on to the part of open source that used to make me sweat: Code Review. This is when you submit your pull request, and other developers examine your code before it gets merged. How do we handle giving and receiving code review feedback gracefully? +**Jamie:** Let's pause on Notifications page. What should a learner take away from it? -**Alex:** Let us start with giving code review feedback. The golden rule is to be specific, be kind, and focus on the code. Think of yourself as a peer editor in a writing class, not a teacher grading a test. We teach a five-step anatomy for helpful feedback. +**Alex:** Keep the learner anchored in Notifications page. On your Notifications page (github.com/notifications). -**Jamie:** I have my notes ready. What are the five steps? +**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:** Step one: Acknowledge what is working. Before identifying problems, name what is good. This is not empty flattery; most contributions have real strengths. Step two: Identify the specific concern. Vague feedback like "This is inaccessible" is useless. Be precise. Step three: Explain why it matters. Context turns a complaint into a lesson. +**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:** Okay, so if I say, "This button has no accessible name," that is step two. Step three would be adding, "Without an accessible name, a screen reader will just announce 'button,' which gives the user no context." +--- -**Alex:** Exactly. Step four is: Suggest a path forward. Offer an idea, like, "Something like an aria-label would work well here." And finally, step five: Signal the weight of the concern. Help the contributor understand if this is a hard blocker that must be fixed before merging, or just a minor preference. +**Jamie:** Let's pause on Projects (board and table view). What should a learner take away from it? -**Jamie:** I see the word "nit" used a lot in reviews. Like N I T. What does that mean? +**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:** "Nit" is short for nitpick. It is a way of saying, "This is a very minor, optional suggestion. Feel free to ignore it." Like pointing out a trailing space or a slight formatting preference. +**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. -**Jamie:** Let us try an exercise. I am going to give you a harsh comment, and you rewrite it using those steps. Here is the comment: "This alt text is bad. Fix it." +**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. -**Alex:** Oh, that is a rough one. Okay, here is how I would rewrite it. First, acknowledge something good. "Nice catch adding this image, it really helps illustrate the step." Then, the concern and the why. "I noticed the alt text just says 'image one dot PNG'. Screen reader users will hear the filename instead of what is actually in the picture." Finally, the suggestion. "Could you describe what the screenshot shows, like 'Settings page with the Accessibility section expanded'? That way everyone gets the same information." +**Jamie:** Let's pause on "I'm hearing too much or navigating too slowly". What should a learner take away from it? -**Jamie:** Wow. If I received the first comment, I would want to quit the project. If I received your rewritten comment, I would feel encouraged and immediately know how to fix 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:** That is the power of good communication. Now, let us talk about receiving code review feedback. The most important rule: do not take it personally. +**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. -**Jamie:** This was so hard for me! When I got my first PR reviewed, the maintainer left six comments requesting changes. I felt like I had failed. I thought, "Well, they hate my code, I am a terrible developer." +--- -**Alex:** That is imposter syndrome talking. Code review is a normal, healthy part of the software development lifecycle. Even the most senior developers in the world get change requests on their pull requests. It is about making the code robust, not about judging your worth as a developer. When you receive feedback, take a breath. Look for the valid concern underneath the words. And always say thank you. When someone takes the time to review your work, acknowledge it. +**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. -**Jamie:** What if I disagree with the feedback? What if they tell me to change something, but I know my way is actually better for accessibility? +**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. -**Alex:** That is a great question. You need to know how to disagree respectfully. First, make your case once, clearly, and provide evidence. You might say, "I considered using an 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." You explain your choice. +**Jamie:** Let's pause on "I can't find the comment box". What should a learner take away from it? -**Jamie:** And if they still say no? +**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:** Then you have to accept that the maintainer has the final say in their project. It is their house. If you strongly disagree, the beauty of open source is that you can always fork the project and take it in a different direction. But fighting endlessly in a comment thread is not productive. +**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. -**Jamie:** Speaking of maintainers, I think it is important to talk about who these people actually are. When I started, I pictured a team of paid professionals sitting in a corporate office, waiting to review my code. +**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. -**Alex:** That is a very common misconception. The reality is that the vast majority of open source maintainers are volunteers. They have day jobs, families, and lives outside of GitHub. They are maintaining these projects in their spare time, out of passion or a sense of community. Understanding that maintainers are volunteers with limited time completely changes how you should interact with them. +--- -**Jamie:** Right. It means practicing patience with response times. If you open a pull request on a Friday night, do not leave a comment on Saturday morning asking why no one has reviewed it yet. +**Jamie:** Let's pause on Official Screen Reader Resources. What should a learner take away from it? -**Alex:** Exactly. Think of it like a community garden. The people managing it are doing it because they love gardening, not because it is their full-time job. If you plant some seeds and ask the manager a question, you might have to wait until they come by on the weekend. If you have been waiting a week or two for a review on your PR, it is perfectly fine to leave a polite follow-up. You can simply say, "Hi, just checking in on this PR when you have a moment." +**Alex:** Start with Official Screen Reader Resources. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** What about asking questions? If I am trying to fix a bug and I get stuck, when is the right time to ask for help, and how should I frame it clearly? +**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:** You should always feel empowered to ask questions. The key is to show what you have already tried. Do not just say, "How do I fix this?" Instead, frame it clearly: "I am trying to fix the broken link on line twenty-four. I searched the repository for the correct URL, but I could not find a file at that path. Can you point me in the right direction?" This shows respect for the maintainer's time because you proved you tried to solve it yourself first. +**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:** I like that. And I want to mention something called the "Good first issue" social contract. Many projects label certain issues as "good first issue" to welcome new contributors. +**Jamie:** Let's pause on Screen Reader Compatibility Notes. What should a learner take away from it? -**Alex:** Yes, and those labels are fantastic. When a maintainer uses that label, they are signaling that they are willing to invest time in mentoring a beginner. But there is a contract there. If you want to work on it, you need to leave a comment claiming it, like, "Hi, I would like to work on this. Can I be assigned?" +**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:** And then you wait for assignment! Do not just start coding. If two people work on it in parallel, someone's time gets wasted. And if you get stuck, or life gets busy and you cannot finish it, just tell them. Say, "Life got busy, you should reassign this." Do not just disappear. +--- -**Alex:** That is professional etiquette at its finest. One final note before we wrap up today. Many of you might be using AI assistive tools, like GitHub Copilot or other agentic workflows, to help draft code or even draft review comments. Remember this: Accessibility Agents' outputs are your responsibility. If an AI drafts a triage reply or a code review for you, your name appears on it in the repository's public history. The agent writes it, but you publish it. Always review an agent-generated comment against the anatomy of helpful feedback we discussed today. Ensure the tone is kind, the language is inclusive, and it does not sound like a cold, automated robot. You are responsible for the culture you help shape. +**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. -**Jamie:** This has been such a great conversation, Alex. I feel like we have covered a lot of ground. What are the main takeaways our listeners should walk away with today? +**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. -**Alex:** I would boil it down to four concrete takeaways. First, open source communication is public, text-based, and asynchronous. Provide full context in your issue and PR descriptions, and do not rely on tone to convey your meaning. Be explicit. Second, when reviewing code, be kind and focus on the code, not the person. Use the five-step feedback anatomy: acknowledge, identify, explain, suggest, and signal. +--- -**Jamie:** Third, do not take feedback personally. Everyone gets change requests on their pull requests. It is a collaborative process to make the software better. And fourth, remember that maintainers are usually volunteers. Be patient with response times, assume good intent, and respect the project's Code of Conduct. +**Jamie:** What should people carry with them after this? -**Alex:** Beautifully summarized, Jamie. Taking the time to master these communication skills will make you a highly valued contributor in any open source community. That is all for Episode 8. In our next episode, we will dive into project management on GitHub, specifically focusing on Labels, Milestones, and Projects. We will learn how repositories organize thousands of issues so nothing gets lost. +**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:** I am looking forward to it. Until next time, happy collaborating! +**Jamie:** That is a better way to say it than just follow the steps. -**Alex:** Keep building, and we will catch you in the next episode of Gitt Going with GitHub. +**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.
+--- -### Episode 9: Labels, Milestones, and Projects +### 7. Episode 3: Navigating Repositories -Organizing and tracking work with labels, milestones, and GitHub Projects. +Exploring a repository: tabs, files, README, branches, and commit history. -Based on: [Chapter 9: Labels, Milestones, and Projects](docs/09-labels-milestones-projects.md) +Based on: [Chapter 3: Navigating Repositories](docs/03-navigating-repositories.md) -[Download Episode 9 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep09-labels-milestones-projects.mp3) +[Download Episode 3 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep03-navigating-repositories.mp3)
-Read Transcript - Episode 9: Labels, Milestones, and Projects +Read Transcript - Episode 3: Navigating Repositories #### Transcript -**Alex:** Welcome to Gitt Going with GitHub. This is episode nine, Labels, Milestones, and Projects. I am Alex, and I am here with Jamie. +**Alex:** Welcome to episode 3 of Git Going with GitHub: Navigating Repositories. 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:** Hello everyone. If you have been following along, you know we have covered a lot of ground. Back in episode five, we talked about how to create and participate in issues. But today, we are tackling the big question. What happens when a repository has hundreds, or even thousands, of open issues? How do you keep track of it all? +**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:** That is exactly what we are focusing on today. Labels, milestones, and projects are the organizational layer of GitHub. They take a chaotic list of issues and pull requests and turn them into a structured, prioritized body of work. By the end of this episode, you will understand how to categorize work, group it into goals, and track it across your entire team. +--- -**Jamie:** I remember the first time I landed on a popular open source repository. I opened the issues tab, and there were literally two thousand open issues. It was completely overwhelming. I had no idea what was being worked on, what was abandoned, or where I could even begin to help. +**Alex:** The lesson focus is Exploring a repository: tabs, files, README, branches, and commit history. We will treat every step as a teachable decision, because that is what makes the skill portable. -**Alex:** It is a very common experience. And that is why the first tool we are going to discuss is so important. Let us talk about labels. If we need a real world analogy, think of labels like the metadata tags on a blog, or the category tags you might use in your email inbox. They communicate at a glance what category, priority, or status an item belongs to. +**Jamie:** So we should explain the why clearly enough that the steps make sense when the learner meets them later. -**Jamie:** And just to be clear, GitHub provides a standard set of labels by default when you create a repository, right? +**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:** Yes, they do. When you start a new project, GitHub gives you a handful of universal labels. You will almost always see a label called bug, which means something is not working as expected. You will see enhancement, which means a new feature request. There is documentation, for changes that only affect the read me or help files. +--- -**Jamie:** My personal favorite when I was starting out was the good first issue label. If you are learning a new codebase, filtering by good first issue is the best way to find a bug that the maintainers have specifically flagged as being suitable for a beginner. +**Jamie:** Okay, set the room for us. What are we walking into? -**Alex:** Absolutely. There is also help wanted, which means the maintainers are actively seeking community help to solve a problem. And you will see labels for things that are not going to be fixed, like duplicate, invalid, or wont fix. +**Alex:** Start with A Screen Reader Guide to GitHub Repositories: everything you need to explore a GitHub repository using your keyboard and screen reader. The next useful detail is this: 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. -**Jamie:** So how does a screen reader actually handle these? Because if you ask a sighted developer, they will tell you that labels are color coded tags. The bug label is usually red, enhancement is blue, and so on. As a screen reader user, do I need to care about the colors? +**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:** Not at all. The color is strictly supplementary visual information. When you scan the issue list with your screen reader, the labels are announced right alongside the issue title. You will hear something like, Issue forty two, Add keyboard navigation to carousel, Labels: accessibility, good first issue. The text name of the label is what matters. +**Alex:** The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 3). Chapter 3 is a confidence-building orientation 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:** That is a relief. So, if I want to see every label that exists in a repository, where do I go? +**Alex:** The practical anchors are these. There are none. Automation check: none. Why: this chapter teaches navigation foundations that are practiced in later issue and PR chapters. -**Alex:** You will want to navigate to the Labels page. From the main page of a repository, you first navigate to the Issues tab. Once you are there, the Labels link is located in the filter toolbar, right above the main list of issues. For screen reader users, the quickest way is to press the letter K to navigate through the links on the page until you hear Labels. It is usually right next to the Milestones link. When you activate that link, you land on a page that lists every single label in the project, along with a text description of what it means. +**Jamie:** What does the learner do first, second, and then after that? -**Jamie:** And if you prefer the command line, you can do this without ever opening your browser. You can open your terminal and type g h space label space list. It will print out every label and its description right there in your console. I use that all the time to quickly check if a repository has an accessibility label before I file a bug. +**Alex:** This is where Safety-First Learning Pattern becomes real: use this sequence before moving to graded chapters. -**Alex:** That is a great tip. Now, let us talk about how you actually apply a label to an issue or a pull request. Let us say you just created an issue about a broken button, and you want to label it as a bug. +**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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Jamie:** This was tricky for me at first because the label controls are not in the main content area with the issue text. They are tucked away in the right sidebar. +--- -**Alex:** Exactly. When you have an issue open, you need to navigate to the sidebar. The easiest way to do this with a screen reader is to press the letter H, or the number 3, to jump by heading until you hear the heading called Labels. Right after that heading, there is a gear button, which might be announced as an edit button. +**Alex:** Now bring the learner back to the room. 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:** And when you activate that gear button, a dropdown menu opens with a list of all the available labels. You can use your up and down arrow keys to move through them, and press Enter to select or deselect a label. +**Jamie:** What would you say to someone who is already bracing for this to be too much? -**Alex:** You can also just start typing when that dropdown opens. If you type the word bug, it filters the list instantly. You press Enter to apply it, and then press Escape to close the dropdown. The label is applied immediately. There is no separate save button you have to hunt for. +**Alex:** The reason What Is a Repository Page? matters is that 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 gives the learner a simple foothold: this page has several distinct regions. -**Jamie:** And again, for my fellow terminal fans, the GitHub C L I makes this incredibly fast. If you want to label issue number forty two, you just type g h space issue space edit space forty two space dash dash add dash label, followed by the name of the label in quotes. You can even add multiple labels at once by separating them with a comma. +**Alex:** The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work. -**Alex:** So now that we have labels on our issues, the real power comes from filtering. Let us go back to Jamie's earlier example of looking at a repository with two thousand open issues. You do not want to read all of them. You only want to read the ones labeled good first issue. +**Alex:** That matters because of the next idea. Start with Description: The repository home page is organized from top to bottom as follows. The next useful detail is this: The Navigation bar (GitHub global nav) contains the avatar menu, Notifications, and search. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need. -**Jamie:** Right. To do that, you navigate to the filter bar on the Issues page. You can usually jump straight to it by pressing the letter F. The filter bar is just a text input field. By default, it will probably say is colon open, which means it is only showing open issues. All you have to do is add a space, and then type label colon, followed by the label name. So, label colon quote good first issue quote. Press Enter, and suddenly those two thousand issues become a list of maybe ten highly relevant issues. +--- -**Alex:** You can combine these too. You could type label colon accessibility, space, label colon bug. That will show you only the issues that have both of those exact labels applied. +**Jamie:** How would you walk the room through that step by step? -**Jamie:** What if the default labels are not enough? In the hackathon we are running, we want to track issues that are blocked by external dependencies. There is no default label for that. Can we create our own? +**Alex:** Here is the plain-English version of Landing on a Repository - What to Expect. When you first navigate to a repo URL. -**Alex:** Yes, as long as you have write access to the repository, you can create custom labels. You navigate back to that Labels page we discussed earlier. You tab to the New Label button and activate it. This opens a form with three fields. First is the label name, where you would type blocked. Second is the description, where you might type, waiting on external dependency. +**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". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. -**Jamie:** And the third field is the color, right? How does that work for us? +**Jamie:** What should happen before anyone copies and runs it? -**Alex:** The color field will usually auto populate with a random hex code. You can completely ignore it if you want to, or you can type in a specific hex code if your team has a visual design system. But again, the color is purely visual. The name and the description are what make the label accessible and useful to everyone. Once you fill those out, you tab to the Create label button, press Enter, and your new label is ready to be used by anyone on the project. +**Alex:** This is where Orientation sequence (do this on every new repo) becomes real: 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. That matters in practice: 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:** Okay, so labels help us categorize what an issue is. It is a bug, it is documentation, it is blocked. But what if we need to organize things by when they need to be finished? That brings us to our second topic, milestones. +**Jamie:** What is the one idea that makes the next few steps less mysterious? -**Alex:** Exactly. If labels answer the question of what, milestones answer the question of when. Milestones group issues and pull requests toward a shared goal or a deadline. +**Alex:** Keep the learner anchored in 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). This is the part to say slowly: Not all tabs appear on every repository - Discussions, Wiki, and Projects must be enabled by the repository owner. -**Jamie:** I like to think of a milestone as a shipping container. You have a bunch of separate boxes, which are your issues. You load them all into the shipping container, which is the milestone. The ship cannot leave the dock until every box inside that container is packed and sealed. In software development, this usually represents a version release, like Version 2 point 0, or a time boxed sprint. +--- -**Alex:** That is a perfect analogy. A milestone has a title, an optional description, an optional due date, and a progress bar. The progress bar tracks the percentage of closed issues versus the total number of issues assigned to that milestone. +**Jamie:** What is the ordered workflow? -**Jamie:** When you are on the issues page, you can press the letter K to find the Milestones link, right next to the Labels link we used earlier. If you activate it, you get a list of all the active milestones. And I love how screen readers announce this. You will hear something like, Hackathon Day 1 Deliverables, 3 of 8 issues closed, due April 20. It gives you the entire context in one sentence. +**Alex:** The reason How to reach the tabs matters is that the tab bar is visible just below the repository name. That gives the learner a simple foothold: click the tab you want - Code, Issues, Pull requests, etc. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places. -**Alex:** It is very efficient. If you press Enter on a milestone title, you open its detail page, which simply lists all the issues and pull requests assigned to it. You navigate that list just like any other issue list, pressing the number 3 to jump from issue title to issue title. +**Alex:** That becomes easier when you listen for these cues. 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. -**Jamie:** So how do we actually put an issue into that shipping container? How do we assign it to a milestone? +**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. The rhythm is simple: orient, act, verify, then continue. -**Alex:** The workflow is almost identical to applying a label. When you are looking at an issue, you navigate to the right sidebar. You press the number 3 or the letter H to jump to the Milestone heading. Right after that heading is the Milestone gear button. You activate it, use your arrow keys to select the correct milestone from the dropdown, and press Escape. +**Jamie:** Give me the version that sounds like an instructor, not a manual. -**Jamie:** I am guessing there is a command line equivalent for this too? +**Alex:** Start with 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:** There is. You can use g h space issue space edit space forty two space dash dash milestone, followed by the milestone name in quotes. But there is a small catch with milestones and the C L I. While you can easily assign issues to a milestone using the C L I, there is no native command to create a brand new milestone from scratch. For that, you either need to use the web interface, or use the g h api command to make a direct web request, which is a bit more advanced. +**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:** Good to know. So let us talk about creating a new milestone through the web interface. I know this has a specific accessibility quirk we need to discuss. +**Alex:** Hold that next to this. Here is the plain-English version of The Files Table. See also: Appendix B: Screen Reader Cheat Sheet lists the keyboard shortcuts for navigating repository file trees. Put another way, the files table is the core of the Code tab - it shows every file and folder in the repo. -**Alex:** Yes, it does. To create a milestone, you navigate to the Milestones page, tab to the New Milestone button, and activate it. You fill in the title and the description just like a label. But then you reach the Due Date field. +--- -**Jamie:** And date pickers on the web are notoriously frustrating with screen readers. Half the time, the calendar pop up traps your keyboard focus, or it does not announce the days of the week correctly. +**Jamie:** Turn that into a path someone can follow. -**Alex:** Exactly. GitHub provides a calendar widget, but my strong recommendation is to ignore it completely. The due date field is a standard text input field. The most reliable, accessible way to set the date is to simply type it out in the standard format. Type the four digit year, a dash, the two digit month, a dash, and the two digit day. So, 2024 dash 10 dash 31. It works perfectly every time, and you never have to fight with the calendar widget. Tab to the Create milestone button, press Enter, and you are done. +**Alex:** This is where Reaching the files table becomes real: 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. That matters in practice: It's visible immediately below the branch selector. +**Alex:** That shows up in the workshop in a few specific ways. 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. -**Jamie:** Alright, we have covered labels for categorization, and milestones for grouping things by a deadline. But both of those tools still just leave you with lists of issues. What if I want a bird's eye view of everything happening in my organization? What if I want to see who is working on what, what is in progress, and what is finished, all on one screen? +**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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Alex:** For that, you need GitHub Projects. GitHub Projects is a fully featured, built in project management tool. If you have ever used tools like Jira, or Trello, or Asana, GitHub Projects is built to do exactly that, but it lives right next to your code. +**Alex:** That connects to another useful point. Keep the learner anchored in 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. This is the part to say slowly: For example: "docs/ Add accessibility guide 3 days ago". A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor. -**Jamie:** And it is important to note that we are talking about Projects version 2 here. If you are reading older documentation, you might see references to classic projects. But the current version of Projects is incredibly powerful because a single project board can pull in issues and pull requests from multiple different repositories at the same time. +**Jamie:** Where do you want a learner to place their attention here? -**Alex:** That cross repository tracking is huge. Imagine you maintain five different open source repositories. Instead of checking five different issue tabs every morning, you can create one organization level Project. You can set it up so that any issue created in any of those five repositories, if it has the bug label, automatically gets added to your central Project. It acts like a giant control tower for your whole ecosystem. +**Alex:** Start with Folder vs file. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** That sounds amazing. But how do we actually read a project board with a screen reader? Because when I hear the word board, I think of a highly visual layout with cards scattered everywhere. +**Alex:** The parts worth keeping in working memory are these. 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:** That is a very valid concern. GitHub Projects supports three different layouts, and you can switch between them depending on what works best for you. The layouts are Table, Board, and Roadmap. Let us break them down one by one, starting with the Table view. +--- -**Jamie:** Table view is my absolute favorite. It basically turns your project into a giant spreadsheet. Each row is an issue or a pull request. And the columns are the data fields, like Title, Status, Assignee, Priority, and so on. +**Alex:** Here is the practical turn. Start with Learning Cards: The Files Table. There is something to understand, something to try, and something that proves the try worked. -**Alex:** The Table view is highly optimized for keyboard navigation. When you load a project in Table view, you can press the letter T to jump your focus straight into the data grid. From there, you just use your arrow keys. You can press Control plus Alt plus Down Arrow to move down through the rows, hearing each issue. And you press Control plus Alt plus Right Arrow to move across the columns for that issue. +**Alex:** On the ground, that means a few things. 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:** So as I arrow across a row, my screen reader will say something like, Title: Fix keyboard trap. Column two, Status: In Progress. Column three, Assignee: Jamie. It is completely linear and incredibly fast to read. And if I want to change the status, I just press Space on the status cell, and a dropdown opens right there. +**Jamie:** If I am listening before the workshop starts, what should settle in my mind first? -**Alex:** Exactly. It is essentially a fully accessible spreadsheet. Now, the second layout is the Board view. This is what people typically call a Kanban board. It organizes work into columns based on status. Usually, you have a To Do column, an In Progress column, and a Done column. +**Alex:** Here is the plain-English version of The Branch Selector. The branch selector button sits just above the files table. Put another way, it lets you switch which branch you are viewing. -**Jamie:** This is where sighted users usually drag and drop cards from one column to another using their mouse. Obviously, drag and drop is not a great experience with a screen reader. So how do we move a card from To Do to In Progress? +**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:** GitHub has made this very straightforward. You do not need to drag and drop anything. Each column is marked as a region, so you can press the letter D, or use your screen reader's region navigation, to jump between To Do, In Progress, and Done. Once you are in a column, you press the number 3 to read the cards. +**Jamie:** Give me the sequence, because order matters here. -**Jamie:** And when I find the card I want to move? +**Alex:** This is where How to open the branch selector becomes real: mouse users see the current branch name as a button with a dropdown arrow (e.g., main ▼) just above the file table. That matters in practice: Type to filter branches, then click a branch name to switch. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed. -**Alex:** You just press Enter on the card. This opens a detail panel on the right side of your screen. Inside that panel, there is a field called Status. You activate the status field, change it from To Do to In Progress, and press Escape. The card instantly moves to the correct column on the board. You are updating the underlying data, and the visual board simply updates to reflect your change. +**Alex:** The room should hear these as checkpoints. 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. -**Jamie:** That is so much easier than trying to simulate a mouse drag. Just open the card, change the word, and close it. Okay, what about the third layout, the Roadmap view? +**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). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Alex:** The Roadmap view is a timeline, often called a Gantt chart. It draws horizontal bars across a calendar to show when work starts and ends. It is heavily visual and is mostly used by project managers to plan capacity over months or quarters. +**Jamie:** Let's pause on How to open the branch selector. What should a learner take away from it? -**Jamie:** To be honest, I rarely use the Roadmap view. Because all three views are just different ways of looking at the exact same data, I find it much easier to just switch back to the Table view. If I want to know the start and end dates of an issue, I just read the date columns in the table. +**Alex:** First, 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. -**Alex:** That is exactly the right approach. Treat the Roadmap as a visual summary for stakeholders, but use the Table view to actually read and edit your project data. +--- +**Jamie:** Let's pause on Inside the branch dropdown. What should a learner take away from it? -**Jamie:** So, how do I actually get my issues into this project? We talked about automation earlier, but what if I just want to add one specific issue manually? +**Alex:** Keep the learner anchored in 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. This is the part to say slowly: VoiceOver: After activating the button, VO+Down to interact with the dropdown → VO+Right to navigate items. -**Alex:** You have two ways to do this. The first is from the issue itself. Just like labels and milestones, there is a Projects heading in the right sidebar of every issue. You press H to find it, activate the gear button, and select your project from the list. +**Jamie:** Let's pause on Switching to a tag. What should a learner take away from it? -**Jamie:** And the second way? +**Alex:** The reason Switching to a tag matters is that tags mark specific releases or versions. That gives the learner a simple foothold: the branch dropdown also provides tag navigation. -**Alex:** The second way is from inside the project board itself. At the bottom of the table or column, there is an Add Item button. If you activate it, a text field appears. You just type the pound sign, also known as the hash symbol, followed by a keyword from your issue title, or the issue number. A search dropdown appears, you select your issue, and it drops right into the project. +**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. The rhythm is simple: orient, act, verify, then continue. -**Jamie:** I want to pause here and talk about how all three of these things, labels, milestones, and projects, fit together. Because when I first learned this, it felt like redundant work. Why do I need a milestone if I have a project board? +**Jamie:** Before we leave Switching to a tag, what is the practical point? -**Alex:** That is a great question, and it is the key to mastering GitHub organization. They are not redundant; they are complementary. Think of it like a sentence. Labels are the adjectives. They describe what the work is. It is an accessibility bug. Milestones are the deadlines. They describe when the work must be finished. It is due by the end of the hackathon. Projects are the map. They describe where the work currently is in the process. It is in progress, and assigned to Jamie. +**Alex:** First, navigate with ↑/↓ and press Enter to select a tag. Think of it as a rail line: each stop confirms you are still on the right route before the next one. -**Jamie:** Oh, that is a great way to put it. And when you combine them, you can create incredibly powerful views. In my project board, I can create a filter that says, only show me issues where the label is accessibility, and the milestone is Hackathon Day 1. Suddenly, a chaotic repository becomes a highly focused to do list. +**Jamie:** Let's pause on Cloning a Repository. What should a learner take away from it? -**Alex:** Exactly. And this is going to become critically important when we start talking about AI and Accessibility Agents later in the workshop. These labels and milestones are the exact language that automated workflows use to route work. If you do not apply labels properly, the automated agents will not know how to prioritize your issues. Labeling is not just overhead; it is how you program the project management system. +**Alex:** Start with Cloning a Repository: Cloning copies the repository to your local machine so you can work with it in VS Code or the terminal. The next useful detail is this: 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one. -**Jamie:** This has been incredibly helpful. I feel like I finally have a mental model for how large open source projects actually function without collapsing into chaos. +**Jamie:** Before we leave Cloning a Repository, what is the practical point? -**Alex:** It really is the secret to scaling collaboration. Let us recap the main takeaways from today's episode. First, labels are text based tags that categorize your issues. You apply them from the right sidebar of an issue, and you can use them in the filter bar to instantly narrow down your view. +**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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. -**Jamie:** Second, milestones group issues together toward a shared deadline. The safest way to set a milestone due date with a screen reader is to ignore the calendar pop up and simply type the date in year, month, day format. +**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. -**Alex:** Third, GitHub Projects act as a central hub, pulling issues from multiple repositories into one view. You can navigate them seamlessly using the Table view, jumping to the grid with the letter T and moving through the data with Control plus Alt plus your arrow keys. +--- -**Jamie:** And finally, do not try to drag and drop cards in a board view. Just press Enter to open the issue, change the status field in the sidebar, and let the board update itself. +**Jamie:** How do you keep commands from becoming magic words? -**Alex:** Perfectly summarized. Now that you know how to organize work, you are going to want to know when people interact with that work. In our next episode, we are tackling one of the most requested topics: GitHub Notifications. We will show you how to tame your inbox, filter the noise, and ensure you never miss a mention. +**Alex:** Here is the plain-English version of Or with standard Git. Setup: Install the GitHub CLI from cli.github.com and authenticate with gh auth login. It 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:** I cannot wait for that one. My inbox is currently a disaster zone. Thank you all for listening, and we will catch you in the next episode of Gitt Going with GitHub. +**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. -### Episode 10: Notifications and Mentions +**Alex:** For a learner, the useful signals are these. 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. -Managing your notification inbox, @mentions, and strategies for avoiding overload. +**Jamie:** Let's pause on Tool Cards: Clone a Repository. What should a learner take away from it? -Based on: [Chapter 10: Notifications and Mentions](docs/10-notifications-and-day-1-close.md) +**Alex:** Keep the learner anchored in Tool Cards: Clone a Repository. github.dev (web editor): No clone needed. This is the part to say slowly: 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. -[Download Episode 10 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep10-notifications.mp3) +**Jamie:** Before we leave Tool Cards: Clone a Repository, what is the practical point? -
-Read Transcript - Episode 10: Notifications and Mentions +**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. The rhythm is simple: orient, act, verify, then continue. -#### Transcript +**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. -**Alex:** Welcome to Gitt Going with GitHub. This is episode ten, Notifications and Mentions. I am Alex, and I am here to help you navigate the social and collaborative side of open source without getting completely overwhelmed by the noise. +--- -**Jamie:** And I am Jamie. I am a blind developer who is still figuring out how to keep my digital life organized. I have to admit, Alex, the title of this episode gives me a little bit of anxiety. Notifications. Just the word makes me think of my phone buzzing non stop and an inbox with ten thousand unread messages. +**Jamie:** Let's pause on Fork vs. Clone vs. Branch - What Is the Difference? What should a learner take away from it? -**Alex:** That is a completely normal reaction, Jamie. In episode five, we talked about working with issues and commenting. Then in episode six, we covered pull requests and reviews. You have been putting your work out there, asking questions, and proposing changes. Now, the community is talking back. And when people talk back, GitHub generates notifications. +**Alex:** The reason Fork vs. Clone vs. Branch - What Is the Difference? matters is that these three concepts are related but serve different purposes. That gives the learner a simple foothold: students often confuse them, so here is a side-by-side comparison. -**Jamie:** It feels like a big transition. Going from being the person initiating the action, to being the person receiving all these updates. When I first started using GitHub about two years ago, I had this moment where I suddenly started receiving hundreds of emails a day from a repository I had visited only once. I thought I broke something. +**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:** You definitely did not break anything, but you did encounter one of the most common right of passage moments for new GitHub users. You probably accidentally subscribed to a very busy project. Today, we are going to make sure that never happens again. We are going to cover how GitHub generates notifications, the difference between participating and watching, how to manage your notification inbox, and how to use mentions to get someone else's attention. +**Alex:** Keep the thread going. 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:** Here is what that changes in practice. 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. -**Alex:** Let us start with the core concept. How does GitHub decide to send you a notification in the first place? It all comes down to two concepts, participating and watching. +**Jamie:** Let's pause on Watching, Starring, and Forking. What should a learner take away from it? -**Jamie:** Participating makes sense to me. If I am part of a conversation, I should probably know when someone replies. +**Alex:** Here is the plain-English version of Watching, Starring, and Forking. These three actions let you follow, bookmark, or copy a repository. -**Alex:** Exactly. You are participating in a thread if you opened the issue or pull request, if you commented on it, or if someone explicitly assigned it to you. You are also participating if someone mentions your username directly. When you are participating, GitHub assumes you want to know how the story ends, so it subscribes you to that specific thread. +--- -**Jamie:** So what is an analogy for that? Is participating like being on a group text message? +**Jamie:** Let's pause on Watching (subscribe to notifications). What should a learner take away from it? -**Alex:** That is a perfect analogy. If you are on the group text, your phone is going to buzz when someone replies. But watching is completely different. Watching a repository is like installing a baby monitor in every room of a giant office building and piping the audio directly into your headphones. +**Alex:** This is where Watching (subscribe to notifications) becomes real: the Watch, Star, and Fork buttons are at the top-right of the repository page, just below the global navigation bar. That matters in practice: Click Watch to open a dropdown of subscription options: Participating and @mentions, All Activity, or Ignore. -**Jamie:** Oh wow. That sounds exhausting. +**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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Alex:** It really is, if you do it to the wrong repository. When you watch a repository, you are telling GitHub that you want to receive a notification for every single thing that happens in that project. Every new issue, every comment, every pull request, every automated test failure. For your own personal projects, watching is great. But for a massive open source project like Microsoft VS Code or the NVDA screen reader, watching means you will get thousands of notifications a week. +**Jamie:** Before we leave Watching (subscribe to notifications), what is the practical point? -**Jamie:** That is exactly what happened to me! I thought I was bookmarking a repository so I could find it later. I navigated to the top of the repository page, found a button, and activated it. The next morning, my email inbox was completely destroyed. +**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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. -**Alex:** I am so glad you brought that up, because new contributors constantly confuse watching with starring. They are two buttons located right next to each other at the top of every repository page. Let us clear up the difference right now. Starring a repository is what you actually wanted to do. Starring is like a public bookmark or a high five to the maintainers. It adds the project to a list on your profile, and it tells the creators that you like their work. Starring generates zero notifications. +**Jamie:** Let's pause on Forking (create your own copy). What should a learner take away from it? -**Jamie:** Zero notifications. That is beautiful. I wish I had known that. +**Alex:** Keep the learner anchored in Forking (create your own copy). Click the Fork button (top-right, next to Watch and Star). This is the part to say slowly: A page opens asking you to choose the owner and repository name for your fork. -**Alex:** Right. Starring is for bookmarking. Watching is for subscribing. By default, when you interact with a repository, your watch settings are set to participating and mentions. That is the sweet spot. It means you only hear about the things that actually involve you. +**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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. -**Jamie:** But what if I do want to change my watch settings? Say I join a small team and I actually do need to know everything that happens in our team repository. +**Jamie:** Before we leave Forking (create your own copy), what is the practical point? -**Alex:** You can easily change your watch level. Navigate to the main page of the repository. If you are using NVDA or JAWS on Windows, you can press B to navigate through the buttons until you find the Watch button. Press Enter to open it. It is actually a drop down menu. Then use your up and down arrow keys to navigate the subscription options. +**Alex:** First, tab to "Create fork" and press Enter. The rhythm is simple: orient, act, verify, then continue. -**Jamie:** And if I am using VoiceOver on a Mac? +**Jamie:** Let's pause on Starring (bookmarking). What should a learner take away from it? -**Alex:** With VoiceOver, you can use quick nav B to find the Watch button, then press VO plus Space to open the menu, use your arrow keys to find your preferred level, and press VO plus Space again to select it. The options you will hear are Participating and mentions, All Activity, Ignore, and Custom. +**Alex:** The reason Starring (bookmarking) matters is that the button changes to Starred with a filled star icon to confirm. That gives the learner a simple foothold: 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 interface gets friendlier when it stops being a wall of controls and starts being a set of named places. -**Jamie:** Ignore sounds pretty intense. +**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. The rhythm is simple: orient, act, verify, then continue. -**Alex:** Ignore is very useful if you are part of a massive organization and you are automatically subscribed to repositories you have nothing to do with. It completely mutes that repository. Custom is also great because it lets you get granular. You can say, only notify me when a new release is published, but ignore all the day to day issue comments. +--- +**Jamie:** Let's pause on Viewing a Single File. What should a learner take away from it? -**Jamie:** Okay, so we have covered how to control the fire hose of information. Let us talk about how we actually get someone else's attention. You mentioned that being mentioned makes you a participant. How does that work? +**Alex:** Start with 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:** Mentions are how you tap someone on the shoulder in a crowded room. Anytime you are typing a comment in an issue, a pull request, or a discussion, you can type the at symbol followed by a person's GitHub username. For example, at Jamie blind dev. When you submit that comment, GitHub immediately sends a notification to that user, and it automatically subscribes them to that thread so they will see future replies. +**Alex:** Before the learner moves on. Here is the plain-English version of Reading a Markdown file (like README.md). The README renders with full heading structure. -**Jamie:** I love the shoulder tap analogy. It is literally requesting someone's specific attention. I use this a lot when I am stuck on a problem and I know exactly which developer wrote the code I am struggling with. I will drop a comment and mention them to ask for their input. +**Alex:** These are the details that keep the idea from floating away. H - navigate headings within the README. T - find any tables. L - find lists. K - navigate links. -**Alex:** That is exactly what it is for. But there is a point of etiquette here. You should only tap someone on the shoulder if you actually need them. Tapping the lead maintainer of a huge project just to say hello or to ask them to look at your unrelated bug is generally frowned upon. Use mentions intentionally. +**Jamie:** Let's pause on Reading a code file. What should a learner take away from it? -**Jamie:** That makes sense. What about when I need help from a group, but I do not know exactly who to ask? Like, I know the accessibility team needs to review my pull request, but I do not know the individual names of the people on that team. +**Alex:** This is where Reading a code file becomes real: code files render as a table where each row is one line of code. -**Alex:** That is where team mentions come in. It is a fantastic feature. Instead of mentioning a person, you can mention a whole team. The syntax is the at symbol, followed by the organization name, a forward slash, and the team name. So, at community dash access forward slash accessibility dash agents. +--- -**Jamie:** Oh, that is clever. It is like using the public address system to page a specific department instead of paging one specific doctor. +**Alex:** This is where the talk moves from concept to action. Keep the learner anchored in The file action buttons. Above the file content, there are buttons. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor. -**Alex:** Exactly. When you mention a team, GitHub sends a notification to everyone who is a member of that team. It is the best way to request a review from a specialized group without having to memorize everyone's individual usernames. +**Alex:** A few details make that real. 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? -**Jamie:** Alright, so people are mentioning me, they are requesting my review, my automated continuous integration tests are failing and sending me alerts. Where does all this information go? Earlier I mentioned my email inbox getting destroyed. Is email the only way to manage this? +**Alex:** The reason How to reach these buttons matters is that press B from within the file area, OR use D to navigate to the "Repository files navigation" landmark. -**Alex:** Email is one way, but it is rarely the best way. The problem with email is that GitHub notifications get mixed in with your bank statements, your newsletters, and messages from your family. It is too easy to lose context. The best way to handle this is the dedicated GitHub notification inbox. +**Jamie:** Let's pause on Editing a file. What should a learner take away from it? -**Jamie:** A dedicated inbox just for GitHub? Where do I find that? +**Alex:** Start with 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:** You can navigate to github dot com forward slash notifications. But there is a much faster way. GitHub has a global keyboard shortcut for this. From almost anywhere on the GitHub website, you can press G then N. +**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. Think of it as a rail line: each stop confirms you are still on the right route before the next one. -**Jamie:** Let me clarify that for our screen reader users. When you say G then N, do you mean pressing them at the same time, like a chord? +**Jamie:** Before we leave Editing a file, what is the practical point? -**Alex:** Great question. No, it is a sequential shortcut. You press the letter G, release it, and then press the letter N. It stands for Go to Notifications. Just make sure you are in browse mode or reading mode, not focus mode, so your screen reader passes the keystrokes through to the browser. +**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). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. -**Jamie:** Okay, so I press G then N, and I arrive at the notification inbox. What is the layout of this page? I always find it helpful to understand the structure before I start arrowing around. +--- -**Alex:** Structurally, the page has three main areas. On the far left, there is a sidebar with filters. In the center, taking up most of the page, is the notification list itself. And on the far right, there is a detail pane that shows a preview of whatever notification you have selected. Though, a quick tip, many screen reader users prefer to disable that right preview pane in their settings because it can make navigation a bit cluttered. +**Jamie:** Let's pause on Learning Cards: Viewing a Single File. What should a learner take away from it? -**Jamie:** I definitely turned that preview pane off. I prefer just a clean list. How do you recommend navigating the list itself? +**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 center list is grouped by date. So you will have a heading for Today, a heading for Yesterday, a heading for This Week, and so on. If you are using NVDA or JAWS, you can press the letter H to jump between these date headings. If you are using VoiceOver, make sure quick nav is on and press H. +**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. -**Jamie:** And once I am under a heading, like Today, how do I read the actual notifications? +**Alex:** Another way to ground it. This is where The Blame View becomes real: blame shows you who changed each line of a file, in what commit, and when. That matters in practice: It is useful for tracing why a particular change was made. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed. -**Alex:** This is a really important detail. Do not use your standard up and down arrow keys to read the list. The list is actually a complex interactive widget. The most reliable way to navigate it is to press the Tab key to move from one notification row to the next. +**Jamie:** Let's pause on Navigating Blame. What should a learner take away from it? -**Jamie:** What exactly does the screen reader announce when I tab to a notification row? +**Alex:** Start with Navigating Blame. There is something to understand, something to try, and something that proves the try worked. -**Alex:** GitHub has done a lot of work to make this announcement comprehensive. When your focus lands on a row, you will hear four distinct pieces of information. First, the repository name. Second, the title of the issue or pull request. Third, the event type, which tells you why you received the notification, like review requested or mention. And fourth, the timestamp. +**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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. -**Jamie:** So it might say something like, microsoft forward slash vscode, Add keyboard shortcut for accessible view, Jamie blind dev mentioned you, two hours ago. +--- -**Alex:** Spot on. That single announcement gives you all the context you need to decide what to do next. And if you want to open that notification to read the full thread, you just press Enter. It will take you directly to the issue or pull request page, and it will automatically scroll your focus down to the exact comment that triggered the notification. +**Alex:** This is the part worth saying out loud. 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:** Okay, so I tab to a notification, I hear what it is. Now I have to make a decision. This is where I struggle. I read it, but then it just sits in my inbox forever. How do I actually clear things out? +**Jamie:** What should they understand before typing anything? -**Alex:** This brings us to inbox actions and keyboard shortcuts. The GitHub inbox is designed for rapid triage. You want to process these notifications like you process physical mail at your front door. You either throw it in the recycling, you file it away, or you open it immediately because it is urgent. +**Alex:** Start with Reading the Commits List Page. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** I love that analogy. I am definitely a pile it on the kitchen counter kind of person, which explains my inbox. What are the shortcuts for processing the mail? +**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:** Once your focus is on a notification row, you have several single key shortcuts available. The most important one is the letter E. Pressing E marks the notification as done. It archives it and removes it from your inbox view. +**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. -**Jamie:** E for done. That is easy to remember. What if I want to keep it in my inbox, but I want to remember that I have already looked at it? +**Alex:** The practical takeaway is this. The commit message (heading). Author and date. Parent commit link. A diff for every file changed. -**Alex:** You can mark it as read without opening it by pressing Shift plus I. If you want to mark something as unread so it stays bold and catches your attention later, press Shift plus U. +--- -**Jamie:** What if it is something really important that I need to work on tomorrow? Is there a way to pin it or save it? +**Jamie:** Let's pause on Searching for a File. What should a learner take away from it? -**Alex:** Yes. Press the letter S to save it for later. This moves it to a special Saved filter in your sidebar, so it does not clutter your main inbox but it is securely filed away for when you have time. +**Alex:** This is where Searching for a File becomes real: the "Go to file" shortcut is extremely useful when you know what you are looking for. -**Jamie:** Okay, those are great. E for done, Shift plus I for read, S for save. But what about the opposite scenario? What if I am participating in a thread, maybe I left a tiny comment a month ago, and now two other developers are arguing back and forth with fifty comments a day. My inbox is filling up with their argument. How do I escape? +**Jamie:** Let's pause on How to use Go to File. What should a learner take away from it? -**Alex:** You need to mute the thread. This is a crucial survival skill. If you are focused on a notification row and you realize the conversation is no longer relevant to you, press the letter M. M stands for mute. It is the equivalent of silently leaving the group chat. You will not receive any more notifications for that specific issue or pull request, unless someone mentions your username directly. +**Alex:** Keep the learner anchored in How to use Go to File. GitHub keyboard shortcut: T - opens the Go to File dialog. This is the part to say slowly: Screen reader conflict warning: T normally means "next table" in NVDA/JAWS Browse Mode. -**Jamie:** That is a lifesaver. M for mute. I am going to use that constantly. But what if I have already opened the issue? Do I have to go back to the inbox to mute it? +**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:** No, you can unsubscribe right from the issue page. Navigate to the right sidebar, find the section called Notifications, and activate the Unsubscribe button. It does the exact same thing as pressing M in the inbox. +**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. It is 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: Searching for a File. What should a learner take away from it? -**Jamie:** Let us talk about strategy. You mentioned earlier that some people have thousands of notifications. How do you personally manage your inbox without spending your entire day organizing 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:** I am a big believer in the mark all as done workflow. When I come back from a long weekend, or if I just let things pile up, I do not process them one by one. I navigate to the top of the inbox, I find the filter field, and I type in the names of the repositories I care about the most. +**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:** Wait, there is a search filter for the inbox? +--- -**Alex:** Yes. At the top of the notification list, there is a text input field. You can navigate to it quickly by pressing the letter F for find, or E for edit, depending on your screen reader. You switch to focus mode, and you just type a repository name or an organization name. The list filters in real time to show only those notifications. +**Alex:** Keep the teaching thread moving. Start with GitHub Shortcuts for Repository Navigation - Spotlight: These are the GitHub built-in shortcuts you will use most on repository pages. The next useful detail is this: They work by sending keystrokes directly to GitHub's JavaScript, so enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need. -**Jamie:** Oh, that is incredibly powerful. So you filter for the important stuff first. +**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. -**Alex:** Exactly. I filter for my primary project. I read those, I reply to those, I press E to mark them done. Once I have handled the high priority items, I clear the filter by pressing Escape. Then, I tab to the button that says Mark all as done, and I press Enter. +**Jamie:** Let's pause on Navigating the sidebar. What should a learner take away from it? -**Jamie:** You just wipe out the rest of the inbox? Just like that? +**Alex:** Here is the plain-English version of Navigating the sidebar. The sidebar content is inside the "Main" landmark, after the files table and README. Put another way, after the README, press H or 2 to reach "About" and the sidebar section headings. -**Alex:** Just like that. It clears everything. If I missed something truly critical, someone will mention me again. But realistically, most notifications are just conversational noise. If you try to read every single one, you will never get any actual coding done. +**Jamie:** Let's pause on The Repository About Section. What should a learner take away from it? -**Jamie:** That is incredibly liberating to hear from an experienced maintainer. It is okay to just let things go. +**Alex:** This is where The Repository About Section becomes real: quick way to check the project description, website link, and topics. -**Alex:** It is mandatory to let things go. You have to protect your focus. And speaking of protecting your focus, let us talk about the left sidebar filters. You can press the letter K to navigate through links, or just Tab to the sidebar. You will find filters like Unread, Saved, and Done. But the most powerful filters are Mentioned, Assigned, and Review requested. +**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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Jamie:** I can see why those are powerful. Those are the items that represent actual work waiting for me. +--- -**Alex:** Exactly. If your inbox is overflowing, just activate the Review requested filter. That instantly narrows your view to only the pull requests where a teammate is literally blocked waiting for your approval. It cuts through all the noise. +**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. -**Jamie:** We talked earlier about email notifications. I still get emails along with my web notifications. It feels redundant. Should I turn one of them off? +**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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. -**Alex:** I strongly recommend turning off email notifications for everything except maybe direct mentions or administrative alerts. Having both is a recipe for anxiety. To fix this, you need to configure your account settings. Navigate to github dot com forward slash settings forward slash notifications. +**Jamie:** Let's pause on Scenario B: "I want to find a good file to edit". What should a learner take away from it? -**Jamie:** What am I looking for on that settings page? +**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:** It is a long page, but it is well structured with headings. You can press H to jump from section to section. Look for the section called Email delivery. There, you can uncheck the boxes that send notifications to your email. I prefer to do all my triage in the web inbox because the keyboard shortcuts we just talked about make it so much faster than managing email. +**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. The rhythm is simple: orient, act, verify, then continue. -**Jamie:** I am going to make that change as soon as we finish recording. What about the GitHub command line interface? In the last few episodes, we talked about how great the G H CLI is for creating issues and pull requests. Can I manage my notifications from the terminal? +**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:** You can, but it serves a slightly different purpose. The web interface is best for rapid triage and achieving inbox zero. The command line is best for targeted queries. For example, you can open your terminal and type g h search p r s dash dash review dash requested at me dash dash state open. +**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. -**Jamie:** That is a long command. Let me break that down. G h search p r s, means search pull requests. Dash dash review dash requested at me, filters for ones waiting on me. And dash dash state open, means only show me ones that are not closed yet. +**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. Think of it as a rail line: each stop confirms you are still on the right route before the next one. -**Alex:** Exactly. That command will output a clean text list in your terminal of exactly what you need to review. You can also run g h issue list dash dash assignee at me, to see all issues assigned to you. So, while the CLI does not have a fully featured inbox management tool for muting and archiving, it is fantastic for quickly finding out what your action items are without ever opening a web browser. +--- -**Jamie:** That is really good to know. I like the idea of starting my morning in the terminal, running those two commands, and knowing exactly what my priorities are for the day, without getting distracted by a hundred other notifications in the web inbox. +**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:** That is a very professional workflow. It puts you in control of the information, rather than letting the information control you. +**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). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. -**Jamie:** Alright, we have covered a massive amount of ground today. This feels like the missing manual I needed two years ago. Let us recap the biggest takeaways for everyone listening. +**Jamie:** Let's pause on Scenario E: "I want to contribute - where do I start?". What should a learner take away from it? -**Alex:** First, understand the difference between watching and starring. Starring is a bookmark. Watching is a subscription. If you are overwhelmed with noise, check to make sure you have not accidentally watched a busy repository. You generally want your watch setting to be participating and mentions. +**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. -**Jamie:** Second, use the dedicated web inbox at github dot com forward slash notifications. The sequential keyboard shortcut is G then N. Do not rely on email. The web inbox gives you powerful filtering and triage tools. +**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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. -**Alex:** Third, navigate the inbox list using the Tab key, not your reading arrows. Listen to the comprehensive announcement for each row, which includes the repository, title, event type, and timestamp. +**Jamie:** Let's pause on Try It: The Five-Tab Tour. What should a learner take away from it? -**Jamie:** Fourth, learn the single key shortcuts. E marks a notification as done and gets it out of your way. M mutes a noisy thread so you stop hearing about it. And S saves it for later. +**Alex:** Keep the learner anchored in Try It: The Five-Tab Tour. Time: 3 minutes What you need: Browser with screen reader, signed in to GitHub. This is the part to say slowly: Navigate to the Accessibility Agents repository and do this. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor. -**Alex:** And finally, do not be afraid to use the mark all as done button. Your attention is your most valuable resource. Protect it ruthlessly. Filter for the things that matter, like review requests and direct mentions, and let the rest go. +**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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. -**Jamie:** This has been incredibly helpful. I feel like I finally have a strategy to tame the beast. What is next on our journey? +**Jamie:** Before we leave Try It: The Five-Tab Tour, what is the practical point? -**Alex:** This episode concludes the first major phase of our workshop. You now know how to navigate repositories, work with issues, review pull requests, and manage your communications. Next time, we are moving into the day two agenda, where things get really exciting. We are going to introduce GitHub Copilot, and we will talk about agentic workflows, where artificial intelligence can actually help you summarize those notifications and manage your project. +**Alex:** First, read the README - Press 1 to find the page title, then 2 to scan sections. The rhythm is simple: orient, act, verify, then continue. -**Jamie:** Oh, I cannot wait for that. Having an AI assistant read my notifications sounds like a dream come true. +--- -**Alex:** It is a game changer, but it relies entirely on the manual discipline we learned today. An agent can only summarize effectively if you have your watch settings configured correctly. So, practice taming your inbox today, and we will see you in the next episode. Thanks for listening to Gitt Going with 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 3. Next in the series is episode 4, where we keep building the same contributor muscles. -## Day 2: VS Code and Accessibility Agents + -### Episode 11: VS Code Setup and Accessibility +--- -Screen reader mode, Command Palette, sidebar navigation, and accessibility settings. +### 8. Episode 4: The Learning Room + +Your shared practice environment: challenges, PR workflow, bot feedback, peer review. -Based on: [Chapter 5: VS Code Setup and Accessibility](docs/11-vscode-interface.md) +Based on: [Chapter 4: The Learning Room](docs/04-the-learning-room.md) -[Download Episode 11 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep11-vscode-basics.mp3) +[Download Episode 4 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep04-the-learning-room.mp3)
-Read Transcript - Episode 11: VS Code Setup and Accessibility +Read Transcript - Episode 4: The Learning Room #### Transcript -**Alex:** Welcome to episode eleven of Gitt Going with GitHub. I am Alex, your lead host for this series, and today we are tackling a massive and exciting topic. We are talking about setting up Visual Studio Code for accessibility. +**Alex:** Welcome to Git Going with GitHub, episode 4: The Learning Room. I am Alex. Today we are going to make The Learning Room something you can explain, practice, and recover from when the interface surprises you. -**Jamie:** And I am Jamie. I have to admit, I am really looking forward to this one, but I also remember how overwhelming this exact topic was for me about two years ago. We spent episode one of this series making sure you all had Visual Studio Code and Git installed, which was a great first step. But actually opening the editor and figuring out how to make it talk nicely with a screen reader felt like a whole new mountain to climb. +**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:** That is a completely normal feeling. Moving from reading code on a website to actually writing and managing code in a professional editor is a big transition. When something might feel intimidating today, I want you to remember that you have already done most of this on day one of your learning journey. You already understand the workflow. Today, we are just learning how to let Visual Studio Code handle the heavy lifting. +--- -**Jamie:** OK, that sounds like a good mindset to have. So, let us start at the very beginning. What exactly is Visual Studio Code? I hear developers just call it VS Code all the time. +**Alex:** The big idea today: Your shared practice environment: challenges, PR workflow, bot feedback, peer review. 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:** Yes, we will refer to it as VS Code from here on out. VS Code is a free, extensible code editor built by Microsoft. +**Jamie:** So the episode should work even if someone has not read the chapter yet. -**Jamie:** Let us break that down. What do you mean by an extensible code editor? How is a code editor different from something like Microsoft Word? +**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:** That is a great question. A word processor like Microsoft Word is designed for rich text. It cares about fonts, bold text, page margins, and printing. A code editor is designed purely for plain text, but it is highly optimized for programming. It understands the structure of code, it can catch errors as you type, and it integrates directly with tools like Git. +--- -**Jamie:** And what about that word, extensible? +**Jamie:** Okay, set the room for us. What are we walking into? -**Alex:** Extensible means you can add new features to it. I like to think of VS Code as a heavy duty workshop bench. Out of the box, it is just a really solid table. But because it is extensible, you can bring your own tools and bolt them onto the bench. You can install tools for Python, tools for spell checking, or tools for GitHub Copilot. You customize the bench to fit exactly what you need to build. +**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. -**Jamie:** I love that analogy. You build your own perfect workspace. But before we talk about the desktop app that everyone installed in episode one, I want to talk about a really cool trick I learned. The browser version. +**Alex:** The next layer is 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. It 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:** Ah, yes. The github dot dev experience. This is one of the most powerful features GitHub offers, and it requires zero installation. +**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:** I remember the first time someone told me how to use this. They told me to open any repository on GitHub and just press the period key. I thought they were joking. +**Jamie:** What is the one idea that makes the next few steps less mysterious? -**Alex:** It sounds like a magic trick, but it is real. If you are navigating any GitHub repository in your browser, and you press the period key, just the dot on your keyboard, the webpage will instantly transform. The URL changes from github dot com to github dot dev, and suddenly, you are sitting inside a fully functional version of VS Code, running entirely in your browser. +**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:** It is so fast. To use your workshop analogy, if the desktop app is your main heavy duty workbench in your garage, the github dot dev browser experience is like a pop up shop version of your workbench. You can access it from anywhere, on any computer, without installing a single thing. +--- -**Alex:** Exactly. It uses the exact same keyboard shortcuts as the desktop version, and it has the exact same screen reader mode. It is the perfect bridge between browsing GitHub on the web and doing deep development work on your machine. +**Jamie:** Turn that into a path someone can follow. -**Jamie:** Are there things the browser version cannot do? Why even bother with the desktop app if the browser version is so good? +**Alex:** Start with 1. Open the assignment link. There is something to understand, something to try, and something that proves the try worked. -**Alex:** The browser version does have limitations. Because it runs in your web browser, it does not have an integrated terminal. You cannot run command line scripts. It also does not support GitHub Copilot or running local accessibility agents. For those heavy duty tasks, you need the desktop application. But for quick edits, fixing a typo in documentation, or reviewing a pull request, pressing the period key is the fastest way to get to work. +**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:** What is the ordered workflow? -**Alex:** Now, whether you are using the browser version or the desktop app, the very first thing you need to do is turn on screen reader mode. VS Code is built using web technologies, which means it behaves a lot like a complex web application. By default, it presents a lot of visual information that can be incredibly noisy or confusing for a screen reader. +**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. -**Jamie:** How do we fix that? How do we make it accessible? +**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:** You activate screen reader mode by pressing Shift plus Alt plus F1. If you are on a Mac, you will press Shift plus Option plus F1. +**Alex:** The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work. -**Jamie:** What actually happens when I press Shift plus Alt plus F1? +**Jamie:** Give me the sequence, because order matters here. -**Alex:** It is like turning the lights on for your screen reader. When you enable this mode, VS Code changes how focus moves around the application. It suppresses a lot of the visual decorations that cause extra noise. Most importantly, it enables live regions for code suggestions and errors. +**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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need. -**Jamie:** Can you define live region for anyone who might be new to that term? +**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. -**Alex:** Certainly. A live region is an invisible area of the application that can send spoken announcements to your screen reader, even if your keyboard focus is somewhere else. So, if you are typing code, and VS Code finds an error, the live region will announce the error to you immediately, without you having to navigate away from the line you are typing on. +--- -**Jamie:** That is incredibly helpful. OK, that sounds like a lot of steps to remember every time I open the app. +**Jamie:** How would you walk the room through that step by step? -**Alex:** It does! But here is the thing, you really only have to configure this once. To make sure it stays on permanently, you should update a specific setting. You will want to navigate to your settings and search for the phrase editor dot accessibility support. You want to set this to the word on, rather than leaving it on auto. +**Alex:** Start with 4. Open your new repository. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** Why force it to on? Does the auto setting not work? +**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:** Auto usually works if you are on Windows using NVDA or JAWS. VS Code will try to detect your screen reader and turn the mode on automatically. But sometimes, especially if you start your screen reader after opening the editor, it might miss the detection. Forcing editor dot accessibility support to on guarantees that all those screen reader announcements and optimizations are always active. +**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:** What does the learner do first, second, and then after that? -**Jamie:** OK, so our screen reader is happy and talking to us properly. How do we actually do things in VS Code? There are so many menus and buttons. It can feel like being dropped into the cockpit of an airplane. +**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. -**Alex:** The secret to VS Code is that you do not need to memorize the menus. You only need to memorize one keyboard shortcut. Control plus Shift plus P. +**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. -**Jamie:** Ah, the Command Palette. I call this the magical concierge. +**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 is the perfect name for it. When you press Control plus Shift plus P, a text input field opens at the top of the window. This is the Command Palette. Every single action, setting, and feature in VS Code can be triggered by typing its name into this box. +**Jamie:** Where do you want a learner to place their attention here? -**Jamie:** It is like going to a restaurant where you do not need to read the menu. You just walk up to the chef and say, I would like to format this document, or I would like to open my settings, and the chef just does it for you. +**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:** Exactly. If you want to change your color theme, you press Control plus Shift plus P, type the word theme, and press enter. If you want to toggle word wrap, you press Control plus Shift plus P, type word wrap, and press enter. You never have to dig through complex dropdown menus. +--- -**Jamie:** And what if I want to learn the actual keyboard shortcuts for the area of the editor I am currently working in? Is there a quick way to get help without leaving the app? +**Alex:** Before the learner moves on. The reason Workshop Recommendation (Chapter 4) matters is that chapter 4 is a system orientation chapter. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places. -**Alex:** Yes, and this is an essential tool for screen reader users. It is the accessibility help dialog. You can open it by pressing Control plus Shift plus H. +**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:** What exactly does it tell you? +**Jamie:** Let's pause on Readiness Checkpoint. What should a learner take away from it? -**Alex:** The accessibility help dialog is context aware. That means if your focus is currently inside the text editor, and you press Control plus Shift plus H, a plain text document pops up. It will read out exactly how to navigate the text editor, which shortcuts move you between errors, and how to trigger suggestions. +**Alex:** Start with Readiness Checkpoint: Before starting Chapter 5 challenges, you should be able to. -**Jamie:** Oh, that is clever! So if I move my focus to the terminal and press Control plus Shift plus H, it gives me different instructions? +**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:** Precisely. It will give you the specific accessibility commands for the terminal. It is your built in manual for wherever you happen to be standing at that exact moment. Use it as your first action whenever you land somewhere new in VS Code. +**Alex:** Hold that next to this. 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. +--- -**Alex:** Speaking of landing somewhere new, let us talk about the layout of VS Code and how to navigate between its different areas. The interface is divided into a few main regions. The Sidebar, the Editor, the Terminal, and the Panels. +**Jamie:** If I am listening before the workshop starts, what should settle in my mind first? -**Jamie:** I like to think of these as the rooms of a house. You do different tasks in different rooms, and you need to know how to walk between them. +**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:** Let us start with the Sidebar. On the far edge of the window is a vertical strip called the Activity Bar. The Activity Bar contains the main views of the application. The most important ones are the Explorer, the Search view, the Source Control view, and the Extensions view. +**Alex:** That shows up in the workshop in a few specific ways. Introduction to GitHub - Create branch, open PR, merge. Communicate Using Markdown - Write headings, links, code, tables. Review Pull Requests - Comment, approve, suggest changes. -**Jamie:** Can we talk about the Explorer first? Because I remember being really confused about the difference between opening a file and opening a folder. +**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 is a very common stumbling block. The Explorer is your file tree. It shows you all the files in your project. But how you open your project matters. If you go to the file menu and select Open File, VS Code will open just that single document. The Explorer will be empty. +**Alex:** That connects to another useful point. 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. -**Jamie:** Right, and my analogy for this is a filing cabinet. Opening a file is like taking a single piece of paper out of the filing cabinet and putting it on your desk. You can read it and write on it, but you cannot see any of the other papers that were next to it. +**Alex:** For a learner, the useful signals 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). -**Alex:** Exactly. But if you choose Open Folder instead, it is like bringing the entire filing cabinet to your desk. The Explorer will populate with every file and subfolder inside that project. This is how you should always work in VS Code. You open the root folder of your repository, so you have access to everything at once. +**Jamie:** Can you translate that into plain choices? -**Jamie:** So if I want to jump over to the Explorer to find a file, what is the shortcut? +**Alex:** Start with How the Two Tracks Compare. There is something to understand, something to try, and something that proves the try worked. -**Alex:** You press Control plus Shift plus E. That moves your focus to the Explorer. You can use your up and down arrows to navigate through your files, and press Enter to open one. +**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:** And when I press Enter, the file opens in the Editor room. How do I move my focus back and forth between the Explorer and the Editor? +--- -**Alex:** To jump into your active Editor, you press Control plus 1. That puts your cursor directly into the text of the file you are working on. To go back to the Explorer, you press Control plus Shift plus E again. You will be doing this dance constantly. Control plus 1 for the editor, Control plus Shift plus E for the Explorer. +**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. -**Jamie:** What about the other views in the Activity Bar? You mentioned Search and Source Control. +**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. -**Alex:** Search allows you to find text across every file in your entire folder. You can navigate to it by pressing Control plus Shift plus F. Source Control is where you stage and commit your changes to Git. You can reach that by pressing Control plus Shift plus G. +**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 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. -**Jamie:** Earlier, you mentioned the Extensions view. You said VS Code is extensible, like bringing your own tools to a workbench. How do we actually install these tools? +**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:** You will open the Extensions view by pressing Control plus Shift plus X. This moves your focus into a search box. You simply type the name of the extension you want, for example, Python, or GitHub Pull Requests. Then you press the Tab key to navigate to the search results, use your arrow keys to find the exact match, and press Enter to install it. +**Alex:** Keep the thread going. 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed. -**Jamie:** I wish I had known that when I started. It is so much faster than trying to use a mouse to find the little install buttons. Now, what about the terminal? You mentioned earlier that the browser version does not have one, but the desktop version does. +**Alex:** These are the details that keep the idea from floating away. 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:** Yes, the integrated terminal. If the editor is where you write your code, the terminal is the engine room. It is where you type direct text commands to your computer's operating system, completely bypassing the graphical interface. You use it to run Git commands, install software packages, or start local web servers. +--- -**Jamie:** How do we open the engine room? +**Jamie:** Give me the version that sounds like an instructor, not a manual. -**Alex:** You press Control plus Backtick. +**Alex:** Start with Why you create a separate branch. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** OK, let us pause for a second. What is a backtick? I spent an embarrassingly long time looking for this key. +**Alex:** A few details make that real. 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:** The backtick key is usually located in the top left corner of your keyboard, right above the Tab key, and just to the left of the number one. It shares a key with the tilde symbol. Pressing Control plus Backtick will instantly open the integrated terminal panel at the bottom of your window and move your focus into it. Pressing Control plus Backtick a second time will hide the terminal and return your focus to the editor. +**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 to use your branch. What should a learner take away from it? -**Jamie:** Let us talk about something really fun. Audio cues. I think this is one of the best accessibility features Microsoft has ever added to an application. +**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. -**Alex:** I completely agree. VS Code has a system called accessibility signals. These are distinct audio cues, little chimes and sounds, that communicate the state of the editor without requiring your screen reader to speak a single word. +**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. -**Jamie:** It is so much like the dashboard sounds in a car. You do not need to take your eyes off the road to look at the dashboard to know your turn signal is on, because you can hear the rhythmic clicking. Audio cues do the exact same thing for coding. +**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. -**Alex:** A perfect example is the error signal. If you have the setting called accessibility dot signals dot line has error turned on, VS Code will play a distinct, slightly lower pitched tone whenever your cursor moves onto a line of code that contains a mistake. +**Jamie:** Let's pause on Learning Cards: Your Practice Branch. What should a learner take away from it? -**Jamie:** It is amazing because it does not interrupt your screen reader's speech. You hear your screen reader read the text of the line, and layered right underneath it, you hear the little error tone. You immediately know something is wrong before you even finish reading the line. +**Alex:** Start with Learning Cards: Your Practice Branch. There is something to understand, something to try, and something that proves the try worked. -**Alex:** There are audio cues for everything. There is a cue for when a terminal command finishes successfully, a cue for when a terminal command fails, and cues for when you are navigating through changes in your code. You can configure all of these by opening your settings and searching for accessibility signals. +**Alex:** The parts worth keeping in working memory are these. 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:** Speaking of navigating through changes, I want to ask about the Accessible Diff Viewer. This is a concept that took me a while to wrap my head around. First, what exactly is a diff? +**Jamie:** Let's pause on Tool Cards: Switch to Your Practice Branch. What should a learner take away from it? -**Alex:** A diff is short for difference. So a pull request, and I love that name because you are literally requesting that someone pull your changes into their project, a pull request is essentially just a big diff. It is a representation of exactly what lines of code you added, and what lines of code you removed. +**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. -**Jamie:** Right. And visually, a diff is usually displayed side by side. You have the old file on the left side of the screen with the removed lines highlighted in red, and the new file on the right side with the added lines highlighted in green. +**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. -**Alex:** Which is an absolute nightmare to navigate with a screen reader. A spatial, color coded layout does not translate well to linear speech. +**Jamie:** Before we leave Tool Cards: Switch to Your Practice Branch, what is the practical point? -**Jamie:** It really does not. So how do we read a diff effectively? +**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. -**Alex:** This is where the Accessible Diff Viewer comes in. When you have a diff open in your editor, instead of trying to read the visual side by side layout, you open the Command Palette with Control plus Shift plus P. Then, you type Open Accessible Diff Viewer and press enter. +**Jamie:** Let's pause on The Practice Files: What You Will Work On. What should a learner take away from it? -**Jamie:** What does that view actually look like to the screen reader? +**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:** It completely transforms the presentation. It turns the diff into a single, vertical list. It is like having a redline document read aloud to you line by line. As you use your up and down arrows, it will announce the change type before reading the code. It will say, Line added, followed by the text. Or it will say, Line removed, followed by the text. Or it will say, Unchanged, to give you the surrounding context. +**Alex:** Now bring the learner back to the room. 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. -**Jamie:** That is a game changer. You get the complete picture of what changed, in reading order, without having to scan visually. +--- +**Jamie:** Let's pause on [TODO] 1 - "Who Can Contribute?" section. What should a learner take away from it? -**Alex:** Before we wrap up, there is one last piece of housekeeping regarding keyboard navigation. Sometimes, a built in VS Code shortcut might conflict with a screen reader command. For instance, NVDA or JAWS might intercept a keystroke before it ever reaches the editor. +**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.]. -**Jamie:** That used to drive me crazy. What is the fix for that? Do you just have to live without that command? +**Alex:** That matters because of the next idea. 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? Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need. -**Alex:** Not at all. VS Code allows for total keyboard shortcut customization. If a shortcut does not work for you, you can change it. You just open the Command Palette with Control plus Shift plus P, type Open Keyboard Shortcuts, and press enter. You can search for the command you want to change, press enter on it, and then simply type your new preferred key combination. +**Jamie:** Let's pause on [TODO] 3 - "After Your Contribution Is Merged" section. What should a learner take away from it? -**Jamie:** I love that. The editor really bends to fit your workflow, not the other way around. +**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:** Exactly. Let us summarize our key takeaways for today. First, remember the period key trick. Pressing period on any GitHub repository opens the github dot dev browser experience for fast, lightweight editing. +--- -**Jamie:** Second, always turn on screen reader mode by pressing Shift plus Alt plus F1, and make sure your editor dot accessibility support setting is forced to on. +**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. -**Alex:** Third, the Command Palette is your best friend. Press Control plus Shift plus P to find any command without digging through menus. And remember Control plus Shift plus H to open the accessibility help dialog for context aware shortcut lists. +**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:** Fourth, always open a folder, not a file, so you have access to your entire project in the Explorer. +**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:** And finally, when reviewing changes, use the Command Palette to open the Accessible Diff Viewer for a clean, line by line reading experience. +**Jamie:** What does someone need before they touch the keyboard? -**Jamie:** This has been incredibly helpful. I feel like my workbench is finally set up and my tools are organized. What are we building next? +**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:** In our next episode, we are going to take everything we just learned about the interface and apply it to version control. We will be covering Git and Source Control directly inside VS Code. We will learn how to stage, commit, and push our code without ever leaving the editor. Thank you for listening to Gitt Going with GitHub, and we will catch you in the next episode. +**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:** Another way to ground it. 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places. +--- -### Episode 12: Git and Source Control in VS Code +**Jamie:** What should the learner prove to themselves after each small task? -Cloning, branching, staging, committing, pushing, and pulling from VS Code. +**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. -Based on: [Chapter 11: Git and Source Control in VS Code](docs/14-git-in-practice.md) +**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. -[Download Episode 12 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep12-git-source-control.mp3) +**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. -
-Read Transcript - Episode 12: Git and Source Control in VS Code +**Jamie:** Before we leave Student A (working on Challenge 3: Complete Welcome Guide), what is the practical point? -#### Transcript +**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 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:** Welcome to Gitt Going with GitHub. This is episode 12, Git and Source Control in VS Code. I am Alex, and I am here with Jamie. +**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:** Hello everyone! I am really excited for this one. I feel like we have been building up to this moment for the entire series. +--- -**Alex:** We absolutely have. In episode 3, we talked about the big concepts of Git, like repositories, branches, and commits. Then in episode 11, we got our VS Code environment set up, learned how to use the Command Palette, and got comfortable navigating the sidebar. Today, we are bringing those two worlds together. We are going to learn how to actually do Git operations right inside VS Code. +**Jamie:** Let's pause on Step 3: Peer Review (Facilitator-Arranged). What should a learner take away from it? -**Jamie:** And I want to say right up front to anyone listening, if this feels like a lot of steps, that is completely normal. I remember learning GitHub about two years ago, and I was terrified I was going to push the wrong button and delete someone else's code. But the beauty of Git is that it is actually really hard to permanently break things. And doing it in VS Code makes the heavy lifting so much easier. +**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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor. -**Alex:** That is a great point, Jamie. We are going to normalize that feeling of intimidation today. Because honestly, the workflow we are going to cover is the exact same workflow you will use whether it is your first day on a project or your tenth year as a senior developer. +**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:** Let us start at the very beginning. To work on a project, you need a copy of it on your computer. In Git terminology, this is called cloning a repository. +**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:** I remember when I first started coding, before I knew Git, I would just go to a website, download a ZIP file of the code, and extract it to a folder. How is cloning different from just downloading a ZIP file? +**Jamie:** Let's pause on Visibility. What should a learner take away from it? -**Alex:** That is the perfect question. When you download a ZIP file, you are just getting the files exactly as they exist at that exact second. It is a snapshot. But when you clone a repository, you are downloading the files plus the entire hidden history of the project. You get every commit, every branch, and most importantly, a permanent connection back to the original repository on GitHub. +**Alex:** Start with Visibility. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** So it is like the difference between taking a photo of a document, versus having a live shared document where you can see all the version history. +**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:** Exactly. Now, there are a few different ways to clone a repository. The most accessible way, and the one we recommend for screen reader users, is using the VS Code Command Palette. +**Jamie:** Let's pause on Your assigned peer reviewer (when one is paired with you). What should a learner take away from it? -**Jamie:** Right, we talked about the Command Palette in the last episode. That is Control plus Shift plus P on Windows, or Command plus Shift plus P on a Mac. +**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:** Correct. When you open the Command Palette, you just type the words Git Clone. You will hear your screen reader announce Git: Clone as an option. You press Enter, and VS Code will ask you for the repository URL. You paste in the web address of the GitHub repository, press Enter again, and VS Code will open a standard file dialog asking where you want to save the folder on your computer. +**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.". -**Jamie:** That sounds pretty straightforward. Navigate to the folder you want, press Enter, and it downloads everything. But I have also heard people talk about doing this in the terminal. Like using the words git clone or gh repo clone. What is the difference there? +**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. -**Alex:** Those are the command line alternatives. The standard Git command line interface, or CLI, uses the command git clone followed by the URL. That does the exact same thing as VS Code, it just does it in the terminal. Then there is the GitHub CLI, which is a separate tool you can install. Its command is gh repo clone. The neat thing about the GitHub CLI is that it already knows you are talking to GitHub. So instead of pasting a massive URL, you just type gh repo clone followed by the owner name, a slash, and the repository name. Like gh repo clone community-access slash learning-room. +--- -**Jamie:** Oh, that is clever! It saves you from having to copy and paste full web addresses. But for today, we will stick to the VS Code Command Palette method. So, I have cloned the repository. I have the files on my computer. Before I start typing and changing code, I feel like I need a mental model of how Git tracks these files. +**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. -**Alex:** You absolutely do. Understanding the mental model is the secret to never getting lost in Git. There are three main areas you need to understand: the working tree, the staging area, and the repository. +**Jamie:** Let's pause on You (PR author). What should a learner take away from it? -**Jamie:** Okay, hit me with an analogy. I need a way to picture this. +**Alex:** Start with You (PR author). There is something to understand, something to try, and something that proves the try worked. -**Alex:** Let us use a mailroom or a shipping department. Imagine you are putting together a care package for a friend. +**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:** I love care packages. +**Jamie:** Before we leave You (PR author), what is the practical point? -**Alex:** Right. So, the room you are standing in, with tables and shelves and items scattered everywhere, that is your working tree. The working tree is just the actual files on your computer right now. You can pick things up, change them, break them, or create new things. +**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:** So when I open a file in VS Code and type a new paragraph, I am messing around in the working tree. +**Jamie:** What is the teaching move inside Visibility? -**Alex:** Exactly. Now, eventually, you want to send some of these items to your friend. But you do not just throw the whole room into a truck. You get a shipping box. You take specific items from your workbench and you place them into the box. That box is the staging area. You are preparing a specific set of changes to be grouped together. +**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:** And I can add things to the box, or take things out of the box, before I tape it shut. +--- -**Alex:** Precisely. The staging area is where you build your next commit. Finally, when the box is perfectly packed, you tape it shut, stick a label on it describing what is inside, and put it on the outbound truck. Taping the box shut is creating a commit, and the truck takes it to the warehouse. That warehouse is the repository. The repository is the permanent, safe archive of all your sealed boxes. +**Alex:** This is the part worth saying out loud. 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. -**Jamie:** That makes so much sense. Working tree is the messy room. Staging area is the open box. Repository is the warehouse of sealed boxes. And I assume files can have different states depending on where they are in this process? +**Alex:** The practical takeaway is this. You merge the PR (button becomes available). PR closes, shows "merged". -**Alex:** Yes. Git tracks files in three distinct states. First is untracked. This is a brand new file you just created. Git says, I have never seen this before, I am not tracking it. It is like a brand new item you just bought that is not on your inventory list yet. +**Jamie:** What makes this practice feel low-stakes but still real? -**Jamie:** Okay. Untracked means brand new. +**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:** Second is modified. This means Git knows about the file, but you have changed it in your working tree, and you have not put it in the shipping box yet. +**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:** Modified means changed, but still on the workbench. +**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:** And third is staged. This means you have moved that modified or untracked file into the staging area. It is in the box, ready to be committed. +**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:** Untracked, modified, staged. I wish I had known that when I started. It makes the error messages make so much more sense when Git complains about modified files. So, how do we actually see these states in VS Code? +--- +**Jamie:** Let's pause on Learning Cards: How PR Sharing Works. What should a learner take away from it? -**Alex:** This brings us to the most important interface for Git in VS Code, which is the Source Control view. It lives in the Activity Bar on the far left of the screen, but you do not need to hunt for it. You just use the keyboard shortcut Control plus Shift plus G. That is G for Git. If you are on a Mac, it is Command plus Shift plus G. +**Alex:** Start with Learning Cards: How PR Sharing Works. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** Control plus Shift plus G. I am pressing it now. What happens? +**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:** A side panel opens up, and your screen reader focus usually lands right in the middle of it. Let us break down the structure of this panel from top to bottom. At the very top is the Source Control title bar. This is actually super helpful because it announces the name of the branch you are currently on, like main or feature slash add-documentation. +**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. -**Jamie:** That is a nice quick way to check where you are without having to use the terminal. What is below the title bar? +**Jamie:** Let's pause on Type 1: Automated Bot Feedback (30 seconds). What should a learner take away from it? -**Alex:** Below that is a multi-line text input field. Your screen reader will call it Source Control Input. This is where you will eventually type your commit message, which is the label for your shipping box. +**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. -**Jamie:** Okay, so the text box is waiting for me. And below the text box? +**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:** Below the text box is the really magical part. It is a specialized tree view that lists your files. But it does not list all the files in your project. It only lists the files that have changed. It is divided into two collapsible sections. The bottom section is called Changes. This is your working tree. It shows all your modified and untracked files. +--- -**Jamie:** So if I fix a typo in the readme file, the readme file will show up under Changes. +**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:** Exactly. And the section right above Changes is called Staged Changes. This is your shipping box. When you first open the panel, Staged Changes might be completely empty or even hidden, because you have not put anything in the box yet. +**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:** How do I navigate this tree view with a screen reader? Is it just like a normal file explorer? +**Jamie:** Let's pause on Type 3: Progress Tracking (on merge). What should a learner take away from it? -**Alex:** It is similar, but it has some special behaviors. For NVDA and JAWS users, you use your Up and Down arrow keys to move through the lists. When you land on a section header like Changes, your screen reader will say Changes, expanded, or Changes, collapsed. You can use your Right arrow to expand a section, and your Left arrow to collapse it. +**Alex:** Here is the plain-English version of Type 3: Progress Tracking (on merge). Together: Instant technical feedback + human mentorship + visible progress. -**Jamie:** And when I arrow down onto an actual file, what does it say? +**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:** It will read the file name, the folder path, and the state. So it might say, index dot HTML, Modified. Or, styles dot CSS, Untracked. +**Jamie:** Let's pause on Study Groups (Optional). What should a learner take away from it? -**Jamie:** Okay, that sounds very efficient. I do not have to guess what I changed today, VS Code just gives me a tidy list of my messy workbench. Before we start moving things into the staging box, though, we should probably talk about branches. Because I know I am not supposed to do my messy work on the main branch. +**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. +**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. -**Alex:** That is a fantastic point. Whenever you want to make a change, whether it is fixing a bug or writing a new feature, you should create a new branch. A branch is basically an isolated copy of the code where you can experiment safely. +--- -**Jamie:** Creating branches from the terminal always made me nervous. How do we do it in VS Code? +**Jamie:** How should someone choose between those options? -**Alex:** It is incredibly easy. We go back to our trusty Command Palette. Control plus Shift plus P. You type the words Create Branch. You will hear Git: Create Branch. Press Enter. +**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. -**Jamie:** And then it asks for a name? +**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:** Yes, a text input appears. You type your branch name. A quick tip on naming conventions: use lowercase letters and hyphens instead of spaces. So you might type, feature hyphen update hyphen readme. Then you press Enter. +**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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places. -**Jamie:** And that is it? Does it switch me to that branch automatically? +**Jamie:** Let's pause on Finding PRs to Review. What should a learner take away from it? -**Alex:** It does. VS Code creates the branch and immediately checks it out, which is Git terminology for switching to it. Your working files stay exactly as they were, but now Git knows that any new commits you make will be saved to this new branch, leaving the main branch perfectly safe and untouched. +**Alex:** Start with Finding PRs to Review: Screen reader users (VoiceOver - macOS). -**Jamie:** That takes so much anxiety out of the process. What if I need to switch back to the main branch to check something? +**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:** Command Palette again. Control plus Shift plus P. This time, type Checkout. You will select Git: Checkout to. A list of all your branches will appear. You just use your Up and Down arrows to find main, and press Enter. +**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:** So I can bounce back and forth between branches just by searching for them. I love that. Okay, so I am on my new branch. I have made some changes to my files. I press Control plus Shift plus G to open the Source Control panel. I arrow down to the Changes section, and I hear that three of my files are modified. It is time to pack the shipping box. How do I stage a file? +--- +**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). -**Alex:** Staging is very satisfying in VS Code. When you are navigating the Source Control panel and your screen reader focus is on a specific file under the Changes list, you have a couple of options. The fastest way is to just press the Spacebar, or press Control plus Enter. For Mac users, that is Command plus Enter. +**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:** Wait, just pressing Spacebar moves it into the box? +**Jamie:** Let's pause on Leaving a Review. What should a learner take away from it? -**Alex:** Yes. The file immediately disappears from the Changes list and reappears up in the Staged Changes list. Your screen reader might not announce the move automatically, depending on your verbosity settings, but if you arrow up, you will find it sitting safely in the Staged Changes section. +**Alex:** This is where Leaving a Review becomes real: screen reader users (VoiceOver - macOS). -**Jamie:** What if I change my mind? What if I put it in the box and realize I am not ready to ship it? +**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. -**Alex:** You do the exact reverse. You arrow up into the Staged Changes list, focus on the file, and press Spacebar or Control plus Enter again. It unstages the file. It takes it out of the box and puts it back on the workbench. The file itself does not lose any of your typed changes, it just changes its Git status. +**Jamie:** Before we leave Leaving a Review, what is the practical point? -**Jamie:** That is so forgiving. Now, you mentioned earlier that I had three modified files. What if I want to stage all of them at once? Do I have to press Spacebar on every single one? +**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:** You can, but there is a faster way. If you move your focus to the actual section heading that says Changes, expanded, you can open the context menu. For Windows users, you can press Shift plus F10, or the Application key if your keyboard has one. For Mac users, you can use VoiceOver keys plus Shift plus M. +**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:** The context menu is like right-clicking with the mouse, right? +**Jamie:** Let's pause on Responding to Feedback. What should a learner take away from it? -**Alex:** Exactly. When the context menu opens, you just arrow down to the option that says Stage All Changes, and press Enter. Boom. Everything on your workbench is swept into the shipping box. +**Alex:** Keep the learner anchored in Responding to Feedback. 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. -**Jamie:** Okay, so why wouldn't I just do that every time? Why does Git even have a staging step? Why not just say, hey Git, save everything I just did? +**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. -**Alex:** That is the million dollar question. The reason Git has a staging step is to help you create atomic commits. Let us say you are working on a new feature, writing a bunch of new code. While you are doing that, you notice a really embarrassing spelling mistake in a completely unrelated documentation file. So you fix the typo, and you keep writing your feature. +**Jamie:** Before we leave Responding to Feedback, what is the practical point? -**Jamie:** I do that all the time. I get distracted by typos. +**Alex:** First, comment: "Updates pushed, ready for review". The rhythm is simple: orient, act, verify, then continue. -**Alex:** Right! Now, at the end of the day, you have a bunch of changed files. If you just saved everything at once, your project history would have one giant commit that says, Added new feature and also fixed a typo. That makes it really hard for other developers to review your work. +**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:** Oh, I see. With the staging area, I can put just the documentation file into the box, seal it up, and call it Typo fix. And then I can put all the feature files into a second box, and call that New feature. +--- -**Alex:** Exactly. You stage individual files to group related changes together. In fact, VS Code even lets you stage individual lines of code within a single file. If you press Enter on a file in the Source Control panel, it opens a diff view showing exactly what lines changed. You can navigate to a specific line, open the context menu with Shift plus F10, and choose Stage Selected Ranges. It is incredibly powerful. +**Jamie:** Let's pause on Learning Cards: Tips for PR Sharing. What should a learner take away from it? -**Jamie:** Okay, that is a total power user move. Staging just a few lines of a file while leaving the rest unstaged. That is amazing. But let us stick to the basics for now. I have staged my files. They are in the Staged Changes list. The box is packed. How do I tape it shut and write the label? +**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:** It is time to commit. In the Source Control panel, you will press Tab or Shift plus Tab until your focus lands in the multi-line text field called Source Control Input. This is where you write your commit message. +**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. -**Jamie:** And writing a good commit message is an art form, isn't it? I know when I first started, my commit messages were literally just the word updates, or fixed stuff, over and over again. +**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. -**Alex:** We have all been there. But in open source, your commit messages are how you communicate with the maintainers. We use a convention called Conventional Commits. The subject line should be short, fifty characters or less, and it follows a specific format. +**Jamie:** Let's pause on "What if I don't agree with my assigned reviewer?". What should a learner take away from it? -**Jamie:** What is the format? +**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:** You start with a type, then a colon, then a space, and then a short summary of what you did in lowercase letters. So for example, if you fixed a bug, you type the word fix, f i x, colon, space, and then something like correct heading hierarchy. +--- -**Jamie:** Fix colon correct heading hierarchy. What if I am adding a new feature? +**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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed. -**Alex:** Then you use the word feat, f e a t. Feat colon add search button. If you are just updating documentation, you use docs, d o c s. Docs colon update screen reader instructions. +**Jamie:** Let's pause on "Can I comment on someone else's PR?". What should a learner take away from it? -**Jamie:** That makes reading the project history so much easier. You can just scan down the list and see exactly what kind of work was done. So, I have typed my message into the input box. How do I actually execute the commit? Do I press Enter? +**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:** If you just press Enter, you will actually just create a new line in the text box, because it is a multi-line input. To actually execute the commit, you press Control plus Enter. Or Command plus Enter on a Mac. +**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. -**Jamie:** Control plus Enter. And what happens when I press it? +--- -**Alex:** The text box clears out. The files disappear from the Staged Changes list. And your screen reader might announce that the commit was successful. You have officially sealed the shipping box. +**Jamie:** Let's pause on "Can I work with a friend?". What should a learner take away from it? -**Jamie:** Success! My code is safe. But wait, where is it safe? Is it on GitHub yet? +**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. It 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:** Ah. This is the most common point of confusion for Git beginners. When you commit, you are only saving that snapshot to your local repository. The warehouse on your computer. GitHub has no idea that you just made a commit. +**Jamie:** Let's pause on "What if bot feedback is wrong?". What should a learner take away from it? -**Jamie:** So if I drop my laptop in a lake right now, that commit is gone forever. +**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:** Unfortunately, yes. To send your commits to GitHub, you have to perform an operation called a push. You are literally pushing your commits up to the remote server. +--- -**Jamie:** Okay, how do I push? +**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. -**Alex:** The easiest way is back in the Command Palette. Control plus Shift plus P. Type Git Push, and select Git: Push. VS Code will contact GitHub and upload your commits. +**Jamie:** Let's pause on Celebration: You're Contributing. What should a learner take away from it? -**Jamie:** What if I get an error? I remember getting an error about no upstream branch when I tried to push my first branch. +**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:** Yes, the dreaded no upstream branch error. This happens because of the relationship between your local branch and the remote tracking branch. Think of your local branch like your personal private journal. You created it on your computer. GitHub does not have a journal with that name yet. +--- -**Jamie:** So when I try to push, Git says, I do not know where to put this on GitHub? +**Jamie:** What should people carry with them after this? -**Alex:** Exactly. When you create a new branch locally and try to push it for the very first time, you have to publish the branch. In the VS Code Command Palette, instead of Git Push, you can select Git: Publish Branch. This tells Git to create a matching branch up on GitHub, and then push your commits to it. From then on, a normal Git Push will work perfectly. +**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:** Git Publish Branch for the first time. Got it. Okay, so pushing is sending my stuff up. What about pulling? I hear people say they need to pull changes. +**Jamie:** That is a better way to say it than just follow the steps. -**Alex:** Pulling is the exact opposite. It is downloading new commits from GitHub into your local repository. Let us say you are collaborating with another developer. They push a new commit to the branch you are both working on. You need to download their work so your local files are up to date. You open the Command Palette, type Git Pull, and select Git: Pull. VS Code downloads their commits and merges them into your working tree. +**Alex:** Right. Steps matter, but understanding wins. That is episode 4. Next in the series is episode 5, where we keep building the same contributor muscles. -**Jamie:** That sounds great, until we both edit the exact same line of code. What happens then? Does my computer explode? +
-**Alex:** No explosions, but you will get what is called a merge conflict. Git is very smart, but it refuses to guess which person's code is the correct one. If you both changed line 42 of the readme file, and you try to pull their changes, Git will stop and say, hey, I have a conflict here. You need to resolve this manually. +--- -**Jamie:** We actually talked about the theory of merge conflicts in episode 6, but in VS Code, how does it handle it? +### 9. Challenge 01: Find Your Way Around -**Alex:** When a conflict happens during a pull, VS Code will show the conflicted files in your Source Control panel under a new section called Merge Changes. If you open one of those files, Git has literally injected both versions of the code into the file, separated by some markers like less-than and greater-than signs. +Repository orientation, headings, tabs, file tree navigation, and confidence in the Learning Room. -**Jamie:** That sounds a bit messy for a screen reader to read through. +Practice focus: Day 1 foundation -**Alex:** It can be. The most accessible way to handle it is to open the file and press F7. F7 jumps you directly to the next conflict in the editor. Then you can press Alt plus F2 to open the Accessible Diff Viewer, which presents both versions very cleanly. You decide which version you want to keep, delete the other version and the markers, save the file, and then stage it just like a normal change. +Audio and transcript are being regenerated for this episode. -**Jamie:** So a conflict is just a file that Git forces you to manually edit and stage again. That is not too scary. I also saw something in our notes about git pull dash dash rebase. What is a rebase? +
+Read Transcript - Challenge 01: Find Your Way Around -**Alex:** Rebase is a slightly more advanced way to pull changes, but it is incredibly useful. Normally, when you pull someone else's changes while you have your own local commits, Git creates an extra merge commit to tie the two histories together. It can make the project history look like a messy subway map with lines crossing everywhere. +#### Transcript -**Jamie:** And rebase prevents that? +**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. -**Alex:** Yes. Think of a rebase like stepping out of line at the grocery store. When you run git pull --rebase in the terminal, Git temporarily un-applies your local commits. It sets them aside. Then it downloads the other person's commits and applies them in a straight line. Finally, it takes your commits and replays them on top of the new history. +**Jamie:** And I am Jamie. I will translate the challenge into the practical questions learners actually have while doing it. -**Jamie:** Oh, wow. So it is like saying, let me pause my work, let you go first, and then I will do my work after you. It keeps the history as one perfectly straight timeline. +--- -**Alex:** Exactly. It is a very elegant way to keep history clean, and many open source projects prefer you to use rebase when pulling updates from the main branch. +**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. -**Jamie:** So we have covered cloning, branching, staging, committing, pushing, and pulling, all using the VS Code interface. Are there other ways to do this? What if I am on a computer that does not have VS Code installed? +**Alex:** Right. A good challenge produces something inspectable: a comment, issue, branch, commit, pull request, review, or clear note about what happened. -**Alex:** There is a fantastic web alternative. You can do almost all of this directly on GitHub dot com. If you navigate to a repository on the GitHub website, you can find any file, open it, and activate the Edit button, which visually looks like a pencil icon. +--- -**Jamie:** And I can just type right there in the browser? +**Jamie:** What makes this practice feel low-stakes but still real? -**Alex:** Yes, it opens a web editor. And here is the interesting difference. On the web, there is no staging step. When you finish editing, you just activate the Commit changes button. GitHub creates the commit directly, either on your current branch or it will automatically create a new branch for you. +**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:** That is super fast for small changes, like fixing a single typo. But I imagine if you are changing five different files, navigating through the web interface for each one gets tedious. +**Jamie:** How would you walk the room through that step by step? -**Alex:** Exactly. The web interface is brilliant for quick single-file edits. But when you are building a complex feature across multiple files, you want the control of VS Code, where you can stage specific files and review everything locally. +**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. -**Jamie:** And for the folks who love the terminal, they can do all of this using the Git CLI, right? +**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:** Absolutely. In VS Code, you can open the integrated terminal by pressing Control plus Backtick. From there, you can type git status to see your modified files, git add dot to stage all changes, git commit dash m to write your message, and git push. Many blind developers actually prefer the terminal because the output is pure plain text, which is very predictable for screen readers. +**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:** That makes sense. It is all about finding the tool that fits your brain. But I have to say, the VS Code Source Control panel with Control plus Shift plus G feels like the perfect middle ground. It organizes the information visually and structurally, but gives you complete keyboard control. +**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. -**Alex:** Let us wrap up with some key takeaways from today's episode. Jamie, what is the first one? +**Jamie:** What is the one idea that makes the next few steps less mysterious? -**Jamie:** Takeaway number one: Understand the three environments. The working tree is your messy workbench. The staging area is the shipping box where you pack specific changes. And the repository is the permanent warehouse of sealed boxes. +**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:** Perfect. Takeaway number two: Use the Source Control panel in VS Code. Press Control plus Shift plus G to open it. It is a dedicated tree view that only shows your modified files, separated into Changes and Staged Changes. +--- -**Jamie:** Takeaway number three: Staging is how you create atomic commits. You do not have to save everything at once. You can focus on a file, press Spacebar to stage it, and commit just that specific fix with a clear message. +**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:** And finally, takeaway number four: Committing only saves locally. Do not forget to push! You have to use Git Push to send your sealed boxes up to GitHub so everyone else can see them. +**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:** This has been incredibly clarifying, Alex. I feel like I am ready to actually contribute code now. But once my code is pushed to a branch on GitHub, how do I actually ask the project maintainers to merge it into the main project? +**Jamie:** What would you say to someone who is already bracing for this to be too much? -**Alex:** That is the final piece of the puzzle. In our next episode, we are going to dive into the GitHub Pull Requests extension. We will learn how to create, review, and merge pull requests without ever leaving VS Code. +**Alex:** Start with Issues tab. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** I cannot wait. Thank you all for listening! +**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:** Thank you for joining us. Keep exploring, keep committing, and we will see you next time on Gitt Going with GitHub. +**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. -### Episode 13: The GitHub Pull Requests Extension +**Alex:** The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work. -Viewing, creating, reviewing, and merging PRs from inside VS Code. +--- -Based on: [Chapter 12: The GitHub Pull Requests Extension](docs/15-code-review.md) +**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. -[Download Episode 13 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep13-github-prs-extension.mp3) +**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. -
-Read Transcript - Episode 13: The GitHub Pull Requests Extension +**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. -#### Transcript +**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:** Welcome to Gitt Going with GitHub. This is episode thirteen: The GitHub Pull Requests Extension. I am Alex, and I am here with Jamie. +**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:** Hi everyone! I am so ready for this episode. We are at the point in the workshop where everything starts coming together. +**Jamie:** Where do you want a learner to place their attention here? -**Alex:** We really are. If you have been following along, in episode six we covered the full pull request lifecycle from the web interface, using GitHub dot com. And in episode twelve, our last episode, we talked about doing local Git operations right inside Visual Studio Code. +**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:** Right, so committing, branching, and pushing without ever leaving the editor. Which was a huge time saver. +--- -**Alex:** Exactly. But what happens when you push that branch and you are ready to open a pull request? Or what if someone asks you to review their code? Up until now, you would have to switch over to your web browser, navigate GitHub dot com, find the pull request, and review it there. +**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:** Which works! We learned how to do that, and it is fully accessible. But switching contexts between your editor and your browser all day can be exhausting. +**Jamie:** Give me the version that sounds like an instructor, not a manual. -**Alex:** It can be. And that brings us to the core concept of today's episode: The GitHub Pull Requests and Issues extension for VS Code. This extension essentially brings the GitHub website directly into your editor. +**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. -**Jamie:** I like to think of it like this. Imagine you are writing a book. Using the web interface for pull requests is like having to drive down to the post office every time you want to mail a chapter to your editor, and then driving back to the post office to pick up their feedback. +**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:** That is a great analogy. +--- -**Jamie:** Right? But installing this extension is like having a direct mail chute installed right at your desk. You write the code, you package it up, and you send it off, all from the exact same chair. You even receive their feedback right on your original manuscript. +**Jamie:** If I am listening before the workshop starts, what should settle in my mind first? -**Alex:** Perfectly said. The extension lets you view, create, review, and merge pull requests without ever pressing Alt plus Tab to open a browser. So, let us talk about how to get it. +**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:** To start using this, you need to install the extension and sign in. +**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:** Okay, walk me through it. I am in VS Code. +**Jamie:** Let's pause on Learning Cards: What Is Always on Every GitHub Page. What should a learner take away from it? -**Alex:** First, open your Extensions sidebar. The keyboard shortcut is Control plus Shift plus X on Windows, or Command plus Shift plus X on Mac. +**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. -**Jamie:** Control plus Shift plus X. Got it. And that puts my focus in a search box, right? +**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:** Yes. Type in the words GitHub Pull Requests. You will hear your screen reader announce the search results. You want to navigate down to the one called GitHub Pull Requests and Issues, published by GitHub. Press Enter to open its detail page, Tab to the Install button, and press Enter again. +--- -**Jamie:** Nice and easy. And since it is connecting to my GitHub account, I assume I need to log in? +**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. -**Alex:** You do. After it installs, VS Code will prompt you with a notification asking to sign in to GitHub. You can navigate to your notifications with Alt plus N on Windows, or Option plus N on Mac. When you activate the Sign In button, it briefly opens your web browser to authorize VS Code, and then sends you right back to the editor. +**Jamie:** Let's pause on Signal 1: The URL. What should a learner take away from it? -**Jamie:** And if I miss the notification, can I just use the Command Palette? +**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:** Absolutely. Just press Control plus Shift plus P, type GitHub Pull Requests Sign In, and press Enter. It does the exact same thing. +**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:** Okay, I am installed and signed in. Where did my pull requests go? How do I find them? +**Jamie:** Let's pause on Signal 3: The first H1 heading. What should a learner take away from it? -**Alex:** The extension adds a brand new section to VS Code. If you are navigating the Activity Bar, it is a new icon that just says GitHub. But the most reliable way to jump straight to it with a screen reader is, as always, the Command Palette. +**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. -**Jamie:** Control plus Shift plus P. +**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. -**Alex:** Exactly. Press Control plus Shift plus P, and type Focus on Pull Requests View. When you press Enter, your focus moves to a new tree view in the sidebar. +**Jamie:** Let's pause on What to expect. What should a learner take away from it? -**Jamie:** A tree view. So that means I am using my Up and Down Arrow keys to move through items, and Right Arrow to expand them. +**Alex:** Start with What to expect. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Spot on. And this tree is organized brilliantly. It is like an email inbox that has already been sorted into folders for you. At the top, you have a section called My Pull Requests. If you expand that, you will find categories like Assigned to Me, Created by Me, and Waiting for my Review. +**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:** Oh, that is incredibly helpful. So if I just want to see the things I am personally responsible for, I can just expand Assigned to Me. +--- -**Alex:** Right. And as you arrow down through the list, your screen reader will announce the PR number, the title, the author, and the status. Something like: Pull Request number 42, Add Timeline Guide, opened by Jeff, 2 days ago. +**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:** That is so much cleaner than tabbing through all the extra links and badges on the web interface. Though I should mention, if you prefer the web, or if you do not have VS Code open, you can still just navigate to the Pull Requests tab on your repository page on GitHub dot com. +**Jamie:** Before we leave What to expect, what is the practical point? -**Alex:** Or use the GitHub Command Line Interface. If you have the gh CLI installed, you can open your terminal and type gh space pr space list. That prints out a beautifully clean text list of all open pull requests right in your console. +**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:** So let us say I find Pull Request number 42 in that tree view, and I want to read it. What happens when I press Enter on it? +--- -**Alex:** When you press Enter on a pull request in the tree, VS Code opens a Pull Request Detail View in your main editor area. This is a fully rendered, highly accessible document. +**Jamie:** What is the teaching move inside What to expect? -**Jamie:** What kind of information is in there? +**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:** Everything you would find on the Conversation tab on the web. It has the title, the description, the CI status checks telling you if the automated tests passed, a list of reviewers, and a section called Files Changed. +**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:** Files Changed. That is the big one. That is where we see the diff, right? The actual code that was added or removed. +**Jamie:** If someone only remembers one thing from What to expect, what should it be? -**Alex:** Exactly. A diff, short for difference, is the before-and-after comparison of the code. Now, you can review the diff simply by navigating to the Files Changed list in that detail view and pressing Enter on any file. It opens a split view or an inline view showing the changes. +**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:** Okay, wait. Reading visual diffs with a screen reader used to be a nightmare for me. Hearing the screen reader try to parse out table columns, jumping between the old file and the new file. It was a lot of cognitive load. +--- -**Alex:** It was. But VS Code has completely solved this with a feature called the Accessible Diff Viewer. This is perhaps the most important keyboard shortcut we will share today. +**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:** I have my notepad ready. +**Jamie:** Let's pause on What to expect on your feed. What should a learner take away from it? -**Alex:** When you have a diff open in the editor, press F7. This jumps your cursor directly to the first chunk of changed code, which is called a hunk. +**Alex:** Start with What to expect on your feed. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** A hunk. I love programmer terminology. +**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:** It gets better. Once your cursor is on that change, press Alt plus F2 on Windows, or Option plus F2 on Mac. This opens the Accessible Diff Viewer. +**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. -**Jamie:** And what does that do? +**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:** It presents the change in a clean, sequential text format that is perfectly optimized for a screen reader. It announces exactly where you are, like Hunk 1 of 3. Then it reads the unchanged context lines, followed by the removed lines prefixed with the word Removed, and then the added lines prefixed with the word Added. +--- -**Jamie:** Oh, that is brilliant. It is like comparing two drafts of a recipe. Instead of making you scan two pieces of paper side-by-side to figure out what changed, the Accessible Diff Viewer just reads it to you clearly: Removed: one cup of sugar. Added: two cups of sugar. +**Jamie:** Let's pause on Learning Cards: The Five Key Page Types. What should a learner take away from it? -**Alex:** Exactly. And when you are done reading that hunk, you press Escape to close the viewer, and press F7 again to jump to the next change. It turns a frustrating visual layout into a logical, readable stream. +**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. -**Jamie:** And if I want to actually run their code to test it out? Can I do that? +**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:** Yes! That is called checking out a pull request. In the PR detail view, there is a Checkout button. When you activate it, VS Code downloads their branch to your local machine and switches your files over to their version. You can run the code, test it with your screen reader, and verify it actually works before you approve it. +**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:** That is a massive advantage over the web interface. On the web, you can read the code, but you cannot easily run it. +**Jamie:** Let's pause on Description. What should a learner take away from it? -**Alex:** Exactly. Though if you are using the terminal, you can achieve the same thing by typing gh space pr space checkout space 42. It pulls down the branch for pull request 42 instantly. +**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:** Okay, so I am reading their code using the Accessible Diff Viewer, and I spot a mistake. They used a heading level two when it should have been a heading level three. How do I tell them? +**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. -**Alex:** You leave an inline comment. This is just like sticking a physical sticky note directly onto a specific line of a manuscript. +**Jamie:** What is the ordered workflow? -**Jamie:** How do I place the sticky note? +**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:** While you are in the diff view, navigate your cursor to the exact line with the mistake. Then, press Shift plus F10 on Windows, or Control plus Return on Mac, to open the context menu. +**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). -**Jamie:** Shift plus F10. Got it. +**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. -**Alex:** Navigate to Add Comment and press Enter. A text input box will appear right there in the editor. You type your feedback, like: This heading should be an H3 to maintain the document outline. +**Jamie:** Give me the sequence, because order matters here. -**Jamie:** And then I just hit submit? +**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:** You have two choices. You can choose Add Single Comment, which posts it to GitHub immediately. Or, you can choose Start Review. +**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. -**Jamie:** What is the difference? +**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. -**Alex:** Starting a review saves your comment as a draft. It lets you go through the rest of the files, leaving more comments as you go, without spamming the author with an email notification for every single typo you find. Once you are done looking at all the files, you submit the review all at once. +--- -**Jamie:** That is polite. I appreciate that. So how do I submit the batch of comments when I am finished? +**Jamie:** Let's pause on 7. Landmark Structure by Page Type. What should a learner take away from it? -**Alex:** Open your Command Palette with Control plus Shift plus P, and type GitHub Pull Requests Finish Review. +**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. -**Jamie:** And that is where I give my final verdict, right? +**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. -**Alex:** Exactly. A prompt will ask you to choose a review type. You can select Comment, which just leaves your feedback without a formal decision. You can select Request Changes, which means the author must fix the issues before the code can be merged. Or, if everything looks great, you select Approve. +**Jamie:** Let's pause on Pull request detail - Files Changed tab. What should a learner take away from it? -**Jamie:** And once I press Enter, all my draft comments and my final verdict are published to GitHub. +**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. -**Alex:** You got it. +--- -**Jamie:** For folks tracking the alternatives, you can do all of this on the web by navigating to the Files Changed tab, finding a line, and activating the Add Comment button. And if you are a terminal fan, you can submit your verdict by typing gh space pr space review, followed by dash dash approve, or dash dash request dash changes. +**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. -**Alex:** So, we have covered reviewing other people's work. Let us flip the script. You have been writing code on a feature branch, you have committed your changes, and you have pushed them to GitHub. How do you create your own pull request from VS Code? +**Jamie:** Let's pause on 9. How GitHub's Layout Changes by Viewport. What should a learner take away from it? -**Jamie:** I am going to guess it involves the Command Palette. +**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:** You know me so well. Press Control plus Shift plus P, and type GitHub Pull Requests Create. Select Create Pull Request, and a form opens right in your editor. +**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. -**Jamie:** What do I need to fill out in this form? +**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:** The most important concepts here are the Base branch and the Compare branch. +--- -**Jamie:** Ah, yes. The terminology can be a little confusing at first. Base and Compare. +**Jamie:** Let's pause on At tablet width (768-1199px). What should a learner take away from it? -**Alex:** Let us use a highway analogy. The Base branch is the main highway. It is the destination. Usually, this is your main branch. The Compare branch is your car on the on-ramp. It is the source of the new changes you want to merge into traffic. +**Alex:** Start with At tablet width (768-1199px). There is something to understand, something to try, and something that proves the try worked. -**Jamie:** That makes perfect sense. So my feature branch is the Compare branch, and I am requesting to merge it into the Base branch, which is main. +**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:** Exactly. VS Code usually selects these for you automatically, but it is good to verify them. After that, you just fill in the Title and the Description. +**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. -**Jamie:** On Day 1 of the workshop, when we opened pull requests on the web, we talked about Pull Request Templates. Those checklists that automatically populate the description box so you remember to test your code. Does VS Code support those? +**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. -**Alex:** It does! If your repository has a template file hidden in the dot github folder, the extension automatically loads it into your description field. You just use your arrow keys to navigate through the Markdown text, fill in the blanks, and put an X inside the brackets for the checkboxes. +**Jamie:** Turn that into a path someone can follow. -**Jamie:** That is fantastic. It is literally the exact same workflow as the web. +**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:** It is. It maps perfectly to what you learned on Day 1. The underlying Git process is identical; you are just interacting with it through VS Code instead of a browser. +**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:** Is there a way to open a Draft PR? Like, if I want to push my code to back it up and get early feedback, but I am not quite ready for a formal review? +--- -**Alex:** Yes, there is a Draft PR checkbox right there in the creation form. If you check that, the PR is marked as a work in progress and cannot be merged until you mark it as ready. Once you have filled everything out, just Tab to the Create button and press Enter. +**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. -**Jamie:** And again, just to map this out for everyone: on the web, you would do this by pushing your code and then clicking the yellow Compare and Pull Request banner. In the CLI, you would just type gh space pr space create. +**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:** Alright, we have reached the final step of the lifecycle. The PR is open, the reviewers have approved it, and the CI checks are green. It is time to merge. +**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. -**Jamie:** The best feeling. How do we merge from VS Code? +**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:** Open the pull request in the PR detail view, scroll down to the bottom, and you will find a Merge Pull Request button. When you press Enter on it, you will be asked to choose a merge type. +**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:** Merge types. This is where people get nervous. We have Merge Commit, Squash and Merge, and Rebase and Merge. Can we break those down? +--- -**Alex:** Absolutely. Let us go back to our traffic analogy. You have a bunch of cars, which are your commits, waiting on the on-ramp, which is your feature branch. A Merge Commit is like a zipper merge. All of your individual cars merge onto the highway one by one, keeping their original identities, and a special sign is put up saying where they merged. It preserves your entire detailed history. +**Jamie:** Let's pause on A Screen Reader Guide to GitHub Repositories. What should a learner take away from it? -**Jamie:** Okay, what about Squash and Merge? +**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:** Squash and Merge is like taking everyone out of their individual cars and putting them all onto a single bus before they get on the highway. +**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. -**Jamie:** Oh, I love that. +**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. -**Alex:** It takes all of your tiny, messy commits, like "fix typo" and "forgot a semicolon", and squashes them into one single, clean commit on the main branch. This is incredibly common for feature branches to keep the project history tidy. +**Jamie:** Let's pause on Safety-First Learning Pattern. What should a learner take away from it? -**Jamie:** And Rebase and Merge? +**Alex:** Start with Safety-First Learning Pattern: Use this sequence before moving to graded chapters. -**Alex:** Rebase is like magically teleporting your cars so they were always on the highway to begin with. It replays your commits one by one at the very tip of the main branch, creating a perfectly straight, linear history without any merge signs. +**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:** Which one should I use? +--- -**Alex:** Always check your project's contributing guidelines. But if you are unsure, Merge Commit is the default and the safest option. Choose your strategy, confirm it, and the PR is merged. +**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:** And then I should probably delete my feature branch, right? Keep the garage clean. +**Jamie:** Let's pause on What Is a Repository Page? What should a learner take away from it? -**Alex:** Exactly. VS Code will usually prompt you, asking if you want to delete the branch. Say yes. Then, use the Command Palette to check out your main branch and do a Git Pull, so your local machine gets the updated, merged code. +**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. -**Jamie:** And to round out our alternatives: on the web, this is the big green Merge button on the conversation tab. In the CLI, it is gh space pr space merge. +**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:** That covers the entire pull request lifecycle, entirely within VS Code. Let us recap our key takeaways. +**Jamie:** Let's pause on Landing on a Repository - What to Expect. What should a learner take away from it? -**Jamie:** Takeaway number one: You do not have to leave your editor to collaborate. The GitHub Pull Requests extension lets you view, review, create, and merge PRs right where you write your code. +**Alex:** The reason Landing on a Repository - What to Expect matters is that when you first navigate to a repo URL. -**Alex:** Takeaway number two: The Accessible Diff Viewer is a game changer for screen reader users. Remember to press F7 to jump to a change, and Alt plus F2, or Option plus F2 on Mac, to read the diff cleanly. +**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:** Takeaway number three: The VS Code workflow maps exactly to the web workflow we learned on Day 1. The concepts of Base and Compare branches, PR templates, and Draft PRs are exactly the same. You are just using a different interface. +**Jamie:** What should happen before anyone copies and runs it? -**Alex:** Perfectly summarized. Now that you are comfortable navigating code and collaborating in VS Code, you are ready for some artificial intelligence assistance. In our next episode, we are going to explore GitHub Copilot, and how it can help explain code, suggest changes, and write documentation. +**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. -**Jamie:** I cannot wait for that one. See you all then! +**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. -**Alex:** Thanks for listening to Gitt Going with GitHub. +**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. +--- -### Episode 14: GitHub Copilot +**Jamie:** Let's pause on How to reach the tabs. What should a learner take away from it? -Inline suggestions, Copilot Chat, prompting strategies, and custom instructions. +**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. -Based on: [Chapter 13: GitHub Copilot](docs/16-github-copilot.md) +**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. -[Download Episode 14 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep14-github-copilot.mp3) +**Jamie:** Let's pause on Reading the tab labels. What should a learner take away from it? -
-Read Transcript - Episode 14: GitHub Copilot +**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.". -#### Transcript +**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:** Welcome to Gitt Going with GitHub, the audio learning series for blind and low-vision developers who are mastering GitHub and open source collaboration. I am your host, Alex, and I am thrilled to be here with you today for episode fourteen, titled GitHub Copilot. Today, we are diving into the world of AI coding assistants. +**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:** Hi everyone, I am Jamie. I am so excited for this one. I keep hearing developers talk about AI and Copilot, but I have been a little hesitant to jump in. I am really hoping we can break down how this actually works with a screen reader. +--- -**Alex:** We absolutely will. Before we get into the new material, let us do a quick recap. In episode eleven, we covered the basics of Visual Studio Code. We talked about how to navigate the interface using your screen reader, how to open the command palette with Control plus Shift plus P, and how to manage your files. You will want to have those basic navigation skills fresh in your mind because Copilot lives right inside VS Code. +**Jamie:** Let's pause on Reaching the files table. What should a learner take away from it? -**Jamie:** I definitely recommend going back to episode eleven if you have not listened to it yet. Getting comfortable with the basic keyboard shortcuts in VS Code makes adding Copilot to the mix much easier. So, Alex, let us start at the very beginning. What exactly is GitHub Copilot? +**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:** At its core, GitHub Copilot is an AI pair programmer. But I like to think of it as a highly caffeinated, very well-read assistant sitting right next to you at your desk. As you type, it tries to guess what you are going to write next and offers suggestions. You can also talk to it conversationally and ask it questions about your project. +**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. -**Jamie:** When you say pair programmer, does that mean I only use this when I am writing code? Because as someone who is still learning, a lot of my open source contributions are actually documentation, writing issue responses, and formatting pull requests. +**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:** That is a fantastic question, and it is a huge misconception. Copilot is brilliant at non-code tasks. In fact, for this workshop, we are going to focus heavily on using Copilot to write Markdown documentation, draft commit messages, and review pull request descriptions. It understands human languages just as well as it understands Python or JavaScript. +**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:** Oh, that is a relief. So how does it actually know what I am trying to do? Does it just read the current line I am on? +**Jamie:** Let's pause on Folder vs file. What should a learner take away from it? -**Alex:** It reads much more than that. Copilot generates its suggestions based on context. Imagine you are cooking in a kitchen. A good sous-chef does not just look at the knife in your hand. They look at the ingredients you have already chopped on the cutting board, they look at the recipe book you have open on the counter, and they look at the pots on the stove. Based on all of that, they hand you the exact spice you need before you even ask for it. +**Alex:** Start with Folder vs file. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** I love that analogy. So Copilot is looking at my whole kitchen. +**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:** Exactly. It looks at the file you are currently editing, where your cursor is positioned, other files you have open in your editor, and even the structure of your project. It gathers all of this context, sends it to the AI model, and returns a suggestion in milliseconds. +--- +**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:** Let us talk about how these suggestions actually appear while you are typing. This is a feature called inline code completions. As you are typing a sentence or a line of code, Copilot will suddenly offer a completion for the rest of the line, or sometimes even an entire paragraph. +**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:** I have heard sighted developers call this ghost text. What does that mean? +**Jamie:** Let's pause on The Branch Selector. What should a learner take away from it? -**Alex:** Yes, ghost text is the industry term for this. For a sighted user, the suggestion appears on their screen as light gray text just ahead of their cursor. It looks like a ghost because it is not actually part of the document yet. It is just a visual preview. But of course, visual previews are not helpful for us. +**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:** Right. So how does my screen reader know the ghost text is there? +**Jamie:** Let's pause on How to open the branch selector. What should a learner take away from it? -**Alex:** VS Code handles this beautifully by using an ARIA live region. When Copilot generates a suggestion, your screen reader will simply announce, suggestion available, or it will read the suggestion out loud, depending on how you have your verbosity settings configured. +**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. -**Jamie:** Okay, so I am typing, I hear suggestion available, and I want to accept it. What do I press? +**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:** You simply press the Tab key. Pressing Tab takes that ghost text and permanently inserts it into your document, moving your cursor to the end of the new text. +**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:** And what if the suggestion is completely wrong? Like, it suggests I write about apples when I am writing about oranges. +**Jamie:** Before we leave How to open the branch selector, what is the practical point? -**Alex:** You just press the Escape key to dismiss it. Or, honestly, you can just keep typing. The moment you type a letter that contradicts the suggestion, Copilot will dismiss it automatically and try to generate a new one based on your new keystrokes. +**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:** That sounds easy enough. Tab to accept, Escape to dismiss. What if it gives me a suggestion, but I wonder if it has any other ideas? Can I ask for a different option? +--- -**Alex:** You can. If you have a suggestion active and you want to see an alternative, you can press Alt plus the right bracket key. That will cycle to the next alternative suggestion. If you want to go back, you press Alt plus the left bracket key. +**Jamie:** Let's pause on Inside the branch dropdown. What should a learner take away from it? -**Jamie:** Okay, that sounds like a lot of steps. I am imagining myself typing, getting interrupted by the screen reader, trying to cycle through options, and losing my train of thought. +**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. -**Alex:** It does sound intimidating! And it is completely normal to feel overwhelmed when your screen reader suddenly starts talking over you while you are trying to think. But here is the thing, you have already done most of this on Day one when we learned basic text editing. This is the exact same workflow, just with VS Code handling the heavy lifting of writing the text. And there are two incredible tricks to make this completely manageable. +**Jamie:** Let's pause on Switching to a tag. What should a learner take away from it? -**Jamie:** Please share the tricks, because I definitely need them. +**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:** The first trick is for when you only want part of the suggestion. Let us say Copilot suggests a whole sentence, but you only agree with the first few words. Instead of pressing Tab to accept the whole thing, you can press Control plus the right arrow key. This accepts the suggestion exactly one word at a time. +**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:** Oh, that is clever! So I can just tap Control plus right arrow three times, take the first three words, and then just resume typing my own thought. +**Jamie:** Before we leave Switching to a tag, what is the practical point? -**Alex:** Exactly. It puts you completely in control. The second trick is even more important, and it solves the biggest current limitation with Copilot and accessibility. +**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:** What limitation is that? +**Jamie:** Let's pause on Cloning a Repository. What should a learner take away from it? -**Alex:** When Copilot generates a long suggestion, it streams the text in piece by piece, or token by token. For a sighted user, this looks like the text is being typed out really fast. But for a screen reader, this streaming effect can cause the live region to update repeatedly. It fragments the announcements. You might hear half a sentence, then an interruption, then the end of the sentence. It can be very noisy and hard to understand. +**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. -**Jamie:** Yes, I have experienced that with other AI tools. It is like someone trying to read you a letter while it is still coming out of the printer. +**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. -**Alex:** That is a perfect description. To solve this, VS Code has a feature called the Accessible View. Whenever you hear that a suggestion is available, do not press Tab yet. Instead, press Alt plus F2. +**Jamie:** Before we leave Cloning a Repository, what is the practical point? -**Jamie:** Alt plus F2. What does that do? +**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:** It pauses the action and opens the complete suggestion in a separate, static text panel called the Accessible View. There is no streaming noise. There are no live region interruptions. It is just plain text. You can use your up and down arrow keys to read the suggestion line by line at your own pace. +**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:** I wish I had known that when I started. So I press Alt plus F2, I read the suggestion in peace, and then what? How do I get it into my document? +--- -**Alex:** While you are still inside the Accessible View, if you decide you like the text, you just press Control plus slash. That immediately inserts the suggestion into your document at your original cursor position and closes the Accessible View. If you do not like the suggestion, you just press Escape to close the view and go back to typing. +**Jamie:** How do you keep commands from becoming magic words? -**Jamie:** That changes everything. Alt plus F2 to read it, Control plus slash to insert it. That feels so much more controlled. +**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. -**Alex:** Now that we have conquered inline suggestions, let us talk about the other half of GitHub Copilot. The Chat interface. +**Jamie:** Let's pause on Learning Cards: Cloning a Repository. What should a learner take away from it? -**Jamie:** This is where I can actually talk to it, right? Like a messaging app? +**Alex:** Start with Learning Cards: Cloning a Repository. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Exactly. You can open the Copilot Chat panel at any time by pressing Control plus Shift plus I. This opens a dedicated view in your sidebar. When you press Control plus Shift plus I, your screen reader will focus an input field. From there, you can ask questions in natural language. +**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:** When you say natural language, do you mean I do not have to write code to talk to it? +**Jamie:** Let's pause on Tool Cards: Clone a Repository. What should a learner take away from it? -**Alex:** Right. You just talk to it like you would talk to a human colleague. You could type, how do I create a pull request using the GitHub command line interface? Or, can you explain what this Markdown file is used for? Then you press Enter to send the message. +**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. -**Jamie:** And does the answer stream in and get all fragmented like the inline suggestions? +**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. -**Alex:** It does stream in, yes. But you can use the exact same trick. As soon as you press Enter to send your question, immediately press Alt plus F2 to open the Accessible View. The response will stream safely into that static view, and you can just use your arrow keys to read it. The Accessible View even formats code blocks and headings properly so your screen reader announces them correctly. +**Jamie:** Before we leave Tool Cards: Clone a Repository, what is the practical point? -**Jamie:** That is so consistent. I love that the same shortcut works in both places. So, what if I want to ask a question about a specific file, or a specific part of VS Code? Does it just know what I am thinking about? +**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:** It is smart, but it cannot read your mind. To help Copilot understand exactly what you are asking about, we use Chat Participants. You can think of these like directing your question to a specific expert department in a massive company. You invoke them by typing the at symbol, followed by the participant name. +**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:** Like tagging someone on social media? +--- -**Alex:** Exactly like that. The three most common ones you will use are at workspace, at terminal, and at vscode. +**Jamie:** Let's pause on Fork vs. Clone vs. Branch - What Is the Difference? What should a learner take away from it? -**Jamie:** Let us break those down. What does at workspace do? +**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:** If you start your chat message with at workspace, Copilot will search across every single file in your current project folder to find the answer. So you could ask, at workspace, where do we document our accessibility guidelines? Copilot will scan the entire repository, find the contributing guide, and summarize the answer for you. +**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. -**Jamie:** That is incredible. It saves me from having to open a dozen files and use the find command. What about at terminal? +**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. -**Alex:** At terminal is a lifesaver when you get an error message on the command line that you do not understand. If you type at terminal, what does this error mean, Copilot will look at the recent text in your VS Code integrated terminal, read the error output, and explain it to you in plain English. +**Jamie:** Let's pause on Watching, Starring, and Forking. What should a learner take away from it? -**Jamie:** Oh, I am definitely going to use that. Command line errors always look like a wall of gibberish to me. And the last one was at vscode? +**Alex:** The reason Watching, Starring, and Forking matters is that these three actions let you follow, bookmark, or copy a repository. -**Alex:** Yes, at vscode. This participant is the expert on the VS Code editor itself. If you forget a keyboard shortcut, or you do not know how to change a setting, you just ask, at vscode, how do I turn on word wrap? It will give you the exact steps and the keyboard shortcuts. +--- -**Jamie:** So participants tell Copilot where to look. Are there ways to tell Copilot what kind of action I want it to take? +**Jamie:** Let's pause on Watching (subscribe to notifications). What should a learner take away from it? -**Alex:** Yes! For that, we use slash commands. If you type a forward slash in the chat input, you invoke a specific command. There are four major ones to memorize: slash explain, slash fix, slash tests, and slash doc. +**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. -**Jamie:** Those sound pretty self-explanatory, but let us go through them. Slash explain? +**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. -**Alex:** If you select a paragraph of complex text, or a dense block of code, and type slash explain, Copilot will break it down and explain how it works step by step. This is amazing when you are reading someone else's pull request and you cannot figure out what their code is doing. +**Jamie:** Before we leave Watching (subscribe to notifications), what is the practical point? -**Jamie:** And slash fix? +**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. -**Alex:** If you select a broken piece of code, or even a Markdown table that is not formatted correctly, you type slash fix. Copilot will analyze the selection, figure out what is wrong, and propose a corrected version that you can accept. +**Jamie:** Let's pause on Forking (create your own copy). What should a learner take away from it? -**Jamie:** That is so much faster than hunting for a missing comma. What about slash tests and slash doc? +**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:** Slash tests will automatically generate unit tests for a function you have selected. And slash doc will automatically write the formal documentation block above a function or class. They are massive time savers for the repetitive parts of software development. +**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? -**Jamie:** Okay, so we have participants like at workspace to set the context, and commands like slash explain to set the action. I feel like I am learning a new syntax. But you said earlier I could just use natural language. Is there a trick to getting good answers when I am just typing regular sentences? +**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. -**Alex:** There is absolutely an art to it. We call it effective prompting. The biggest mistake beginners make is being too vague. If you type, write about accessibility, Copilot will give you a very generic, boring encyclopedia entry. +**Jamie:** Let's pause on Starring (bookmarking). What should a learner take away from it? -**Jamie:** So what makes a good prompt? +**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:** A good prompt is specific, it provides context, and it sets constraints. Think about ordering a sandwich at a deli. You do not just walk up and say, make me food. You say, I would like a turkey sandwich on rye bread, no mayo, add mustard, and please cut it in half. +**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:** I am getting hungry. But I see your point. How does the sandwich order translate to Copilot? +--- -**Alex:** Instead of saying, write about accessibility, you would say, write a three-paragraph section explaining how screen reader users can navigate the VS Code sidebar. Include keyboard shortcuts for NVDA. Assume the reader is a beginner. Use clear headings and bullet points. +**Jamie:** Let's pause on Viewing a Single File. What should a learner take away from it? -**Jamie:** Wow, that is incredibly specific. You gave it the topic, the audience, the length, and the formatting. +**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:** Exactly. And the best part of effective prompting is iterating. Copilot remembers the conversation. So if it gives you an answer and it is a little too technical, you do not have to start over. You just reply, make that a little simpler, or, rewrite that in a friendlier tone. It will adjust the text immediately. +**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:** Alex, I noticed in the settings there is a place to choose different AI models. What does that mean? Why are there different models? +**Jamie:** Let's pause on Reading a code file. What should a learner take away from it? -**Alex:** That is a great observation. GitHub Copilot does not just rely on one single AI brain. It gives you access to multiple AI models from different companies, like OpenAI, Anthropic, and Google. You can switch between them using the model picker, which is a dropdown menu located at the bottom of the chat panel. +**Alex:** Start with Reading a code file: Code files render as a table where each row is one line of code. -**Jamie:** Why would I want to switch? Are they really that different? +--- -**Alex:** They are! Think of it like hiring different contractors for different jobs. If you select the GPT five mini model, it is incredibly fast and completely free to use. It is great for everyday questions and quick code completions. It is like riding a bicycle for a quick errand. +**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. -**Jamie:** But what if I have a really complex problem? Like a bug that spans across five different files? +**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). -**Alex:** Then you might want to open the model picker and select something like Claude Sonnet four point six, or GPT five point two. These models have much deeper reasoning capabilities. They are like renting a heavy-duty moving truck. They are slower, and if you are on a paid plan, they consume what are called premium requests, but they can handle incredibly complex logic. +**Jamie:** Let's pause on How to reach these buttons. What should a learner take away from it? -**Jamie:** That makes sense. But honestly, having to choose which model to use every time I ask a question sounds exhausting. +**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. -**Alex:** I completely agree. And that is why the default setting in the model picker is simply called Auto mode. +**Jamie:** Let's pause on Editing a file. What should a learner take away from it? -**Jamie:** Auto mode. Let me guess, it chooses the vehicle for me? +**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:** Exactly. When you leave the model picker on Auto, Copilot evaluates your prompt behind the scenes. If you ask a simple question, it routes it to a fast, lightweight model. If you ask it to architect a complex new feature, it automatically upgrades to a heavy-duty model like Codex. It manages the cost and the speed for you, so you can just focus on writing. +**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:** I will definitely be leaving that on Auto. +**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:** So, Alex, I have a question about consistency. If I am working on an open source project, and we have very specific rules. For example, let us say our project requires all Markdown headings to use sentence case, and we never use the word click in our documentation. Do I have to type those rules into my prompt every single time I ask Copilot to write something? +--- -**Alex:** That would be incredibly tedious. Thankfully, the answer is no. This brings us to one of the most powerful features for project maintainers: custom instructions files. +**Jamie:** Let's pause on Learning Cards: Viewing a Single File. What should a learner take away from it? -**Jamie:** Custom instructions. Is that a setting in VS Code? +**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:** It is actually a file you commit directly to your repository. You create a regular text file at the path dot github, slash copilot dash instructions dot m d. +**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. -**Jamie:** So it is just a Markdown file living in the dot github folder? +**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. -**Alex:** Exactly. And it acts like an employee handbook for Copilot. You can write your project's rules in plain English in that file. You might write, always write for screen reader users first. Never skip heading levels. Use imperative mood for commit messages. +**Jamie:** Let's pause on Navigating Blame. What should a learner take away from it? -**Jamie:** And Copilot just reads this file automatically? +**Alex:** Start with Navigating Blame. There is something to understand, something to try, and something that proves the try worked. -**Alex:** Yes! Once that file is committed to your repository, Copilot silently reads it in the background every single time you ask a question or generate a completion. You never have to mention it. Copilot simply follows the rules of the house. +**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:** That is brilliant. So if someone clones my repository and uses Copilot, their Copilot will automatically follow my accessibility rules? +--- -**Alex:** Exactly. It is a fantastic way to enforce accessibility standards across an entire team without being a micromanager. Now, there is one more file type I want to mention, which is related to custom instructions, and that is prompt files. +**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. -**Jamie:** Prompt files. How are those different from the instructions file? +**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. -**Alex:** The instructions file is always on, in the background. Prompt files allow you to create your own custom slash commands that you invoke on demand. They are stored in the dot github, slash prompts folder, and they end with the extension dot prompt dot m d. +**Jamie:** What should they understand before typing anything? -**Jamie:** Oh, I see. So earlier we talked about built-in commands like slash explain. I can make my own? +**Alex:** Start with Reading the Commits List Page. There is something to understand, something to try, and something that proves the try worked. -**Alex:** You got it. Let us say you do a lot of accessibility audits. You could create a file called dot github, slash prompts, slash audit dot prompt dot m d. Inside that file, you write a detailed prompt asking the AI to check for missing alt text, skipped headings, and improper link names. +**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. -**Jamie:** And then in the chat panel, I just type slash audit? +**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:** Exactly. You type slash audit, and Copilot executes that massive, detailed prompt perfectly every single time. It saves you from having to type out complex requests over and over again. +**Alex:** The practical takeaway is this. The commit message (heading). Author and date. Parent commit link. A diff for every file changed. +--- -**Jamie:** Alex, this has been an incredibly packed episode. We went from ghost text to custom AI employees. +**Jamie:** Let's pause on Searching for a File. What should a learner take away from it? -**Alex:** It is a lot to take in! But remember, you do not have to use all of this on day one. Start by just leaving Copilot turned on while you write, and get used to how it feels. Let us wrap up with our key takeaways for today. +**Alex:** Start with Searching for a File: The "Go to file" shortcut is extremely useful when you know what you are looking for. -**Jamie:** I will take the first one. When Copilot offers an inline suggestion, your screen reader will announce it. You can press Tab to accept the whole thing, Escape to dismiss it, or my favorite, Control plus the right arrow key to accept it one word at a time. +**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. -### Episode 15: Accessible Code Review +**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. -Navigating diffs with a screen reader, reviewing PRs in browser and VS Code. +**Jamie:** Let's pause on Learning Cards: Searching for a File. What should a learner take away from it? -Based on: [Chapter 14: Accessible Code Review](docs/15-code-review.md) +**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. -[Download Episode 15 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep15-accessible-code-review.mp3) +--- -
-Read Transcript - Episode 15: Accessible Code Review +**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. -#### Transcript +**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. -**Alex:** Welcome back to Gitt Going with GitHub. This is episode fifteen, Accessible Code Review. I am your host, Alex. +**Jamie:** Let's pause on Navigating the sidebar. What should a learner take away from it? -**Jamie:** And I am Jamie! I am so ready for this one. +**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. -**Alex:** Today is all about the reviewer experience. We are going to cover how to navigate file changes, read code comparisons, leave helpful comments, and submit your final review, entirely using your keyboard and screen reader. +**Jamie:** Let's pause on The Repository About Section. What should a learner take away from it? -**Jamie:** Before we jump in, let us quickly remind everyone of a couple of prerequisites. We will be building heavily on two previous episodes. First, episode six, where we introduced the concept of pull requests and the general review process. And second, episode eleven, which covered VS Code accessibility features. If you have not listened to those yet, you might want to open them up and give them a quick listen first. +**Alex:** Start with The Repository About Section: Quick way to check the project description, website link, and topics. -**Alex:** Exactly. Now, in episode six, we talked about how a pull request, or PR, is a way to propose changes to a repository. You are literally requesting that the maintainers pull your code into their project. But before they do that, someone needs to review it. +**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. +--- -**Jamie:** So, Alex, let us start with the big picture. Why is code review so important? When I first started learning GitHub about two years ago, I thought code review was just a way for senior developers to catch my typos. +**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:** That is a very common misconception. Code review does catch bugs, but it is fundamentally about quality and learning. It is a two-way street. The author gets another set of eyes on their work, and the reviewer gets to learn new techniques or familiarise themselves with a different part of the codebase. +**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. -**Jamie:** I love that. It reminds me of a writer's workshop. You do not just hand your manuscript to an editor to fix your grammar. You share it with peers. They might point out that a character's motivation is confusing, or they might learn a new way to write dialogue by reading your work. +**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. -**Alex:** That is a brilliant analogy. And just like a writer's workshop, building a habit of reviewing others' work regularly is one of the fastest ways to level up your own skills. +**Jamie:** Let's pause on Scenario B: "I want to find a good file to edit". What should a learner take away from it? -**Jamie:** I will be honest, though. Reviewing code still feels intimidating sometimes. Especially when I am looking at a pull request from someone who has been coding for ten years longer than I have. +**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:** It does feel intimidating! But here is the thing, you bring a unique perspective. Even if you do not catch a complex logic bug, you might catch an unclear variable name, or a missing documentation update. What we look for in a review really falls into four categories. Correctness, clarity, style, and accessibility. +**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:** Correctness meaning, does the code actually do what it is supposed to do? +**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:** Right. Clarity means, is it easy to understand? Style means, does it follow the project's conventions? And accessibility means, does this change introduce any barriers for users with disabilities? You do not have to be an expert in all four to leave a valuable review. +**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:** Okay, so I am sold on the why. Let us talk about the where. Where do we actually do these reviews? +--- -**Alex:** You have two main environments for code review. The GitHub web interface in your browser, and your local code editor, which for our workshop is VS Code. +**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? -**Jamie:** Is one better than the other? +**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:** They just have different strengths. Both give you full keyboard and screen reader access. I like to think of the web browser as a quick chat at a coffee shop. It is great for quick reviews, leaving a few comments, and you can do it from any machine without downloading the code. +**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:** And VS Code? +**Jamie:** Let's pause on Scenario E: "I want to contribute - where do I start?". What should a learner take away from it? -**Alex:** VS Code is like setting up in your home office for deep work. It is best for large reviews where you need to navigate through a lot of files, test the code locally, or use advanced screen reader features. +**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. -**Jamie:** I should also mention there is a third path, right? The GitHub CLI, or command line interface. +**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. -**Alex:** Yes, absolutely. The GitHub CLI is fantastic. You can open your terminal and type gh pr review to approve or request changes without ever leaving the command line. It is like the drive-through window of code review. Very fast, very efficient, but maybe not where you want to sit down and leave twenty detailed inline comments. +**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. -**Jamie:** Let us start with the coffee shop. The web browser. When I open a pull request on GitHub, how do I actually read the changes? +**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. -**Alex:** You need to navigate to the Files Changed tab. When you load a pull request page, you are usually on the Conversation tab, which has the description and the comments. +**Jamie:** Before we leave Try It: The Five-Tab Tour, what is the practical point? -**Jamie:** Right, so how do I get to the files? +**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:** The most reliable way with a screen reader is to use your landmark navigation. Press the D key if you are using NVDA or JAWS, or use your VoiceOver landmarks rotor, to navigate to the Pull request navigation tabs landmark. From there, you can press the Right Arrow or Tab key to find the Files changed link, and press Enter. +--- -**Jamie:** And when I open that, what am I actually listening to? +**Jamie:** Let's pause on What Is the Learning Room? What should a learner take away from it? -**Alex:** You are listening to a diff. Diff is short for difference. It is a format that shows exactly what changed between the old version of a file and the new version. +**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. -**Jamie:** I always explain a diff like a recipe where someone has crossed out a line and written a new one. Imagine a recipe card that says one cup of sugar, but the words one cup have a line through them, and next to it, someone wrote two cups. +**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:** That is exactly what a unified diff format looks like. It is called unified because it shows the old and new text combined into a single continuous flow. Every line in a diff is categorized in one of three ways. An addition line, a deletion line, or a context line. +**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 us break those down. +**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:** An addition line is new code that the author added. It starts with a plus sign prefix. A deletion line is code the author removed. It starts with a minus sign prefix. +**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:** And context lines? +--- -**Alex:** Context lines are the unchanged lines of code right above and below the changes. They do not have a plus or minus prefix. They are just there to give you context, so you know where the change is happening in the file. +**Jamie:** Let's pause on 1. Open the assignment link. What should a learner take away from it? -**Jamie:** Okay, so I am on the Files Changed tab. How do I navigate through this diff? +**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, orient yourself using the file tree. This is a region on the page that lists every changed file. You can navigate to the File tree region using your landmark shortcut, and just press the Down Arrow to move through the list. It will announce the file name, and how many additions and deletions it has. +**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:** That is so helpful for getting a summary. If I see a file has five hundred additions, I know I need a coffee. +**Jamie:** Let's pause on 2. Identify yourself (if asked). What should a learner take away from it? -**Alex:** Exactly. Once you know what files you are dealing with, you can move to the actual code. Each changed file is presented under a heading level three containing the file name. So you can just press the number 3 key on your keyboard to jump from file to file. +**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. -**Jamie:** And what happens when I reach a file I want to read? +**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. -**Alex:** The diff for each file is structured as a table. Every row in the table is one line of code. To read it, you will navigate to the table using the T key. Then, and this is important, you need to turn on Focus Mode if you are using NVDA, or turn off the Virtual PC Cursor if you are using JAWS. +**Jamie:** Let's pause on 3. Accept the assignment. What should a learner take away from it? -**Jamie:** Ah, right. Because in Browse Mode, pressing the Down Arrow just moves through the page structure. In Focus Mode, your arrow keys let you navigate the table cells directly. +**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:** Precisely. Once you are interacting with the table, you can press the Down Arrow to move through the lines of code one at a time. To read across the columns of a specific line, you press Control plus Alt plus the Right Arrow key. It will read the line number, then the change type, meaning whether it was added or deleted, and then the actual code content. +**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. +--- -**Jamie:** Okay, so I am reading down the table, line by line. I hear a minus prefix, then a plus prefix, so I know a line was replaced. Let us say I spot a problem. The author changed a heading, but they skipped a heading level. They went from level two to level four. As an accessibility advocate, I know that breaks navigation for screen reader users. How do I tell them? +**Jamie:** Let's pause on 4. Open your new repository. What should a learner take away from it? -**Alex:** You need to write an inline review comment. This means you are attaching your comment directly to the specific line of code that has the issue, rather than just leaving a general comment at the bottom of the page. +**Alex:** Start with 4. Open your new repository. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** Like sticking a post-it note exactly on the sentence in a book that needs a rewrite. +**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:** Exactly. To do this, while your focus is on that specific line in the diff table, press the Tab key to look for a comment button. Or you can press the B key to navigate to the next button, which will say Add a comment to this line. +**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:** Okay, that sounds like a lot of steps. +**Jamie:** Let's pause on 5. Find your first challenge issue. What should a learner take away from it? -**Alex:** It does! But here is the thing, you have already done most of this on Day One of the workshop. It is the exact same workflow as opening an issue or replying to a discussion, just attached to a line of code. You press Enter on that button, an inline comment box opens, you switch to Focus Mode, and you type your feedback. +**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. -**Jamie:** What makes a good review comment? I remember early on, I would just write things like, this is wrong, or please fix. And people would get frustrated because they did not know what I wanted. +**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. -**Alex:** A helpful review comment is specific, educational, and graduated. +**Jamie:** Let's pause on 6. Confirm Aria can talk to you. What should a learner take away from it? -**Jamie:** Graduated? What does that mean? +**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 ). -**Alex:** It means signalling how important the comment is. Is it a strict requirement that blocks the pull request from merging, or is it just a stylistic preference? Using prefixes at the start of your comment is a great way to set expectations. +--- -**Jamie:** Oh, I love prefixes. I use the word nit, spelled N I T, all the time. Like, nit, the link text says click here, which is not great for screen readers. Consider changing it to read the setup guide. +**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:** That is a perfect example. Nit means a non-blocking stylistic preference. Another good prefix is blocking. For your heading example, you could write, blocking, heading hierarchy violation. This skips level three. Please change to a level three heading before this merges. +**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:** That is so clear. It names the issue, explains why it matters, and tells them exactly how to fix it. +**Jamie:** Let's pause on Readiness Checkpoint. What should a learner take away from it? -**Alex:** Right. And once you type that comment, you tab to the button that says Start a review, and press Enter. +**Alex:** This is where Readiness Checkpoint becomes real: before starting Chapter 5 challenges, you should be able to. -**Jamie:** Wait, why Start a review? Why not just click Add single comment? +**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:** If you use Add single comment, it posts immediately and sends an email notification to the author right then and there. If you leave ten comments, they get ten emails. Start a review batches all your comments together into a draft. When you are done looking at all the files, you submit the review all at once, and they get one single notification. It is much kinder to your teammates. +**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. +--- -**Jamie:** Let us talk about that final submission. I have gone through all the files, I have left my post-it notes on various lines. How do I wrap this up? +**Jamie:** Let's pause on Track 1: GitHub Skills Modules (Optional Self-Paced Practice). What should a learner take away from it? -**Alex:** You need to submit your review. You navigate to the top right of the Files Changed page, or the bottom of the Conversation tab, and find the Review changes button. Press Enter on that, and a dialog opens. +**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. -**Jamie:** This is where I give it my final grade, right? +**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:** Exactly. The dialog has a summary text area where you can write an overall thought, like, great work, just a few accessibility tweaks needed. Below that are three radio buttons for your verdict. Comment, Approve, or Request 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. -**Jamie:** Approve is pretty obvious. It means the code looks good to me, let us merge it. Request changes means I found a blocking issue, and they need to fix it before it can merge. What about Comment? +**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). -**Alex:** Comment means you have observations or questions, but you do not have a strong position on whether it should be blocked or approved. You are just leaving notes. Once you select your radio button, tab to Submit review, and press Enter. +**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. -**Jamie:** Okay, so that is the coffee shop experience. The web browser. It is incredibly powerful, but navigating those diff tables can get a little tedious if a pull request has hundreds of changes. +**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:** And that is exactly why we have the home office. VS Code. When you are dealing with a large review, VS Code offers a feature that completely changes the game for screen reader users. It is called the Accessible Diff Viewer. +--- -**Jamie:** I remember the first time I used this. It was an absolute revelation. +**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:** How would you describe the difference between the browser diff and the VS Code Accessible Diff Viewer? +**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:** In the browser, as we discussed, it is a big table. You have to navigate down rows, and across columns to figure out what line you are on, whether it is a plus or minus, and what the text says. The Accessible Diff Viewer is like a guided museum audio tour. It skips all the empty hallways and unchanged context lines, and just takes you straight to the exhibits that actually changed, and tells you exactly what happened to them. +**Jamie:** Let's pause on Your Learning Room Folder Structure. What should a learner take away from it? -**Alex:** That is a beautiful way to put it. Let us walk through how to use it. First, you open the pull request in VS Code. If you have the GitHub Pull Requests extension installed, you can open the Command Palette with Control plus Shift plus P, and search for GitHub Pull Requests View Pull Request. +**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. -**Jamie:** And once the pull request is open, the changed files appear in a tree on the sidebar. You navigate to a file and press Enter to open its diff editor. +**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:** Right. Now, when the standard diff editor opens, it is still a side-by-side visual comparison, which can be noisy. But here is the magic trick. Press the F7 key. +**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. -**Jamie:** F7. The magic button. What happens? +**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:** The Accessible Diff Viewer opens as a dedicated panel. Instead of a table, it presents each change, which programmers sometimes call a hunk, as a structured block of text designed specifically for sequential listening. +--- -**Jamie:** So what does my screen reader actually say when I press F7? +**Jamie:** Let's pause on Why you create a separate branch. What should a learner take away from it? -**Alex:** It announces something like this. Changed lines fourteen to fourteen in docs slash keyboard-shortcuts dot markdown. Change one of three. Removed, heading level four, NVDA Single-Key Navigation. Added, heading level three, NVDA Single-Key Navigation. +**Alex:** Start with Why you create a separate branch. There is something to understand, something to try, and something that proves the try worked. -**Jamie:** It is just so clean. It tells me exactly where I am, how many changes there are in total, and gives me clear Removed and Added labels. I do not have to guess what changed. +**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:** Exactly. And the navigation is purpose-built. You just press F7 again to jump to the next change. Or Shift plus F7 to jump to the previous change. You do not have to mess around with table navigation or focus modes. It just works with NVDA, JAWS, and VoiceOver right out of the box. +**Jamie:** Let's pause on How to use your branch. What should a learner take away from it? -**Jamie:** And if I want to leave a comment while I am in VS Code? +**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:** You close the Accessible Diff Viewer by pressing Escape. That puts your cursor right back on the line you were just reviewing in the main editor. From there, you can open the Command Palette with Control plus Shift plus P, and select GitHub Pull Requests Add Comment. A text area opens, you type your comment, and submit it. +**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. -**Jamie:** And those comments sync directly back to GitHub, right? The author sees them on the web exactly as if I had used the browser. +**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. -**Alex:** Yes, they sync instantly. The author gets the exact same experience. They do not know or care which tool you used to write the review. +**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. -**Jamie:** This is so empowering. Whether I use the browser for a quick check or VS Code for a deep dive, I have complete access to the review process. +**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. -**Alex:** You do. And developing this manual review skill is critical. You need to know how to spot a heading hierarchy issue, or a missing alt attribute, or unclear link text yourself. +--- -**Jamie:** Why is that so critical? +**Jamie:** Let's pause on Tool Cards: Switch to Your Practice Branch. What should a learner take away from it? -**Alex:** Because in our next episode, we are going to introduce Accessibility Agents. These are AI tools that can automatically scan a pull request and draft a review for you. +**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. -**Jamie:** Oh, wow. So the AI just does the review for me? +**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. -**Alex:** Not quite. The AI generates a draft. It will point out potential issues and suggest comments. But the AI does not have your human judgment. Your job shifts from finding every single issue manually, to reading the AI's draft, verifying if it is correct, and deciding what is actually worth saying to the author. +**Jamie:** Before we leave Tool Cards: Switch to Your Practice Branch, what is the practical point? -**Jamie:** I see. So if I do not know what a good review looks like, I will not know if the AI is giving me good advice. +**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. -**Alex:** Exactly. The manual skill is the foundation. The AI is just an amplifier. +**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. -**Jamie:** Let us wrap this up with a few concrete takeaways from today's episode. Number one, code review is a two-way street for quality and learning. It is not just about finding bugs, it is about improving the whole team. +**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:** Number two, you have two great environments. The browser is fantastic for quick, accessible reviews using landmark and table navigation. But for deep, line-by-line reading, press F7 in VS Code to open the Accessible Diff Viewer for a streamlined, sequential experience. +--- -**Jamie:** Number three, when writing comments, be specific, educational, and graduated. Use prefixes like nit or blocking to clearly communicate your expectations to the author. +**Jamie:** Let's pause on [TODO] 1 - "Who Can Contribute?" section. What should a learner take away from it? -**Alex:** And number four, always use Start a review to batch your comments, rather than sending a dozen single comment notifications. +**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.]. -**Jamie:** This has been incredibly helpful. I feel like I am ready to go leave some blocking post-it notes on some pull requests. +**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? -**Alex:** I am sure your team will appreciate the thorough feedback. Thank you all for listening to Gitt Going with GitHub. In episode sixteen, we will dive into those Accessibility Agents and see how AI can speed up your workflow. Until then, keep practicing those reviews. +**Jamie:** Let's pause on [TODO] 3 - "After Your Contribution Is Merged" section. What should a learner take away from it? -**Jamie:** See you next time! +**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. -### Episode 16: Issue Templates +**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. -Creating YAML-based issue templates for bug reports, features, and custom forms. +**Jamie:** What is the pre-flight check here? -Based on: [Chapter 15: Issue Templates](docs/17-issue-templates.md) +**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. -[Download Episode 16 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep16-issue-templates.mp3) +**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. -
-Read Transcript - Episode 16: Issue Templates +--- -#### Transcript +**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 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:** 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:** Welcome to Gitt Going with GitHub. This is episode 16, Issue Templates. I am Alex, and as always, I am joined by Jamie. +**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:** Hello everyone! I am very excited for this one because, if you remember way back in episode 5, we talked about how to file an issue. And I mentioned that staring at a completely blank text box was one of the most intimidating parts of learning GitHub for me. I never knew what information I was supposed to provide. +**Jamie:** Before we leave You (PR author), what is the practical point? -**Alex:** It is a universal feeling. You find a bug, you navigate to the Issues tab, you activate the New Issue button, and GitHub just hands you a blank page. You are left wondering, what do the maintainers actually need to know? Do they want my operating system? My screen reader version? Steps to reproduce? +**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:** Exactly. And then you write what you think is a helpful description, and a day later a maintainer replies asking for exactly the details you left out. It is frustrating for everyone. It feels like a lot of unnecessary back and forth. +**Jamie:** What is the teaching move inside Visibility? -**Alex:** That is exactly the problem issue templates solve. Today, we are going to learn what issue templates are, how to use them, and most importantly, how to create them for your own repositories. We will cover where they live in your project, how to configure them, and the two different types of templates. We have traditional Markdown templates, and we have YAML form templates. We will talk about why YAML forms are a massive upgrade for screen reader accessibility. +**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:** I love anything that makes screen reader navigation smoother. And just to remind our listeners, if you have not listened to episode 5 on working with issues, you might want to brush up on that first. But if you know how to navigate to the Issues tab and activate the New Issue button, you are ready for today. +--- -**Alex:** Perfect. Let us start by defining what an issue template actually is. Think of an issue template like going to a new doctor. When you walk in, the receptionist does not just hand you a blank piece of paper and say, write down why you are here. +**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. -**Jamie:** Right, they give you an intake form. It asks for your name, your symptoms, your medical history, your current medications. It guides you to provide exactly what the doctor needs to know before they even see you. +**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 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. + +--- + +**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:** 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. + +--- + +**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 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. + +--- + +**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. + +
+ +--- + +## 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](docs/05-working-with-issues.md) + + + +[Download Episode 5 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep05-working-with-issues.mp3) + +
+Read Transcript - Episode 5: Working with Issues + +#### 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:** 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 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 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 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:** 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:** 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:** 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:** 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:** 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:** 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 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 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. 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 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 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 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 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 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. 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 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. 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 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. + +--- + +**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 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:** 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 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 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. + +
+ +--- + +### 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. + +--- + +**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:** 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:** 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. + +--- + +**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:** 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. + +--- + +**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. + +--- + +**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. + +--- + +**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:** 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. + +--- + +**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 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. + +--- + +**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 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. + +--- + +**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 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. + +--- + +**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:** 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. + +--- + +**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 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. + +--- + +**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. + +--- + +**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. + +--- + +**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. + +--- + +**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 - Challenge 03: Join the Conversation + +#### 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:** 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:** 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. + +**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. + +**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:** 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:** 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:** 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:** 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. + +--- + +**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. + +**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. + +**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:** 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. + +**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, 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. + +--- + +**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. + +--- + +**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 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 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. + +--- + +**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. + +--- + +**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 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 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 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. + +--- + +**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. + +--- + +**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. + +--- + +**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:** 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 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. + +--- + +**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:** 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. + +--- + +**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 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. + +--- + +**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 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? + +--- + +**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 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 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:** 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. + +--- + +**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:** 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 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:** 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. + +--- + +**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. + +--- + +**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. + +--- + +**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. + +--- + +**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:** 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. + +--- + +**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 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. 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 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 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 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. 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 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. 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:** 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 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 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:** 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 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. + +--- + +**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 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. + +--- + +**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 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 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:** 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. + +--- + +**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:** 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. + +
+ +--- + +### 13. Episode 22: GitHub Flavored Markdown + +Markdown syntax, GitHub extensions, and writing accessible documentation. + +Based on: [Appendix C: GitHub Flavored Markdown](docs/appendix-c-markdown-reference.md) + +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:** 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:** 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:** 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:** 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:** 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:** 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:** 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:** 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:** 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 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:** 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 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. + +--- + +**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:** 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. 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 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. + +--- + +**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 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. 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 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. + +--- + +**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. + +--- + +**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:** 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:** 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:** 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 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:** 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. 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:** 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. 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:** 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. 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:** 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. 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 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. 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 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. 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 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. 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 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. + +--- + +**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 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. 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 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. + +--- + +**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 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 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 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. 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 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. 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:** 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. 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 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. 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:** 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. + +
+ +--- + +### 14. Episode 23: GitHub Gists + +Lightweight code sharing: creating, editing, forking, and embedding Gists. + +Based on: [Appendix U: GitHub Gists](docs/appendix-u-discussions-and-gists.md) + +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:** 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. 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. + +--- + +**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 23. Next in the series is episode 24, where we keep building the same contributor muscles. + +
+ +--- + +### 15. Episode 24: GitHub Discussions + +Forum-style conversations, Q&A, polls, and navigation with screen readers. + +Based on: [Appendix U: GitHub Discussions](docs/appendix-u-discussions-and-gists.md) + +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:** 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:** 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. 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. + +--- + +**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 24. Next in the series is episode 25, where we keep building the same contributor muscles. + +
+ +--- + +## 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](docs/06-working-with-pull-requests.md) + + + +[Download Episode 6 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep06-working-with-pull-requests.mp3) + +
+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? + +--- + +**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:** 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. + +--- + +**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:** 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:** 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:** 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:** 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 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 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 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. + +--- + +**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 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:** 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 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. + +--- + +**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 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:** 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:** 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:** 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 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 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:** 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 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 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. 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:** 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 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 6. Next in the series is episode 7, where we keep building the same contributor muscles. + +
+ +--- + +### 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 - 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:** 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:** 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:** 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:** 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:** 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. + +--- + +**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:** 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. + +--- + +**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 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:** 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 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:** 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 [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. 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 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. + +--- + +**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 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. 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 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 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 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. + +--- + +**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 "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. 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 "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. 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 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 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 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 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 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 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 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. 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 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. 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 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 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. + +
+ +--- + +### 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 - Challenge 05: Make Your Mark + +#### 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:** 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:** 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:** 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:** 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. + +--- + +**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. + +--- + +**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 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:** 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 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:** 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 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:** 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:** 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 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 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 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:** 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. + +--- + +**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 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. + +--- + +**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. 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 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 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 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. 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:** 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. + +--- + +**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:** 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. 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 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:** 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 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 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 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. 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 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 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: 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. 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 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 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 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. + +--- + +**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:** 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. + +
+ +--- + +### 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:** 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:** 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:** 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:** 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:** 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:** 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:** 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 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. + +--- + +**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 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 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 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:** 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 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:** 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 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 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 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. 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:** 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. 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. + +
+ +--- + +### 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](docs/07-merge-conflicts.md) + + + +[Download Episode 7 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep07-merge-conflicts.mp3) + +
+Read Transcript - Episode 7: Merge Conflicts Are Not Scary + +#### 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:** 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 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. + +--- + +**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 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 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:** 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:** 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:** 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). + +--- + +**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 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 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. 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 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 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 7. Next in the series is episode 8, where we keep building the same contributor muscles. + +
+ +--- + +### 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 - Challenge 07: Survive a Merge Conflict + +#### 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:** 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:** 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 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:** 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:** 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:** 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. + +--- + +**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:** 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:** 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. + +--- + +**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. + +--- + +**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. + +--- + +**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. + +--- + +**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:** 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 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. + +
+ +--- + +### 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](docs/08-open-source-culture.md) + + + +[Download Episode 8 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep08-culture-and-etiquette.mp3) + +
+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:** 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 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:** 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 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 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:** 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:** 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:** 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. + +--- + +**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 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. + +--- + +**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 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:** 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:** 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:** 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 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). 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:** 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 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. 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 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:** 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 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. 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 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:** 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 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. 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 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 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:** 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 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:** 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. + +
+ +--- + +### 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:** 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:** 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:** 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:** 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:** 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:** 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:** 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 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:** 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. 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:** 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. + +--- + +**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 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. 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:** 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. + +--- + +**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:** 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.". + +--- + +**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. + +--- + +**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. + +--- + +**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. + +--- + +**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. + +--- + +**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. + +--- + +**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 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:** 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 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 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 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. + +--- + +**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:** 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 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. + +--- + +**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 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. + +--- + +**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. + +--- + +**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. + +--- + +**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:** 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. + +--- + +**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 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. + +
+ +--- + +### 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](docs/09-labels-milestones-projects.md) + + + +[Download Episode 9 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep09-labels-milestones-projects.mp3) + +
+Read Transcript - Episode 9: Labels, Milestones, and Projects + +#### 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. + +--- + +**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. + +--- + +**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. + +--- + +**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. + +**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 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:** 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:** 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. + +
+ +--- + +### 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](docs/appendix-r-projects-deep-dive.md) + +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. + +--- + +**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. + +**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 1. Projects v2: What Changed. GitHub has two generations of project tooling. Put another way, the current generation - called Projects (v2) - is what you'll find on any repository or organization page today. It 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 2. Creating a Project becomes real: projects can be created at the organization level (shared across all repos in an org) or at the repository level (scoped to one repo). + +--- + +**Jamie:** Turn that into a path someone can follow. + +**Alex:** Start with Create from an Organization. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, navigate to your organization page (github.com/your-org). Then, select the Projects tab. After that, activate "New project" button. Finally, choose a template (blank table, blank board, feature release, etc.) or start empty. 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, give the project a name and select "Create project". The rhythm is simple: orient, act, verify, then continue. + +**Jamie:** Give me the sequence, because order matters here. + +**Alex:** Start with Create from a Repository. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, navigate to any repository. Then, select the Projects tab. After that, activate "Link a project" or "New project". Finally, follow the same template/name flow. 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:** That matters because of the next idea. Start with Learning Cards: Creating a Project. 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 "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. 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. + +--- + +**Jamie:** If I am listening before the workshop starts, what should settle in my mind first? + +**Alex:** Here is the plain-English version of Table View. A spreadsheet-style grid where each row is an issue, PR, or draft item. Put another way, columns are fields (Title, Status, Assignee, Labels, Priority, custom fields you create). + +**Alex:** This is where the talk moves from concept to action. This is where Screen reader output per row becomes real: "Fix keyboard trap in modal dialog Status: In Progress Assignee: alice Priority: High Labels: bug, accessibility". + +**Jamie:** Where do you want a learner to place their attention here? + +**Alex:** Keep the learner anchored in Board View. Each column represents a status value. This is the part to say slowly: Cards can be dragged between columns (or updated via keyboard by editing the Status field). + +--- + +**Jamie:** How would you walk the room through that step by step? + +**Alex:** Start with Change a card's column without dragging. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, enter to open the card. Then, navigate to the Status field in the right panel. After that, activate the Status dropdown. Finally, select the new column value. The rhythm is simple: orient, act, verify, then continue. + +**Jamie:** What does the learner do first, second, and then after that? + +**Alex:** First, 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:** What would you say to someone who is already bracing for this to be too much? + +**Alex:** Start with Roadmap View: Items appear as bars spanning their start/due dates. The next useful detail is this: Iterations and milestones can be visualized against real calendar time. + +**Alex:** Hold that next to this. Start with Setting dates. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** The practical anchors are these. Add a Date custom field (e.g., "Start Date", "Due Date") or use a Milestone field. Items without dates appear in the ungrouped section. + +--- + +**Jamie:** Give me the version that sounds like an instructor, not a manual. + +**Alex:** Start with Learning Cards: The Three Layouts. 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. 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. 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. + +**Alex:** That connects to another useful point. Keep the learner anchored in 4. Custom Fields. This is one of Projects v2's most powerful features. This is the part to say slowly: You can add fields beyond the GitHub defaults (Title, Assignee, Labels, Milestone, 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 Field Types. What should a learner take away from it? + +**Alex:** The reason Field Types matters is that text: Free-form notes for things like acceptance criteria or design links. That gives the learner a simple foothold: number: Numeric values such as story points or estimates (for example, "Points: 3"). + +--- + +**Jamie:** Let's pause on Creating a Custom Field. What should a learner take away from it? + +**Alex:** Start with Creating a Custom Field. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, in Table view, scroll right to the + button at the end of the column header row. Then, activate the + button. After that, select a field type. Finally, name the field and configure options (for select fields, type each option, press Enter to add more). Think 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 Custom Field, what is the practical point? + +**Alex:** First, confirm - the field appears as a new column. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. + +**Jamie:** Let's pause on Editing a Field Value on an Item. What should a learner take away from it? + +**Alex:** Start with Editing a Field Value on an Item. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, in Table view, navigate to the cell where the field intersects the row. Then, enter or Space to activate the editor. After that, type value (text/number) or select from dropdown (single select). Finally, enter or Tab to confirm. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. + +**Jamie:** Let's pause on Add an Existing Issue or PR. What should a learner take away from it? + +**Alex:** This is where Add an Existing Issue or PR becomes real: the issue itself will now show which projects it belongs to in its sidebar. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed. + +**Alex:** First, activate the "+ Add item" button at the bottom of a table/column. Then, type to trigger the issue/PR search. After that, type a keyword or issue number. Finally, select the item - 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:** Before we leave Add an Existing Issue or PR, what is the practical point? + +**Alex:** First, the issue/PR is now tracked in the project; it still lives in its repository. 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 Add a Draft Issue. What should a learner take away from it? + +**Alex:** Keep the learner anchored in Add a Draft Issue. Draft issues live only inside the project (not in any repository) until you promote them. This is the part to say slowly: When to use drafts: Capturing ideas during planning before you're ready to commit them to a repo. + +**Alex:** First, activate "+ Add item". Then, type the title directly (no ). After that, press Enter - a draft row appears. Finally, open the draft → "Convert to issue" button → select the repository. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. + +**Jamie:** Let's pause on Promote a Draft to an Issue. What should a learner take away from it? + +**Alex:** Start with Promote a Draft to an Issue. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, open the draft item (Enter on the row). Then, activate "Convert to issue" in the panel. After that, select the target repository from the dropdown. Finally, confirm - the draft becomes a real issue in that repo. The rhythm is simple: orient, act, verify, then continue. + +**Jamie:** Let's pause on Bulk Edit Items. What should a learner take away from it? + +**Alex:** Start with Bulk Edit Items. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, check the checkbox on each row (first column, Space to toggle). Then, a bulk action bar appears 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:** This is the part worth saying out loud. Here is the plain-English version of 6. Built-In Automations. Projects v2 has native automation rules - no GitHub Actions YAML 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 Accessing Automations. What should a learner take away from it? + +**Alex:** Start with Accessing Automations. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, select the. menu (project overflow) in the top-right. Then, select "Workflows". After that, you'll see a list of built-in automation rules you can enable/disable. 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 Available Built-In Workflows. Item added to project: When an item is manually added, its Status is set to a value you choose. This is the part to say slowly: Item reopened: When an issue or pull request is reopened, its Status changes back (for example, to "In Progress"). + +--- + +**Jamie:** Let's pause on Setting Up Auto-Add. What should a learner take away from it? + +**Alex:** The reason Setting Up Auto-Add matters is that this is the most powerful workflow for maintainers. That gives the learner a simple foothold: now any matching issue in linked repos is added to your project the moment it's filed - no manual triage step required. + +**Alex:** First, in Workflows, select "Auto-add to project". Then, toggle it On. After that, configure the filter: e.g., label:accessibility is:issue adds any new issue with the accessibility label automatically. The rhythm is simple: orient, act, verify, then continue. + +**Alex:** Here is the practical turn. Start with GitHub Actions Integration: For more complex automations, Projects v2 has a full GraphQL API and works with GitHub Actions. The next useful detail is this: See Appendix Q: GitHub Actions and Workflows for the foundation, and the GitHub documentation on automating projects for advanced patterns. 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 what that changes in practice. Auto-assign items based on repository when added. Set due dates based on linked milestone. Send Slack notifications when high-priority items are added. + +**Jamie:** Let's pause on 7. Iterations (Sprints). What should a learner take away from it? + +**Alex:** Here is the plain-English version of 7. Iterations (Sprints). An iteration field lets you group work into time-boxed cycles - sprints, weeks, or any cadence you choose. + +--- + +**Jamie:** Let's pause on Creating an Iteration Field. What should a learner take away from it? + +**Alex:** Start with Creating an Iteration Field. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, add a new field (the + column button in Table view). Then, select "Iteration" as the field type. After that, name it (e.g., "Sprint"). Finally, set the iteration duration (1 week, 2 weeks, custom). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe. + +**Jamie:** Before we leave Creating an Iteration Field, what is the practical point? + +**Alex:** First, GitHub automatically generates current and upcoming iterations. It is 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 Iterations. What should a learner take away from it? + +**Alex:** Start with Using Iterations. 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. 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. + +**Jamie:** Let's pause on Iteration Insights. What should a learner take away from it? + +**Alex:** Start with Iteration Insights. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, select the Insights tab (the bar chart icon). Then, select "Current iteration". After that, see: items by status, completion rate, items added vs closed over time. The rhythm is simple: orient, act, verify, then continue. + +--- + +**Jamie:** Let's pause on 8. Views and Filters. What should a learner take away from it? + +**Alex:** Start with 8. Views and Filters: A view is a saved configuration of layout + filters + grouping + sort. The next useful detail is this: You can have many views on one project, each showing a different slice of the data. + +**Jamie:** Let's pause on Creating a View. What should a learner take away from it? + +**Alex:** Start with Creating a View. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, activate the "+ New view" button in the view tab bar. Then, choose layout (Table, Board, Roadmap). After that, configure filters, grouping, sort. Finally, the view saves automatically with a default name - rename by clicking/activating the tab label. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. + +**Jamie:** Let's pause on Filter Syntax. What should a learner take away from it? + +**Alex:** This is where Filter Syntax becomes real: the filter bar accepts a query language similar to GitHub's issue search. That matters in practice: status:In Progress shows only items with that Status value. + +--- + +**Jamie:** Let's pause on Grouping. What should a learner take away from it? + +**Alex:** Keep the learner anchored in Grouping. In Table or Board view, you can group rows. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor. + +**Alex:** First, select "Group by" in the view configuration menu. Then, choose any field: Status, Assignee, Priority, Iteration, Label, Repository. After that, items are collapsible into group sections. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed. + +**Jamie:** Let's pause on Sorting. What should a learner take away from it? + +**Alex:** The reason Sorting matters is that multiple sort levels are supported. + +**Alex:** The parts worth keeping in working memory are these. Priority ascending, then due date ascending. + +**Alex:** Keep the thread going. Start with 9. Cross-Repository Projects: A single project can track issues and PRs from multiple repositories - including repos in different organizations (if you have access). + +--- + +**Jamie:** Let's pause on Add a Repository to a Project. What should a learner take away from it? + +**Alex:** Start with Add a Repository to a Project. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, in project settings (the. overflow menu → "Settings" ). Then, select "Manage access" → "Add repository". After that, search and select additional repositories. Finally, items from those repos can now be added to the project. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl. + +**Alex:** Another way to ground it. This is where Using the Repository Field becomes real: when a project spans multiple repos, the "Repository" field lets you see - and filter by - which repo each item belongs to. That matters in practice: Common use case: An organization project tracking all accessibility bugs across every repo, labeled accessibility, with Auto-add enabled. 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 Project Home Page (list of projects). There is something to understand, something to try, and something that proves the try worked. + +**Alex:** Treat examples as spoken recipes, not decorations. You may hear something like 3 → Jump to project titles (they are h3 links); Enter → Open a project. 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 Table View matters is that NVDA note: Use Browse mode (NVDA+Space to toggle) to read all cell content, then App mode (NVDA+Space again) for interactive editing. That gives the learner a simple foothold: NVDA announces cell content as you navigate with arrow keys. + +**Jamie:** Let's pause on 11. Accessibility Agents: /project-status. What should a learner take away from it? + +**Alex:** Start with 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. + +**Alex:** Keep the teaching thread moving. Start with What It Shows. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** For a learner, the useful signals are these. 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. + +--- + +**Jamie:** Let's pause on Example Output. What should a learner take away from it? + +**Alex:** This is where Example Output becomes real: GitHub Project: Accessibility Agents Roadmap (3 active views). That matters in practice: After the overview: "Want to see a specific column or check a team member's workload?". + +**Alex:** The room should hear these as checkpoints. Stale: "Update screen reader navigation guide" - In Review for 9 days, no activity. Unassigned: "Triage accessibility bug backlog" in In Progress. + +**Alex:** Keep the teaching thread moving. Start with When to Use It. 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. 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. + +**Jamie:** Let's pause on Exercise 1: Create a Personal Tracking Project. What should a learner take away from it? + +**Alex:** Start with Exercise 1: Create a Personal Tracking Project. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, create a new project at the organization level: name it "My Workshop Contributions". Then, add the Board layout. After that, add a custom Priority field with options: P0, P1, P2. Finally, add your fork of accessibility-agents as a linked repository. The rhythm is simple: orient, act, verify, then continue. + +**Jamie:** Before we leave Exercise 1: Create a Personal Tracking Project, what is the practical point? + +**Alex:** First, add any open issue you've filed to the 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 Exercise 2: Set Up Automation. What should a learner take away from it? + +**Alex:** Start with Exercise 2: Set Up Automation. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, in your project's Workflows, enable "Item closed" → Status: Done. Then, file a test issue in your fork. After that, close that issue. Finally, verify it moved to "Done" automatically in the project board. Think of 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 3: Create a Sprint View. What should a learner take away from it? + +**Alex:** Start with Exercise 3: Create a Sprint View. There is something to understand, something to try, and something that proves the try worked. + +**Alex:** First, add an Iteration field named "Sprint" with 2-week iterations. Then, assign your existing project items to the current sprint. After that, switch to Roadmap view - observe the items on the timeline. Finally, check Insights to see the current iteration burndown. Treat 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 4: Cross-Repo Project (Advanced). What should a learner take away from it? + +**Alex:** This is where Exercise 4: Cross-Repo Project (Advanced) becomes real: 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. That matters in practice: Next: Appendix S: Releases and Insights Back: Appendix Q: GitHub Actions Teaching chapter: Chapter 09: Labels, Milestones, and Projects. + +**Alex:** First, create a cross-repo project connected to two of your repositories. Then, add the Repository field to the Table view. After that, create a view filtered to is:issue label:accessibility. Finally, set up Auto-add: any issue with the accessibility label in those repos goes to this project automatically. 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 26. Next in the series is episode 27, where we keep building the same contributor muscles. + +
+ +--- + +### 26. Episode 27: Advanced Search + +GitHub search query language, qualifiers, and filtering for issues, PRs, and code. + +Based on: [Appendix N: Advanced Search](docs/appendix-n-advanced-search.md) + +Audio and transcript are being regenerated for this episode. + +
+Read Transcript - Episode 27: Advanced Search + +#### Transcript + +**Alex:** Welcome to episode 27 of Git Going with GitHub: Advanced Search. 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 GitHub search query language, qualifiers, and filtering for issues, PRs, and 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 Finding Anything Across All of GitHub: GitHub's search engine is powerful and underused. The next useful detail is this: 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. + +**Alex:** The next layer is this. Here is the plain-English version of 1. The Search Interface. GitHub's search is accessible from nearly any page. It 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. 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. + +**Jamie:** What is the one idea that makes the next few steps less mysterious? + +**Alex:** Start with Learning Cards: The Search Interface. 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 / 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. 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. + +--- + +**Alex:** Now bring the learner back to the room. Keep the learner anchored in 2. Search Scopes. By default, GitHub searches across all of GitHub. This is the part to say slowly: Example: repo:community-access/accessibility-agents in:title keyboard finds issues/PRs whose titles mention "keyboard" in the accessibility-agents repo. + +**Jamie:** What would you say to someone who is already bracing for this to be too much? + +**Alex:** The reason Going to the Issues search directly matters is that GitHub's issue/PR search is at github.com/issues (your issues) or github.com/pulls (your PRs). That gives the learner a simple foothold: the search bar there is pre-scoped to "repos you have access to involving you.". + +**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 Learning Cards: Searching Issues and Pull Requests. 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 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. 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. + +--- + +**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. Searching Code. Code search operates differently from issue search. Put another way, as of 2024, GitHub uses an improved code search engine (sometimes called "code search v2") with better indexing. + +**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 9. Practical Queries for This Workshop becomes real: bookmark these for use during the hackathon. + +**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:** Keep the learner anchored in 10. Saving and Reusing Searches. GitHub does not have a built-in saved-search feature, but you can. + +**Alex:** First, bookmark the URL - every search result page has the query in the URL. Bookmark it in your browser for instant re-run. Then, pin in notifications - if you're watching a repo, set up notification filters. After that, accessibility Agents - use /my-issues and /my-prs for your personal saved-search equivalents without leaving VS Code. 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 Example bookmarkable URL matters is that next: Appendix O: Branch Protection Back: Appendix M: Accessibility Standards Teaching chapter: Chapter 05: Working with Issues. 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 27. Next in the series is episode 28, where we keep building the same contributor muscles. + +
+ +--- + +### 27. Episode 10: Notifications and Mentions + +Managing your notification inbox, @mentions, and strategies for avoiding overload. + +Based on: [Chapter 10: Notifications and Mentions](docs/10-notifications-and-day-1-close.md) + + + +[Download Episode 10 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep10-notifications.mp3) + +
+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. + +**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. + +--- + +**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:** 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. + +--- + +**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. + +--- + +**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 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:** 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:** 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:** 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 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 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 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:** 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 10. Next in the series is episode 11, where we keep building the same contributor muscles. + +
+ +--- + +### 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 - 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:** 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:** 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 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:** 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:** 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:** 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:** 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:** 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:** 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:** 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:** 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. + +--- + +**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:** 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:** 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:** 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 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 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 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:** 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 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:** 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 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:** 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:** 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. + +--- + +**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 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. 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 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. 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 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. + +--- + +**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 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:** 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 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. + +**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:** 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 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:** 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 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:** 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 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:** 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 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 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. + +
+ +--- + +### 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 - Challenge bonus-d: Notifications + +#### 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:** 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 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 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:** 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 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. + +--- + +**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:** 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 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:** 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 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:** 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 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 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. + +--- + +**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 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. + +--- + +**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 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 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:** 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. + +
+ +--- + +## 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](docs/11-vscode-interface.md) + + + +[Download Episode 11 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep11-vscode-basics.mp3) + +
+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. + +--- + +**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 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:** 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). + +--- + +**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 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:** 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:** 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 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:** 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 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 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. + +--- + +**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:** 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. 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 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 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: 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. + +--- + +**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:** 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: 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:** 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. 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 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. 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 11. Next in the series is episode 12, where we keep building the same contributor muscles. + +
+ +--- + +### 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](docs/12-vscode-accessibility.md) + +Audio and transcript are being regenerated for this episode. + +
+Read Transcript - Episode 45: VS Code Accessibility Deep Dive + +#### 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. + +**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. + +**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:** 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:** 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 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. + +--- + +**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. + +--- + +**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 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:** 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 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. 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 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. 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 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:** 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 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 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 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 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 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. 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 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. 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 45. Next in the series is episode 46, where we keep building the same contributor muscles. + +
+ +--- + +### 32. Episode 21: Git Authentication + +Personal access tokens, SSH keys, credential storage, and commit signing. + +Based on: [Appendix D: Git Authentication](docs/appendix-d-git-authentication.md) + +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). + +--- + +**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:** 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 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 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. + +--- + +**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:** 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:** 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:** 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 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. 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 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:** 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. + +
+ +--- + +### 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](docs/13-how-git-works.md) + +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? + +--- + +**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:** 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. + +--- + +**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. + +--- + +**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). + +--- + +**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. + +--- + +**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. + +--- + +**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. + +--- + +**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. + +--- + +**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:** 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. + +--- + +**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:** 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 46. Next in the series is episode 47, where we keep building the same contributor muscles. + +
+ +--- + +### 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](docs/14-git-in-practice.md) + + + +[Download Episode 12 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep12-git-source-control.mp3) + +
+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? + +--- + +**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:** 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:** 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:** 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. + +--- + +**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:** 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 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:** 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:** 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 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:** 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. + +--- + +**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 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. + +--- + +**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 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. + +--- + +**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 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 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:** 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. + +--- + +**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:** 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:** 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:** 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:** 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:** 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:** 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 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:** 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 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:** 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:** 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. 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 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 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:** 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. 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 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 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 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. + +--- + +**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 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 12. Next in the series is episode 13, where we keep building the same contributor muscles. + +
+ +--- + +### 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 - 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. + +--- + +**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:** 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 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 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 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. + +--- + +**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 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. + +--- + +**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. + +**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:** 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:** 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. + +--- + +**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. + +--- + +**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:** 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. + +--- + +**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). + +--- + +**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? + +--- + +**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 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. + +--- + +**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 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. + +--- + +**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. + +--- + +**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. + +--- + +**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 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 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). + +--- + +**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 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. 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 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 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:** 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 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". + +--- + +**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 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. 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:** 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 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 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. + +--- + +**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:** 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. 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 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. + +--- + +**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:** 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. + +--- + +**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 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 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 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 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 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. 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 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:** 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:** 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:** 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 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 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 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 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:** 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. + +
+ +--- + +### 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 - Challenge bonus-e: Git History + +#### 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:** 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 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. + +**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? + +--- + +**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:** 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:** 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:** 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. + +--- + +**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:** 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 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:** 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:** 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:** 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:** 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 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. + +--- + +**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 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:** 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:** 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:** 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:** 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. + +--- + +**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:** 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:** 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 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 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:** 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. + +--- + +**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:** 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 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:** 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 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. + +
+ +--- + +### 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](docs/15-code-review.md) + + + +[Download Episode 13 (MP3)](https://github.com/Community-Access/git-going-with-github/releases/download/podcasts/ep13-github-prs-extension.mp3) + +
+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. + +--- + +**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 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:** 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 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:** 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 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 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. + +--- + +**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:** 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 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:** 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 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. + +--- + +**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. + +--- + +**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 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 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:** 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:** 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 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 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 - [Overview](#1-overview) diff --git a/docs/appendix-l-agents-reference.md b/docs/appendix-l-agents-reference.md index e983bdb..9d0780e 100644 --- a/docs/appendix-l-agents-reference.md +++ b/docs/appendix-l-agents-reference.md @@ -1,6 +1,6 @@ # Appendix L: Accessibility Agents Reference > -> **Listen to Episode 39:** [Accessibility Agents - Complete Reference](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 39:** [Accessibility Agents - Complete Reference](../admin/PODCASTS.md) - 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](19-accessibility-agents.md) | Also relevant: [Chapter 20](20-build-your-agent.md) > @@ -8,7 +8,7 @@ ## 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 16: Accessibility Agents](19-accessibility-agents.md). For Copilot keyboard shortcuts and Chat features, see [Appendix W: GitHub Copilot Reference](appendix-k-copilot-reference.md). +> 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](19-accessibility-agents.md). For Copilot keyboard shortcuts and Chat features, see [Appendix K: GitHub Copilot Reference](appendix-k-copilot-reference.md). ## Table of Contents @@ -1318,7 +1318,7 @@ This shows: which files were found, which were loaded, which have errors, and fr ## 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 W: GitHub Copilot & Agentic Reference](appendix-k-copilot-reference.md). +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](appendix-k-copilot-reference.md). ### Official accessibility.github.com Guides diff --git a/docs/appendix-m-accessibility-standards.md b/docs/appendix-m-accessibility-standards.md index b31520b..3d564b6 100644 --- a/docs/appendix-m-accessibility-standards.md +++ b/docs/appendix-m-accessibility-standards.md @@ -1,6 +1,6 @@ # Appendix M: Accessibility Standards Reference > -> **Listen to Episode 20:** [Accessibility Standards Reference](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 20:** [Accessibility Standards Reference](../admin/PODCASTS.md) - 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](08-open-source-culture.md) | Also relevant: [Chapter 12](12-vscode-accessibility.md) > diff --git a/docs/appendix-n-advanced-search.md b/docs/appendix-n-advanced-search.md index b409a9a..f4d9b4a 100644 --- a/docs/appendix-n-advanced-search.md +++ b/docs/appendix-n-advanced-search.md @@ -1,6 +1,6 @@ # Appendix N: GitHub Advanced Search > -> **Listen to Episode 27:** [Advanced Search](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 27:** [Advanced Search](../admin/PODCASTS.md) - 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](05-working-with-issues.md) | Also relevant: [Chapter 09](09-labels-milestones-projects.md) > diff --git a/docs/appendix-o-branch-protection.md b/docs/appendix-o-branch-protection.md index e743e26..5706034 100644 --- a/docs/appendix-o-branch-protection.md +++ b/docs/appendix-o-branch-protection.md @@ -1,6 +1,6 @@ # Appendix O: Branch Protection Rules and Repository Rulesets > -> **Listen to Episode 28:** [Branch Protection and Rulesets](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 28:** [Branch Protection and Rulesets](../admin/PODCASTS.md) - 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](08-open-source-culture.md) | Also relevant: [Chapter 14](14-git-in-practice.md) > diff --git a/docs/appendix-p-security-features.md b/docs/appendix-p-security-features.md index 3b5b1a0..f215f50 100644 --- a/docs/appendix-p-security-features.md +++ b/docs/appendix-p-security-features.md @@ -1,6 +1,6 @@ -# Appendix P: GitHub Security Features +# Appendix P: GitHub Security Features > -> **Listen to Episode 29:** [GitHub Security Features](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 29:** [GitHub Security Features](../admin/PODCASTS.md) - 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](08-open-source-culture.md) | Also relevant: [Chapter 17](17-issue-templates.md) > diff --git a/docs/appendix-q-actions-workflows.md b/docs/appendix-q-actions-workflows.md index 465e1ef..27e6589 100644 --- a/docs/appendix-q-actions-workflows.md +++ b/docs/appendix-q-actions-workflows.md @@ -1,6 +1,6 @@ # Appendix Q: GitHub Actions and Workflows > -> **Listen to Episode 34:** [GitHub Actions and Workflows](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 34:** [GitHub Actions and Workflows](../admin/PODCASTS.md) - 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](17-issue-templates.md) | Also relevant: [Chapter 19](19-accessibility-agents.md) > diff --git a/docs/appendix-r-projects-deep-dive.md b/docs/appendix-r-projects-deep-dive.md index 719e3d0..58807ca 100644 --- a/docs/appendix-r-projects-deep-dive.md +++ b/docs/appendix-r-projects-deep-dive.md @@ -1,6 +1,6 @@ # Appendix R: GitHub Projects Deep Dive > -> **Listen to Episode 26:** [GitHub Projects Deep Dive](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 26:** [GitHub Projects Deep Dive](../admin/PODCASTS.md) - 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](09-labels-milestones-projects.md) > diff --git a/docs/appendix-s-releases-tags-insights.md b/docs/appendix-s-releases-tags-insights.md index a5cee68..b00f857 100644 --- a/docs/appendix-s-releases-tags-insights.md +++ b/docs/appendix-s-releases-tags-insights.md @@ -1,6 +1,6 @@ # Appendix S: Releases, Tags, and Repository Insights > -> **Listen to Episode 25:** [Releases, Tags, and Insights](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 25:** [Releases, Tags, and Insights](../admin/PODCASTS.md) - 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](08-open-source-culture.md) > diff --git a/docs/appendix-t-community-and-social.md b/docs/appendix-t-community-and-social.md index f50d3d8..d6999c0 100644 --- a/docs/appendix-t-community-and-social.md +++ b/docs/appendix-t-community-and-social.md @@ -12,7 +12,7 @@ > -> **Listen to Episode 35:** [Profile, Sponsors, and Wikis](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 35:** [Profile, Sponsors, and Wikis](../admin/PODCASTS.md) - 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 @@ -228,7 +228,7 @@ Wiki pages automatically appear in a sidebar for navigation. ## GitHub Organizations and Templates > -> **Listen to Episode 36:** [Organizations and Templates](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 36:** [Organizations and Templates](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. ## A Contributor's Guide to GitHub's Structural Features diff --git a/docs/appendix-u-discussions-and-gists.md b/docs/appendix-u-discussions-and-gists.md index 076d9c6..b0e1266 100644 --- a/docs/appendix-u-discussions-and-gists.md +++ b/docs/appendix-u-discussions-and-gists.md @@ -12,7 +12,7 @@ > -> **Listen to Episode 24:** [GitHub Discussions](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 24:** [GitHub Discussions](../admin/PODCASTS.md) - 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 @@ -319,7 +319,7 @@ This works well for first-response drafts on Q&A threads or community questions ## GitHub Gists > -> **Listen to Episode 23:** [GitHub Gists](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 23:** [GitHub Gists](../admin/PODCASTS.md) - 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 diff --git a/docs/appendix-v-github-mobile.md b/docs/appendix-v-github-mobile.md index 990ffd4..debc524 100644 --- a/docs/appendix-v-github-mobile.md +++ b/docs/appendix-v-github-mobile.md @@ -1,6 +1,6 @@ # Appendix V: GitHub Mobile > -> **Listen to Episode 32:** [GitHub Mobile](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 32:** [GitHub Mobile](../admin/PODCASTS.md) - 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](05-working-with-issues.md) | Also relevant: [Chapter 10](10-notifications-and-day-1-close.md) > diff --git a/docs/appendix-w-github-pages.md b/docs/appendix-w-github-pages.md index 733276f..20edf3c 100644 --- a/docs/appendix-w-github-pages.md +++ b/docs/appendix-w-github-pages.md @@ -1,6 +1,6 @@ # Appendix W: Publishing with GitHub Pages > -> **Listen to Episode 33:** [Publishing with GitHub Pages](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 33:** [Publishing with GitHub Pages](../admin/PODCASTS.md) - 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](08-open-source-culture.md) | Also relevant: [Chapter 21](21-next-steps.md) > diff --git a/docs/appendix-x-resources.md b/docs/appendix-x-resources.md index 2cd93bc..180e917 100644 --- a/docs/appendix-x-resources.md +++ b/docs/appendix-x-resources.md @@ -1,6 +1,6 @@ # Appendix X: Resources > -> **Listen to Episode 38:** [Resources and Links](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 38:** [Resources and Links](../admin/PODCASTS.md) - 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 diff --git a/docs/appendix-y-workshop-materials.md b/docs/appendix-y-workshop-materials.md index a0f1dca..52b0f86 100644 --- a/docs/appendix-y-workshop-materials.md +++ b/docs/appendix-y-workshop-materials.md @@ -1,6 +1,6 @@ # Appendix Y: Accessing and Downloading Workshop Materials > -> **Listen to Episode 42:** [Accessing Workshop Materials](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 42:** [Accessing Workshop Materials](../admin/PODCASTS.md) - 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](00-pre-workshop-setup.md) > diff --git a/docs/appendix-z-github-skills.md b/docs/appendix-z-github-skills.md index 6632181..3e4ac32 100644 --- a/docs/appendix-z-github-skills.md +++ b/docs/appendix-z-github-skills.md @@ -1,6 +1,6 @@ # Appendix Z: GitHub Skills - Complete Course Catalog > -> **Listen to Episode 43:** [GitHub Skills - Complete Course Catalog](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 43:** [GitHub Skills - Complete Course Catalog](../admin/PODCASTS.md) - 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](00-pre-workshop-setup.md) | Also relevant: [Chapter 21](21-next-steps.md) > diff --git a/docs/course-guide.md b/docs/course-guide.md index c46f425..9851c09 100644 --- a/docs/course-guide.md +++ b/docs/course-guide.md @@ -1,6 +1,6 @@ # Course Guide > -> **Listen to Episode 0:** [Welcome to Git Going with GitHub](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. +> **Listen to Episode 0:** [Welcome to Git Going with GitHub](../admin/PODCASTS.md) - 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 @@ -13,15 +13,23 @@ 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. By the end of Day 1, you will have filed issues, opened pull requests, reviewed someone else's work, and resolved a merge conflict - all in the 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. By the end of Day 2, your name is in the commit history of a real open source accessibility project. +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 @@ -38,7 +46,7 @@ github.dev - VS Code on the web, no install needed Day 2 - Deepen with VS Code + Accessibility Agents VS Code basics → Copilot inline → Copilot Chat - @daily-briefing → @issue-tracker → @pr-review → @analytics → ship upstream + @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. @@ -46,6 +54,8 @@ Day 2 - Deepen with VS Code + Accessibility Agents ## Before You Begin +Start with **[Get Going with GitHub](get-going.md)** 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](00-pre-workshop-setup.md)** before Day 1. This chapter walks you through: - Creating a GitHub account @@ -61,7 +71,7 @@ Complete everything in **[Chapter 00: Pre-Workshop Setup](00-pre-workshop-setup. 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 all 44 episodes](../PODCASTS.md)** with HTML5 audio players +- **[Browse the podcast episodes](../admin/PODCASTS.md)** with HTML5 audio players - **[Subscribe via RSS](https://community-access.org/git-going-with-github/podcasts/feed.xml)** in your preferred podcast app - Episodes are 8-18 minutes each - perfect for commutes, walks, or screen reader breaks @@ -72,6 +82,7 @@ These chapters are designed to be read and practiced in order. Each builds on th | # | Chapter | What You Will Learn | Time | |---|---------|-------------------|------| +| [Start](get-going.md) | **Get Going with GitHub** | GitHub Classroom onboarding, Learning Room first steps, support, and tool choice | 15 min | | [00](00-pre-workshop-setup.md) | **Pre-Workshop Setup** | Install and configure everything before Day 1 | 30 min | | [01](01-choose-your-tools.md) | **Choose Your Adventure: A Tool Tour** | Explore the 5 tool environments before you start | 30 min | | [02](02-understanding-github.md) | **Understanding GitHub's Web Structure** | How GitHub is organized - page types, headings, landmarks, screen reader orientation | 1 hr | @@ -84,7 +95,7 @@ These chapters are designed to be read and practiced in order. Each builds on th | [09](09-labels-milestones-projects.md) | **Labels, Milestones and Projects** | Organize and cross-reference work | 45 min | | [10](10-notifications-and-day-1-close.md) | **Notifications and Day 1 Close** | Manage your inbox, @mentions, and subscriptions; recap Day 1 | 30 min | -**Day 1 Total:** ~8 hours of structured time +**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 @@ -105,7 +116,7 @@ Day 2 moves you from the browser to the desktop. Every skill maps directly to wh | [20](20-build-your-agent.md) | **Build Your Agent: Capstone** | Design, build, and contribute a real accessibility agent | 1.5 hrs | | [21](21-next-steps.md) | **What Comes Next** | Graduation, portfolio, continued learning, community | 30 min | -**Day 2 Total:** ~10 hours of structured time +**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 @@ -203,9 +214,9 @@ If you get stuck at any point during the workshop, these resources are always av | Resource | What It Is | When to Use It | |----------|-----------|---------------| -| [FAQ](admin/FAQ.md) | Answers to common questions | When you have a question about the workshop, GitHub, or screen readers | -| [Troubleshooting](../TROUBLESHOOTING.md) | Step-by-step solutions to common problems | When something is not working | -| [Quick Reference](../QUICK_REFERENCE.md) | Condensed shortcuts and commands | When you need a keyboard shortcut or command fast | +| [FAQ](../admin/FAQ.md) | Answers to common questions | When you have a question about the workshop, GitHub, or screen readers | +| [Troubleshooting](../admin/TROUBLESHOOTING.md) | Step-by-step solutions to common problems | When something is not working | +| [Quick Reference](../admin/QUICK_REFERENCE.md) | Condensed shortcuts and commands | When you need a keyboard shortcut or command fast | | [Glossary](appendix-a-glossary.md) | Term definitions | When you encounter an unfamiliar word | | [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 | @@ -221,7 +232,7 @@ If you get stuck at any point during the workshop, these resources are always av | **Tools** | Browser, screen reader | VS Code, Copilot, Accessibility Agents | | **Chapters** | 00-10 (11 chapters) | 11-21 (11 chapters) | | **Skills** | Navigate, Issue, PR, Review, Merge | Git, Copilot, Agents, Fork, Capstone | -| **Outcome** | You can use GitHub independently | Your name is in a real project's commit history | +| **Outcome** | You can use GitHub independently | You have a real contribution path and review process | | **Time** | ~8 hours | ~10 hours | diff --git a/docs/get-going.md b/docs/get-going.md new file mode 100644 index 0000000..faba541 --- /dev/null +++ b/docs/get-going.md @@ -0,0 +1,135 @@ +# 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](00-pre-workshop-setup.md). 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. If GitHub asks you to authorize GitHub Classroom, activate **Authorize GitHub Classroom**. +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. Activate **Accept this assignment**. +5. Wait while GitHub Classroom creates your private repository. +6. Refresh the page until the repository link appears. +7. 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. + +1. Open your Learning Room repository. +2. Navigate to the **Issues** tab. On GitHub, the keyboard shortcut is `G` then `I`. +3. Find an issue titled **Challenge 1: Find Your Way Around**. +4. Open the issue and read the body from top to bottom. +5. Follow the checklist in the issue. +6. Post your evidence in the evidence field or as the requested comment. +7. 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 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](solutions/). +- 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. I can find the Issues tab. +3. I can open Challenge 1. +4. I know where to post my evidence and how to ask for help. + +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](00-pre-workshop-setup.md) +2. [Chapter 01: Choose Your Tools](01-choose-your-tools.md) +3. [Chapter 02: Understanding GitHub](02-understanding-github.md) +4. [Chapter 03: Navigating Repositories](03-navigating-repositories.md) +5. [Chapter 04: The Learning Room](04-the-learning-room.md) +6. Your **Challenge 1: Find Your Way Around** issue in your Learning Room repository + +You belong here. We will keep the path explicit, and we will keep giving you the next step. diff --git a/docs/images/learning-room-tree.svg b/docs/images/learning-room-tree.svg index fc2e42f..0e905fa 100644 --- a/docs/images/learning-room-tree.svg +++ b/docs/images/learning-room-tree.svg @@ -1,10 +1,10 @@ - learning-room (SHARED) + learning-room-<username> (PRIVATE) ├── main branch (protected) - ├── Student A’s PR #12 (open, assigned to Student B for review) - ├── Student B’s PR #13 (open, assigned to Student C for review) - ├── Student C’s PR #14 (open, assigned to Student A for review) - ├── Student A’s PR #11 (merged, closed) - └── [More PRs as students contribute] + ├── Challenge issues (created sequentially by bot) + ├── learn/<username> branch (student work) + ├── Student PR #12 (open, Aria feedback) + ├── Peer simulation PR (optional review practice) + └── Facilitator feedback PR (GitHub Classroom) diff --git a/facilitator/FACILITATOR_GUIDE.md b/facilitator/FACILITATOR_GUIDE.md deleted file mode 100644 index a4f7ad8..0000000 --- a/facilitator/FACILITATOR_GUIDE.md +++ /dev/null @@ -1,307 +0,0 @@ -# Facilitator Guide and Workshop Timeline - -## Facilitator Team - -- **Jeff Bishop** -- lead facilitator, maintainer of [Accessibility Agents](https://github.com/community-access/accessibility-agents) -- **Michael Babcock** -- co-facilitator - -Both facilitators run all sessions together. "The facilitator" or "your facilitator" in this guide refers to whichever of the two is leading a given moment; either can step in for the other on any task in this guide. - -## Overview - -This is a **two-day workshop** designed for blind and low-vision students learning GitHub through hands-on collaboration. Each day runs approximately 8 hours with structured sessions and flexible working time. - -**Format:** Hybrid (streaming + individual GitHub Classroom repos) -**Main Goal:** Get every student to merge their first pull request - -> **Deployment note:** For setup instructions, see [classroom/README.md](../classroom/README.md). -> Each student receives their own private repository through GitHub Classroom. -> The Aria bot and student-progression workflow handle challenge delivery and feedback automatically. - -## Before the Workshop (Day Before) - -### Facilitator Checklist - -- [ ] Verify GitHub Classroom roster is complete (all students accepted invite links) -- [ ] Confirm both assignments are published and invite links work -- [ ] Test Aria bot validation by submitting a practice PR in a test repo -- [ ] Verify student-progression workflow triggers correctly (close Challenge 1, see Challenge 2 appear) -- [ ] Share meeting link and reminder email with: - - Video call link + audio-only option - - Pre-workshop setup reminder (see [docs/00-pre-workshop-setup.md](../docs/00-pre-workshop-setup.md)) - - FAQ: "What if I get stuck?" - - Office hours/emergency contact info - -### Verify Infrastructure - -Use the **GitHub Classroom dashboard** to confirm: - -1. All students have accepted their assignment invite links -2. Each student's private repo was created successfully -3. Challenge 1 issue exists in each student repo (auto-created on acceptance) - -Test the automation by opening a PR in one student repo and confirming: - -- Aria bot comments with feedback within 30 seconds -- Closing Challenge 1 issue triggers Challenge 2 to appear - -## Day 1: GitHub Orientation and First Pull Request - -### Hour 1: Welcome and GitHub Orientation (60 min) - -**Facilitator Role:** - -- Create welcoming opening acknowledging everyone's accessibility needs -- Explain why GitHub matters for blind/low-vision inclusion -- Demonstrate: "I'm going to open the repo right now and you'll follow along" -- Q&A in chat -- answer every question - -**What Students Do:** - -- Join the video call with screen reader -- Open GitHub in their browser -- Navigate to their private repo (created by GitHub Classroom) -- Confirm they can see their first challenge issue - -**Resources to Have Ready:** - -- Screen reader cheatsheet (Appendix B) -- Common GitHub.com keyboard shortcuts -- Chat moderator who watches for questions - -**Success Metric:** All students report "I found my issue" - -### Hour 2: Demo -- Your First PR (30 min) - -**You (facilitator) will:** - -1. Show a completed example on screen with narration -2. Walk through EVERY step: - - "First, I click the edit pencil" - - "I see the markdown editor open" - - "I make my change here" - - "I scroll down and create a new branch" - - "Now I click 'Propose changes' button" - - "GitHub shows me the PR preview -- notice the Aria bot already right here checking my work" - - "I fill in the PR template fields" - - "I click 'Create Pull Request'" - - "Aria comments within 30 seconds with feedback" - - "I address the feedback and push an update commit" - - "I request review by typing @peer_username" - - "My peer reviews and I get approval" - - "I click merge button" - - "Done! My PR is merged!" - -**This is the workflow EVERY student will repeat.** Make it crystal clear. - -**Success Metric:** Students report "I see how this works" in chat - -### Hours 2-6: Working Session (approx. 4.5 hours) - -**Students work independently on challenges in their own repos.** - -This is THE MAIN ENGAGEMENT. They're making their first real contribution. When a student closes a challenge issue, the student-progression workflow automatically opens the next one. - -**Facilitator Role:** - -- Monitor the GitHub Classroom dashboard for student progress -- Check individual student repos for PR comments and questions -- Respond quickly to blockers -- Celebrate each merged PR in chat - -**Expected Cadence:** - -- **First hour** -- Students opening issues, starting edits (expect early PRs from fast movers) -- **Second hour** -- Aria bot feedback flowing, students making fixes -- **Third hour** -- Reviews happening, merges happening, progression bot unlocking new challenges -- **Fourth hour** -- Stragglers finishing, peer reviews catching up - -**Facilitator Interventions:** - -If a student hasn't opened a PR after the first hour: - -- Message them: "Hey @student! Need help getting started? Check your Issues tab for your current challenge." -- Keep it low-pressure -- some students will take longer - -If Aria gives critical feedback: - -- Explain what the bot meant in plain language -- Show the fix clearly -- Make sure the student isn't discouraged - -If a peer review isn't happening: - -- Offer to do a facilitator review instead -- Or ask another student: "Can you review this PR?" -- Priority is getting to merge, not strict peer review - -**Celebrate Merges:** -Post in the chat or discussion when a student merges their first PR. Public recognition matters. - -### Hour 7: Q&A and Reflection (30 min) - -**Prompt for Discussion:** - -> "Tell us in chat: What was one thing you learned today about GitHub?" - -**Be ready to:** - -- Answer "I got an error..." questions -- Help troubleshoot remaining issues -- Give credit to peer reviewers -- Mark students who didn't finish but are close as "follow-up needed" - -**Send them home with:** - -- Tomorrow's agenda -- Sneak peek at what's next (VS Code, local Git, advanced challenges) -- Encouragement! - -### Hour 8: Office Hours (Optional) - -- Available for 1:1 troubleshooting -- Help students finish PRs -- Answer "How do I...?" questions about GitHub -- Document common questions for tomorrow's content - -## Day 2: Deeper Skills and Celebration - -### Hour 1: Recap and Wins (30 min) - -**Facilitator:** - -- Show stats from the GitHub Classroom dashboard: "X students, Y PRs merged on Day 1" -- Acknowledge students who got stuck but persisted -- Introduce the Day 2 assignment (students accept the second invite link) - -> Students accept the Day 2 assignment invite link now. -> The student-progression workflow begins delivering Challenge 10 onwards. - -### Hour 2: Deep Dive -- Code Review (60 min) - -**Teach:** - -- How to review someone else's PR -- What good feedback looks like -- How to incorporate feedback gracefully -- Real-world code review practices - -**Paired Activity:** - -- Have students review each other's Day 1 PRs -- Start with example feedback you provide -- Let them practice the async review process - -### Hours 3-7: Skill-Building Challenges (approx. 4.5 hours) - -**Students work through progressively harder challenges delivered by the progression bot:** - -| Track | Challenges | Topics | -|-------|-----------|--------| -| Core Day 2 | 10-13 | VS Code, Git basics, local commits, code review | -| Advanced | 14-16 | Issue templates, fork-and-contribute, capstone agent | -| Bonus | bonus-a through bonus-e | Advanced search, branch protection, GitHub CLI, cloud editors | - -Challenges unlock automatically as students close issues. Faster students will reach bonus challenges; slower students may still be working through core content. Both paces are valid. - -**Aria Bot Enhances:** - -- Accessibility feedback becomes more detailed on later challenges -- Highlights larger patterns ("You capitalized but others use lowercase") -- Suggests improvements, not just fixes - -**Facilitator Role:** - -- Use the Classroom dashboard to track who's advancing through challenges -- Give encouragement to students on later challenges -- Help students with merge conflict resolution (Challenge 7 / autograder) -- Keep the energy positive - -### Hour 7: Final Q&A and Celebration (60 min) - -**Metrics to share (pull from Classroom dashboard):** - -- Total students enrolled - -- PRs merged (track real number) -- Students who completed multiple challenges -- Students who completed the code review cycle -- Accessibility wins -- screen readers worked throughout - -**Next Steps:** - -- Point them to CONTRIBUTING.md in their favorite open source projects -- Share list of "good first issue" finding techniques -- Give them the resources appendices -- Offer alumni community channel - -### Hour 8: Informal Hangout (60 min) - -- Students hang out on the call -- Chat with peers and facilitators -- Ask follow-up questions -- Exchange GitHub usernames - -## Facilitator Role Critical Points - -### Communication Style - -**DO:** - -- Use simple language: "Click the pencil icon to edit" -- Narrate exactly what you're doing: "I'm clicking... now I'm typing..." -- Normalize mistakes: "Oops I forgot something - let me fix it" -- Celebrate effort not just success: "Nice work thinking through that!" -- Answer the same question multiple times patiently - -**DON'T:** - -- Use "obviously" or assume prior knowledge -- Assume everyone is on the same screen area -- Rush through demos -- Make anyone feel bad about getting stuck -- Focus on speed - focus on understanding - -### Responding to Common Issues - -| Student Says | Your Response | -|-------------|--------------| -| "I can't see my assignment issue" | Have them go to Issues tab, filter by Assignee > Me, or give direct link | -| "The bot is confusing me" | Ask what part confused them, then explain in plain language | -| "I don't know what [jargon] means" | Explain, then add it to glossary so next student finds it | -| "I accidentally merged the wrong thing" | No big deal - revert commit, explain it, move on | -| "My screen reader stops at the file picker" | Have them use keyboard: Tab to button, Space to open, Type filename | -| "I'm done - what's next?" | Option 1: Do another challenge. Option 2: Review someone's PR. Option 3: Help a peer. | - -### End of Workshop Facilitator Duties - -1. **Export metrics** - Use progress tracker to generate final report -2. **Write thank you email** - Personal note to each student (use template) -3. **Create alumni channel** - Slack/Discord for ongoing support -4. **Document what worked** - Feedback for next workshop -5. **Tag students in commit credit** - Add to CONTRIBUTORS file - -## Emergency Protocols - -### Bot stops responding to PRs - -- Check GitHub Actions status page -- Manually review PRs and comment with feedback format bot would use -- Post in Discussions: "Facing technical issue, we'll handle this manually" - -### Student GitHub account locked - -- Have them reset password via GitHub -- Or create temporary escalation issue for them to move forward - -### Video call connectivity issues - -- Have phone dial-in number as backup -- Offer to continue in Discussions if needed -- Record session for students who lose connection - -### Workshop needs to end early - -- Stop at natural break point -- Students can continue async after -- No one forced offline mid-PR diff --git a/generate-audio.bat b/generate-audio.bat new file mode 100644 index 0000000..8374aac --- /dev/null +++ b/generate-audio.bat @@ -0,0 +1,69 @@ +@echo off +setlocal enabledelayedexpansion + +:: --------------------------------------------------------------------------- +:: generate-audio.bat +:: Generate podcast audio for all episodes or a specific range. +:: +:: Usage: +:: generate-audio.bat -- generate all 75 episodes +:: generate-audio.bat 5 -- generate episodes 5 and above +:: generate-audio.bat 5 10 -- generate episodes 5 through 10 +:: +:: Audio format, voice models, and pitch are read from: +:: podcasts\tts\voice-config.ini +:: --------------------------------------------------------------------------- + +:: Move to the repo root (the folder that contains this bat file) +cd /d "%~dp0" + +:: Ensure ffmpeg is on the PATH (winget installs to a versioned subfolder) +where ffmpeg >nul 2>&1 +if errorlevel 1 ( + echo [INFO] ffmpeg not found on PATH - refreshing from machine environment... + for /f "usebackq tokens=*" %%P in (`powershell -NoProfile -Command ^ + "[System.Environment]::GetEnvironmentVariable('Path','Machine')"`) do ( + set "PATH=%%P;%PATH%" + ) + where ffmpeg >nul 2>&1 + if errorlevel 1 ( + echo [WARN] ffmpeg still not found. MP3 output may fail. + echo Install ffmpeg: winget install --id Gyan.FFmpeg + ) +) + +:: Build the optional --start / --end arguments +set "RANGE_ARGS=" +if not "%~1"=="" ( + set "RANGE_ARGS=--start %~1" +) +if not "%~2"=="" ( + set "RANGE_ARGS=!RANGE_ARGS! --end %~2" +) + +echo. +echo ============================================================ +echo Podcast Audio Generator +echo Config : podcasts\tts\voice-config.ini +if defined RANGE_ARGS ( + echo Range : %RANGE_ARGS% +) else ( + echo Range : all episodes +) +echo ============================================================ +echo. + +:: Run the Python batch generator. +:: generate_all.py already prints "Generating episode N/total: " as it works. +set "PYTHONPATH=%CD%" +python -m podcasts.tts.generate_all %RANGE_ARGS% + +if errorlevel 1 ( + echo. + echo [ERROR] Audio generation finished with errors. Check output above. + exit /b 1 +) + +echo. +echo [DONE] Audio generation complete. +exit /b 0 diff --git a/generate-transcripts.bat b/generate-transcripts.bat new file mode 100644 index 0000000..385e715 --- /dev/null +++ b/generate-transcripts.bat @@ -0,0 +1,62 @@ +@echo off +setlocal + +:: --------------------------------------------------------------------------- +:: generate-transcripts.bat +:: Generate reviewable draft podcast transcript scripts from the catalog. +:: +:: Transcripts are written to podcasts\scripts\ as ep*.txt / cc-*.txt files. +:: These are the input files consumed by generate-audio.bat. +:: +:: Note: transcript generation always rebuilds ALL episodes from the catalog. +:: Range selection is not supported at this stage. +:: +:: Usage: +:: generate-transcripts.bat +:: --------------------------------------------------------------------------- + +:: Move to the repo root (the folder that contains this bat file) +cd /d "%~dp0" + +echo. +echo ============================================================ +echo Podcast Transcript Generator +echo Output : podcasts\scripts\ +echo Rebuilds all episode and challenge scripts from catalog +echo ============================================================ +echo. + +:: Validate the catalog before generating +echo [1/3] Validating podcast catalog... +call npm run validate:podcasts --silent +if errorlevel 1 ( + echo [ERROR] Catalog validation failed. Fix errors above before generating transcripts. + exit /b 1 +) + +:: Build episode and challenge bundles (metadata used by transcript generator) +echo [2/3] Building episode and challenge bundles... +call npm run build:podcast-bundles --silent +if errorlevel 1 ( + echo [ERROR] Bundle build failed. + exit /b 1 +) +call npm run build:podcast-challenge-bundles --silent +if errorlevel 1 ( + echo [ERROR] Challenge bundle build failed. + exit /b 1 +) + +:: Generate the transcript scripts +echo [3/3] Generating transcript scripts... +call npm run generate:podcast-transcripts +if errorlevel 1 ( + echo. + echo [ERROR] Transcript generation finished with errors. Check output above. + exit /b 1 +) + +echo. +echo [DONE] Transcript scripts written to podcasts\scripts\ +echo Run generate-audio.bat to synthesise audio from these scripts. +exit /b 0 diff --git a/html/ACCESSIBILITY_TESTING.html b/html/ACCESSIBILITY_TESTING.html deleted file mode 100644 index 931bdc5..0000000 --- a/html/ACCESSIBILITY_TESTING.html +++ /dev/null @@ -1,401 +0,0 @@ - - - - - - - Accessibility Testing Checklist - GIT Going with GitHub - - - - - - - - -
-

Accessibility Testing Checklist

-

Verify GitHub Templates & Workflows Are Accessible

-

This checklist helps you test issue templates, PRs, and GitHub workflows to ensure they're usable by people with disabilities (especially screen reader users).

-

Quick Checklist for Templates

-

Use before deploying any new issue template or form.

-

Form Fields & Labels

-
    -
  • Every form field has a visible label
    • -
  • Label text is clear and describes what's needed (not "Please enter")
    • -
  • Required fields are marked and announced as required
    • -
  • Help text is associated with each field (not just placeholder text)
    • -
  • No fields rely on color alone to indicate required/error status
    • -
-

Form Structure

-
    -
  • Form inputs are in logical order (top to bottom)
    • -
  • Dropdown options are readable and include blank option or instruction
    • -
  • Checkboxes and radio buttons are grouped and labeled
    • -
  • No more than 6-8 required fields (reduces cognitive load)
    • -
  • Preview or review step before submission (allows verification)
    • -
-

Instructions & Guidance

-
    -
  • Markdown section explains what's needed and why
    • -
  • Instructions use simple language (8th grade reading level)
    • -
  • Headings are in order (H2, H3, H4 - not H2, H4)
    • -
  • Links have descriptive text (not "click here")
    • -
  • Code examples are formatted clearly (not in plain text)
    • -
-

YAML & Technical

-
    -
  • YAML passes syntax validation (https://www.yamllint.com/)
    • -
  • No trailing spaces or mixed indentation
    • -
  • All required fields present: name:, description:, body:
    • -
  • Field IDs are unique and lowercase with hyphens (e.g., browser_type)
    • -
-

Screen Reader Testing Workflow

-

Before Testing

-
    -
  1. Prepare: Have form open in browser with screen reader ready
    2. -
  2. Choose: Test with NVDA (Windows), JAWS (Windows), or VoiceOver (macOS)
    3. -
  3. Record: Note any issues for fixing
    4. -
-

NVDA Testing (Windows)

-
1. Press NVDA+Space to enable browse mode on page
-2. Press H to navigate to first heading
-3. Use H repeatedly to scan all headings (should be H1 → H2 → H3, not jumps)
-4. Press B to find buttons, forms
-5. Navigate to form field: Tab or arrow keys
-6. Screen reader should announce:
-   "[Label text] [field type] [required if applicable]"
-   Example: "Email address edit text, required"
-7. Tab through every field in order
-8. Check Tab order makes sense (left-to-right, top-to-bottom)
-9. Verify instructions between fields are heard
-

What to listen for:

-
    -
  • Every field label is announced
    • -
  • "Required" is announced for required fields
    • -
  • No fields are skipped
    • -
  • Field types are clear (edit text, dropdown, checkbox, etc.)
    • -
  • Help text is read before or near the field
    • -
-

JAWS Testing (Windows)

-
1. Press Spacebar to enter browse mode
-2. Press Insert+F6 to open headings list
-   - Verify headings are in order (1 → 2 → 3, no jumps)
-   - Close list (Escape)
-3. Press Insert+F5 to open forms list
-   - Should see every field
-   - Close list
-4. Tab through form field by field
-5. JAWS should announce:
-   "[Label] [field type] [required if applicable]"
-6. Press Insert+Down to read entire form (simulates form-scanning)
-

What to listen for:

-
    -
  • Form start is announced
    • -
  • All fields are listed in Forms List
    • -
  • Required fields say "required"
    • -
  • Field order matches logical reading order
    • -
  • No unlabeled fields
    • -
-

VoiceOver Testing (macOS)

-
1. Press VO+U to open Web Rotor
-2. Navigate to Form Controls section
-   - Should list all fields
-   - Verify count matches expected fields
-3. Navigate to Headings section
-   - Check heading hierarchy (no jumps)
-4. Press VO+Right arrow to move through page
-   - Should hear each field label before field
-5. Press VO+Space on field to interact
-6. VoiceOver should announce:
-   "[Label], [field type] [required if applicable]"
-

What to listen for:

-
    -
  • Rotor shows all form controls
    • -
  • Heading levels are correct (no 1 → 3 jumps)
    • -
  • Field labels are adjacent to fields
    • -
  • Instructions are readable
    • -
-

Accessibility Testing by Component

-

Checkboxes & Radio Buttons

-
    -
  • Grouped label describes the entire group
    • -
  • Individual labels describe each option
    • -
  • Screen reader announces number of options
    • -
  • Example: Screen reader says: "Browser, radio button group, 3 items. Chrome, radio button, not selected"
    • -
-

Test: Tab to group, use arrow keys to select. Screen reader should guide you clearly.

- -
    -
  • Visible label above or adjacent to dropdown
    • -
  • Dropdown shows currently selected value
    • -
  • Opening dropdown announces all options (or "expandable menu")
    • -
  • Options include instruction or blank option if optional
    • -
  • Focus style is visible (not invisible on dark backgrounds)
    • -
-

Test: Tab to dropdown, press Down/Space to open, arrow through options.

- -
    -
  • Link text describes where it goes (not "click here", "link", "read more")
    • -
  • Button text describes what happens (not "submit", "go", "continue")
    • -
  • Focuses visible with keyboard (Tab key shows clear highlight)
    • -
  • No links that are only images (images need alt text)
    • -
-

Test: Press Tab to navigate, read labels aloud.

-

Text Fields (Input, Textarea)

-
    -
  • Label directly associated with field (via label tag or aria-label)
    • -
  • Placeholder text is NOT a substitute for label
    • -
  • Example: Bad: Empty field with gray "Enter email" (disappears when you type)
    • -
  • Example: Good: Visible label "Email address:" + field
    • -
-

Test: Tab to field, screen reader announces label, then focus moves into field.

-

Instructions & Help Text

-
    -
  • Help text appears visually near the field
    • -
  • Help text is announced by screen reader (not hidden)
    • -
  • Instructions use simple language
    • -
  • No abbreviations without explanation
    • -
-

Test: Tab to field, screen reader should announce label, field type, help text, and required status.

-

Color & Contrast Testing

-
    -
  • Text contrast is 4.5:1 or higher (WCAG AA for normal text)
    • -
  • Color is not the only way to show information
      -
    • Example: Bad: "Red fields are errors" (only color indicates error)
      • -
    • Example: Good: "Error" label + red color + error icon
      • -
    -
    • -
  • Required fields marked with or "required" text (not just color)
    • -
  • Disabled fields are visually distinct
    • -
-

Test: Use WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/

-

Keyboard Navigation Testing

-

Test WITHOUT using the mouse.

-
    -
  • Tab key navigates to all interactive elements
    • -
  • Tab order follows logical reading order (left-to-right, top-to-bottom)
    • -
  • Shift+Tab goes backwards
    • -
  • Focus indicator is visible (not hidden or very faint)
    • -
  • Can activate buttons with Enter or Space
    • -
  • Can select radio buttons and checkboxes with arrow keys
    • -
  • Can open dropdowns with Space or Down arrow
    • -
  • Can submit form with Enter from submit button
    • -
-

Test: Close trackpad, use Tab/Shift+Tab/Enter/Space only.

-

Mobile & Responsive Testing

-
    -
  • Form is readable on small screens (mobile, tablet)
    • -
  • Form is usable with touch (buttons large enough: 44x44px minimum)
    • -
  • Form labels don't disappear on narrow screens
    • -
  • Touch targets don't overlap
    • -
  • No horizontal scrolling required to use form
    • -
-

Test: Resize browser to mobile width (375px), or use phone/tablet to fill form.

-

Multilingual & Plain Language Testing

-
    -
  • Instructions use simple, clear language (avoid jargon)
    • -
  • No unexplained abbreviations (spell out first use, then abbreviate)
    • -
  • Text can be enlarged to 200% without breaking layout
    • -
  • If translated, consider cultural appropriateness of images/phrasings
    • -
-

Test: Select browser zoom 200% (Ctrl+Plus / Cmd+Plus), or use browser reader mode.

-

Testing Checklist Summary

-

Before Deploying (Must-Have)

-
    -
  • All form fields have labels
    • -
  • Required fields marked and announced
    • -
  • Tab order is logical
    • -
  • Focus styles are visible
    • -
  • Color contrast is adequate (4.5:1 minimum)
    • -
  • Heading hierarchy is correct
    • -
  • YAML syntax is valid
    • -
-

Before Workshop/Training (Should-Have)

-
    -
  • Tested with at least 1 screen reader (NVDA, JAWS, or VoiceOver)
    • -
  • Keyboard-only workthrough (no mouse)
    • -
  • Mobile/responsive check
    • -
  • Plain language review
    • -
-

Best Practice (Nice-to-Have)

-
    -
  • Tested with all 3 screen readers
    • -
  • Tested with multiple browsers (Chrome, Firefox, Safari, Edge)
    • -
  • Tested with actual users with disabilities
    • -
  • Performance tested (forms load quickly)
    • -
-

Common Accessibility Failures & How to Test Them

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FailureWhat to CheckHow to Detect
No field labelsScreen reader announces field but not what it's forTab to field; screen reader should say "[Label] [field type]"
Bad heading hierarchyHeading jumps from H1 to H3 (confusing outline)Use screen reader heading list (NVDA: not in list)
Color-only errorsError only shown in red, not marked with textAdd error to optional field; look for text + color
Invisible focusCan't see which element has keyboard focusTab through form; focus outline should be clear
Unlabeled fieldsDropdown or input has no visible/announced nameTab to field; screen reader says "(blank)"
Links say "click here"Not descriptive; screen reader only hears "click here"Read link text aloud; should make sense out of context
No skip linkCan't skip repetitive navigationPress Tab to first element; should offer "skip to content"
-

Testing Tools & Resources

-

Automated Testing

- -

Manual Testing

- -

Feedback

- -

After Testing: Recording Issues

-

When you find an accessibility problem, document it:

-
Title: [Accessibility] Form label missing on email field
-
-Description:
-When tabbing to the email input on the issue template, the screen reader 
-announces "edit text, required" but does not announce what the field is for.
-
-Steps to reproduce:
-1. Open [template file/page]
-2. Tab to email field
-3. Listen to screen reader announcement
-
-Expected:
-Screen reader should announce: "Email address, edit text, required"
-
-Actual:
-Screen reader announces: "Edit text, required"
-
-Screen reader tested: NVDA 2025.3.3
-Browser: Chrome 130
-OS: Windows 11
-

Testing the Built HTML Output

-

This repository includes a build system that converts all Markdown files to HTML (see BUILD.md). If participants will use the HTML versions, test them separately:

-

Heading Hierarchy

-
    -
  • Each HTML page has exactly one <h1> element
    • -
  • Heading levels don't skip (no <h1> → <h3> jumps)
    • -
  • Navigation footers don't break the heading outline
    • -
- -
    -
  • Internal links resolve correctly (.md links are converted to .html)
    • -
  • Anchor links (#section-name) scroll to the correct position
    • -
  • External links open and are not broken
    • -
-

Landmark Structure

-
    -
  • The <main> element wraps the primary content
    • -
  • Navigation elements are properly structured
    • -
  • Screen reader can identify page regions using landmarks (D key in NVDA/JAWS)
    • -
-

Validation

-
    -
  • Run pages through the W3C HTML Validator - check for errors
    • -
  • Run pages through WAVE - check for accessibility errors
    • -
  • Verify syntax-highlighted code blocks are readable (not color-only)
    • -
-

Quick test: Open html/index.html in a browser, enable your screen reader, and navigate using H (headings) and K (links). Every heading and link should be announced clearly.

-

Questions or Feedback?

-
    -
  • Having trouble testing? See TROUBLESHOOTING.md
    • -
  • Need screen reader help? See docs/appendix-b-screen-reader-cheatsheet.md
    • -
  • Want resources? See docs/appendix-u-resources.md
    • -
-

Last updated: February 2026
Accessibility is foundational to inclusive workflows.

- -
- - - \ No newline at end of file diff --git a/html/BATCH.html b/html/BATCH.html new file mode 100644 index 0000000..d8c67d2 --- /dev/null +++ b/html/BATCH.html @@ -0,0 +1,200 @@ + + + + + + + Batch Command Reference - GIT Going with GitHub + + + + + + + + +
+

Batch Command Reference

+

This file documents the cmd.exe batch files in the repo root for podcast operations. +All batch files change directory to the repo root automatically, so they work correctly +from any location.

+

Workflow order

+

Run operations in this sequence for a full podcast build from scratch:

+
    +
  1. generate-transcripts.bat - write episode scripts from the catalog
    2. +
  2. generate-audio.bat - synthesise MP3 audio from those scripts
    3. +
  3. build-rss-feed.bat - generate the RSS feed and podcast listing
    4. +
  4. validate-rss-feed.bat - verify the feed is valid before publishing
    5. +
+

generate-transcripts.bat

+

Validates the podcast catalog, builds episode and challenge bundles, then writes +all episode and challenge coach scripts to podcasts\scripts\.

+
generate-transcripts.bat
+

Output files: podcasts\scripts\ep*.txt and podcasts\scripts\cc-*.txt

+

Note: transcript generation always rebuilds all episodes from the catalog. +Range selection is not supported at this stage. Run this step whenever the +catalog or source docs change.

+

generate-audio.bat

+

Synthesises MP3 audio for all episodes or a specific numbered range. +Audio format, voice model, pitch, and speed settings are read from +podcasts\tts\voice-config.ini.

+

The script echoes each episode name and index as it is processed. +ffmpeg is required for MP3 output and is located automatically from the +machine PATH, including after a fresh winget install.

+
generate-audio.bat                  generate all 75 episodes
+generate-audio.bat 5                generate episodes 5 and above
+generate-audio.bat 5 10             generate episodes 5 through 10
+

Output files: podcasts\audio\*.mp3

+

To change audio format, voice pitch, or speed, edit podcasts\tts\voice-config.ini +before running this command.

+

build-rss-feed.bat

+

Generates the RSS 2.0 / iTunes-compatible podcast feed and the admin podcast listing. +Reads MP3 file sizes from podcasts\audio\ and episode metadata from the catalog.

+
build-rss-feed.bat
+

Output files:

+
    +
  • podcasts\feed.xml - the RSS feed for podcast directories
    • +
  • admin\PODCASTS.md - human-readable episode listing
    • +
+

Run this command after generate-audio.bat completes so that enclosure lengths +reflect the final MP3 file sizes.

+

validate-rss-feed.bat

+

Runs local RSS 2.0 and iTunes compliance checks on podcasts\feed.xml.

+
validate-rss-feed.bat
+

Checks performed:

+
    +
  • Required channel elements: title, link, description, language
    • +
  • Required per-item elements: title, enclosure, guid
    • +
  • Enclosure URL, byte length, and MIME type
    • +
  • Duplicate GUID detection
    • +
+

Run build-rss-feed.bat first. The validator exits with a non-zero code on +any failure so it can be used in CI scripts.

+

Configuration file

+

podcasts\tts\voice-config.ini controls all audio generation settings.

+

The following table lists the available settings.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionExample
male_modelPiper ONNX model file for the male voice (Alex)en_US-ryan-high.onnx
female_modelPiper ONNX model file for the female voice (Jamie)en_US-lessac-high.onnx
male_pitch_semitonesPitch shift in semitones for the male voice-2
female_pitch_semitonesPitch shift in semitones for the female voice2
speech_rateWords per minute (passed to Piper)180
episode_audio_formatOutput format: wav, mp3, or bothmp3
+

npm scripts

+

The batch files wrap these npm scripts. They can also be run directly from +a PowerShell or bash session at the repo root.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
npm scriptDescription
npm run validate:podcastsValidate the podcast catalog
npm run generate:podcast-transcriptsGenerate transcript scripts
npm run build:podcast-audioGenerate audio (all episodes)
npm run build:podcast-siteBuild RSS feed and podcast listing
npm run validate:podcast-feedValidate the RSS feed
+

To pass a range to the audio build from npm:

+
npm run build:podcast-audio -- --start 5 --end 10
+ +
+ + + + diff --git a/html/BUILD.html b/html/BUILD.html index 170840e..02a2b80 100644 --- a/html/BUILD.html +++ b/html/BUILD.html @@ -172,5 +172,6 @@

Additional Resources

GIT Going with GitHub - A workshop by Community Access

View on GitHub · community-access.org

+ - \ No newline at end of file + diff --git a/html/CODE_OF_CONDUCT.html b/html/CODE_OF_CONDUCT.html index 584212e..3f6af14 100644 --- a/html/CODE_OF_CONDUCT.html +++ b/html/CODE_OF_CONDUCT.html @@ -125,5 +125,6 @@

Attribution

GIT Going with GitHub - A workshop by Community Access

View on GitHub · community-access.org

+ - \ No newline at end of file + diff --git a/html/COMING_SOON.html b/html/COMING_SOON.html index 93cbb9c..09ed211 100644 --- a/html/COMING_SOON.html +++ b/html/COMING_SOON.html @@ -76,5 +76,6 @@

Questions?

GIT Going with GitHub - A workshop by Community Access

View on GitHub · community-access.org

+ - \ No newline at end of file + diff --git a/html/COMPREHENSIVE_VALIDATION_AUDIT.html b/html/COMPREHENSIVE_VALIDATION_AUDIT.html deleted file mode 100644 index b0470da..0000000 --- a/html/COMPREHENSIVE_VALIDATION_AUDIT.html +++ /dev/null @@ -1,1516 +0,0 @@ - - - - - - - Comprehensive Validation Audit: Chapters 4-16 Student Challenges - GIT Going with GitHub - - - - - - - - -
-

Comprehensive Validation Audit: Chapters 4-16 Student Challenges

-

Date: March 5, 2026
Scope: Chapters 4-16 challenge definitions, documentation, templates, and associated files
Auditor: GitHub Copilot
Status: Complete audit with critical findings

-

Executive Summary

-

All 13 chapters (4-16) have challenge content defined with generally clear instructions, accessible documentation, and appropriate difficulty progression. However, several critical and medium-priority issues require remediation before student deployment.

-

Overall Status by Chapter

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ChapterTitleStatusPriority Issues
Ch 4Working with IssuesPASSNo issues found
Ch 5VS Code AccessibilityWARNKeyboard shortcut consistency; VoiceOver parity
Ch 6Working with Pull RequestsPASSNo issues found
Ch 7Merge ConflictsPASSNo issues found
Ch 8Culture & EtiquetteWARNOptional challenge lacks clarity on evaluation
Ch 9Labels/Milestones/ProjectsPASSNo critical issues
Ch 10NotificationsWARNTime estimate may be optimistic; screen reader testing needed
Ch 11Git & Source ControlWARNTime estimates may be low for beginners; repository complexity
Ch 12GitHub PR ExtensionWARNWrite access assumption; authentication flow clarity
Ch 13GitHub CopilotWARNCopilot subscription assumption not flagged upfront
Ch 14Accessible Code ReviewPASSWells structured with good "If You Get Stuck" guidance
Ch 15Issue TemplatesWARNPrerequisites scattered; YAML syntax complexity underestimated
Ch 16Accessibility AgentsWARNAgent count (55) unprepared for; unclear agent discovery method
-

Detailed Chapter Analysis

-

Chapter 4: Working with Issues

-

[PASS] — Challenge is well-designed and achievable.

-

Prerequisites Check

-

Verified:

-
    -
  • Chapter 4 appears first in challenge work (after Chapter 2-3 orientation)
    • -
  • Prerequisites explicitly listed in documentation: "Complete Pre-Workshop Setup"
    • -
  • GitHub account and browser access is sufficient
    • -
  • All prerequisites realistic for absolute beginners
    • -
-

Instructions Clarity

-

Verified:

-
    -
  • Challenge set is small: 3 micro-challenges
      -
    • Create your first issue
      • -
    • Claim a challenge issue
      • -
    • Ask one clarifying question
      • -
    -
    • -
  • All instructions are unambiguous and actionable
    • -
  • Language is beginner-friendly with examples provided
    • -
- -

All files and references verified:

-
    -
  • learning-room/docs/CHALLENGES.md exists
    • -
  • .github/ISSUE_TEMPLATE/challenge-hub.md exists
    • -
  • Guide links to Chapter 4 section in CHALLENGES.md
    • -
  • Cross-reference to podcasts working (Episode 5)
    • -
  • Screen reader cheatsheet reference (appendix-b) exists
    • -
-

Time Estimate Accuracy

-

Verified:

-
    -
  • Stated: "Under 10 minutes each challenge"
    • -
  • Assessment: ACCURATE
      -
    • Issue creation: 2-3 minutes
      • -
    • Claiming with comment: 1-2 minutes
      • -
    • Asking a question: 2-3 minutes
      • -
    -
    • -
  • Total: ~8 minutes is realistic
    • -
-

"If You Get Stuck" Guidance

-

Verified:

-
    -
  • 4 specific remediation steps provided
    • -
  • Escalation path: re-read hub → search filter → retry → ask facilitator
    • -
  • Specific search filter example given: is:open label:"challenge: beginner"
    • -
  • No vague instructions ("just try again")
    • -
-

Accessibility Assessment

-

Verified:

-
    -
  • Documentation tested with screen reader perspective
    • -
  • Search filters are keyboard-navigable following GitHub's standards
    • -
  • No emoji used as critical symbols
    • -
  • Heading hierarchy is correct (Ch 4 = h2, subsections = h3)
    • -
  • Link text is descriptive
    • -
-

Recommendations

-

No changes needed — Chapter 4 is a model for other chapters.

-

Chapter 6: Working with Pull Requests

-

[PASS] — Challenge progression builds naturally on Chapter 4.

-

Prerequisites Check

-

Verified:

-
    -
  • Explicit: "Complete Chapter 4 first"
    • -
  • All concepts from Chapter 4 (creating issues, understanding GitHub) carry forward
    • -
  • PR workflow assumes: GitHub account, basic issue understanding, web interface comfort
    • -
  • Realistic progression: small markdown fixes before tackling merge conflicts
    • -
-

Instructions Clarity

-

Verified:

-
    -
  • Challenge set is focused: 3 steps (create branch change, open linked PR, pass checks)
    • -
  • Bot validation is clearly explained: "Watch bot feedback until required checks pass"
    • -
  • Clear linking instruction: "Include Closes #XX"
    • -
  • Examples provided in documentation with file paths and expected outcomes
    • -
- -

All files verified:

-
    -
  • Reference to Chapter 6 docs (docs/06-working-with-pull-requests.md)
    • -
  • Learning Room repo structure exists and is accessible
    • -
  • Bot validation workflow references clear
    • -
  • Template reference (PR template in .github/) exists
    • -
-

Time Estimate Accuracy

-

Verified:

-
    -
  • Stated: "Under 10 minutes each"
    • -
  • Assessment: ACCURATE for experienced users; OPTIMISTIC for complete beginners
      -
    • Create branch: 2-3 minutes
      • -
    • Open PR with template: 3-4 minutes
      • -
    • Respond to bot feedback: 2-5 minutes (depends on check failures)
      • -
    -
    • -
  • Caveat: Assumes students have cloned repo locally; if using web editor, time is longer
    • -
  • Reality check: First-time PR authors may spend 8-12 minutes
    • -
-

"If You Get Stuck" Guidance

-

Verified:

-
    -
  • Specific troubleshooting steps provided
    • -
  • "Check that changed files are only in learning-room/" — excellent specificity
    • -
  • Bot validation comment walkthrough explained
    • -
  • Escalation: "ask for peer or facilitator review with exact error message"
    • -
-

Accessibility Assessment

-

Verified:

-
    -
  • PR diff reading instructions are well-documented in main chapter text
    • -
  • "Files Changed" tab navigation covered thoroughly
    • -
  • Inline comment buttons explained for screen readers
    • -
  • No accessibility gaps noted
    • -
-

Recommendations

-

No changes needed — Chapter 6 maintains quality standard set by Chapter 4.

-

Chapter 7: Merge Conflicts

-

[PASS] — Single controlled challenge with appropriate scoping.

-

Prerequisites Check

-

Verified:

-
    -
  • Prerequisites: Ch 4, Ch 6, Ch 11 (Git basics)
    • -
  • Prerequisite documentation states: "Understand branch creation and PR workflow"
    • -
  • All prerequisites realistic and well-ordered
    • -
-

Instructions Clarity

-

Verified:

-
    -
  • Single challenge with clear scope: "Resolve conflict markers"
    • -
  • Step-by-step process documented:
      -
    1. Open assigned merge-conflict practice issue
      2. -
    2. Edit only designated practice file/section
      3. -
    3. Remove conflict markers
      4. -
    4. Open PR with Closes #XX
      5. -
    -
    • -
  • Clear learning goal: Distinguish between conflict marker lines and content
    • -
- -

Verified:

-
    -
  • Reference to "designated practice file/section" is created as part of challenge setup
    • -
  • Examples of conflict marker syntax provided: <<<<<<<, =======, >>>>>>>
    • -
  • Main chapter documentation (docs/07-merge-conflicts.md) fully explains conflict resolution
    • -
  • Links to other chapters (Ch 4, 5, 11) all exist
    • -
-

Time Estimate Accuracy

-

Verified:

-
    -
  • Stated: "Under 10 minutes"
    • -
  • Assessment: ACCURATE
      -
    • Reading practice file: 2-3 minutes
      • -
    • Identifying markers: 1-2 minutes
      • -
    • Resolving (removing markers, choosing content): 2-3 minutes
      • -
    • Opening PR and completing: 2-3 minutes
      • -
    -
    • -
  • Reality check: Conflict resolution is cognitively simple but requires focus; 8-10 minutes realistic
    • -
-

"If You Get Stuck" Guidance

-

Verified:

-
    -
  • Excellent specific steps:
      -
    1. "Pause and read marker blocks line by line before editing" — prevents rushing
      2. -
    2. "Keep one side, or combine both sides when both lines are valid" — addresses the decision point
      3. -
    3. "Delete all marker lines" — explicit action
      4. -
    4. "Ask facilitator to sanity-check final content before opening PR" — safety valve
      5. -
    -
    • -
-

Accessibility Assessment

-

Verified:

-
    -
  • Conflict marker documentation uses monospace formatting for clarity
    • -
  • Learning moment explains value of conflicts (not failure)
    • -
  • Screen reader navigation through markers is straightforward (text-based)
    • -
-

Recommendations

-

No changes needed — Chapter 7 provides good model for teaching high-stakes tasks through controlled practice.

-

Chapter 8: Culture, Etiquette, and Community Standards

-

[WARN] — Guidance is clear but optional challenge needs evaluation criteria clarification.

-

Prerequisites Check

-

Verified:

-
    -
  • No hard prerequisites stated; appears after PR workflow chapters
    • -
  • Implied: Students have read Chapters 4-6
    • -
  • Timing is appropriate (after technical practices, before code review)
    • -
-

Instructions Clarity

-

ISSUE FOUND:

-
    -
  • Challenge is explicitly optional with provided reflection template
    • -
  • Template asks for 3 items:
    - One respectful review habit I will use:
-- One way I will ask for help clearly:
-- One way I will respond to feedback constructively:
    -
    • -
  • Problem: No clarity on what counts as "complete"
    • -
  • Impact: Students may not know if they've met expectations
    • -
- -

Verified:

-
    -
  • Chapter 8 documentation (docs/08-culture-etiquette.md) exists
    • -
  • Podcast reference (Episode 8) links correctly
    • -
  • Learning moment is well-written
    • -
-

Time Estimate Accuracy

-

ISSUE FOUND:

-
    -
  • Stated: "No bot-graded challenge"
    • -
  • Estimated time: Implied 5-10 minutes
    • -
  • Problem: No explicit time estimate provided
    • -
  • Reality: Reflection can take 10-20 minutes depending on depth
    • -
  • Risk: Students may rush if they perceive it as quick
    • -
-

"If You Get Stuck" Guidance

-

Verified:

-
    -
  • 4 specific steps provided:
      -
    1. "Use one simple sentence per prompt"
      2. -
    2. "Focus on one real behavior you can do today"
      3. -
    3. "If writing feels hard, draft bullet points first, then post"
      4. -
    4. "Ask facilitator for one example response and adapt it"
      5. -
    -
    • -
-

Accessibility Assessment

-

Verified:

-
    -
  • Reflection template is unambiguous
    • -
  • Non-visual learners can engage with prompts
    • -
  • No accessibility barriers identified
    • -
-

Recommendations

-

CHANGE REQUIRED:

-
    -
  1. Add explicit evaluation criteria: "Your reflection is complete when you have posted one sentence for each of the three prompts. We will not judge your answers—honest reflection is the goal."
    2. -
  2. Add time estimate: "Estimated time: 10-15 minutes"
    3. -
  3. Add clarity on optional nature: Change "Optional" to "Strongly Encouraged" (optional implies students can skip; encouraged signals importance without making it required)
    4. -
-

Chapter 9: Labels, Milestones, and Projects

-

[PASS] — Triage recommendation challenge is well-scoped and clear.

-

Prerequisites Check

-

Verified:

-
    -
  • Implicit: Complete Chapters 4-6 first (understand issues, VS Code, and PRs)
    • -
  • Triage context explained in main chapter documentation
    • -
  • Realistic for students who have filed and reviewed issues
    • -
-

Instructions Clarity

-

Verified:

-
    -
  • Challenge is specific: "Post a triage recommendation comment"
    • -
  • Template provided with 4 fields:
    - Suggested labels:
-- Suggested milestone:
-- Suggested project board column:
-- One-sentence reason:
    -
    • -
  • Clear guidance for students without write access: "Write triage recommendation even if you can't apply labels"
    • -
- -

Verified:

-
    -
  • .github/ISSUE_TEMPLATE/ folder exists
    • -
  • Label, milestone, and project references are GitHub standard features
    • -
  • Main chapter documentation (docs/09-labels-milestones-projects.md) exists
    • -
  • Podcast reference (Episode 9) exists
    • -
-

Time Estimate Accuracy

-

Verified:

-
    -
  • Stated: "1 guided challenge" with no specific time estimate visible in challenge summary
    • -
  • Caveat: Main chapter documentation should state time explicitly
    • -
  • Estimated actual time: 5-10 minutes (read issue, recommend, post comment)
    • -
-

"If You Get Stuck" Guidance

-

Verified:

-
    -
  • 4 well-structured steps:
      -
    1. "Start with one label only" — doesn't require mastery of all labels
      2. -
    2. "If milestone is unclear, write none and explain why" — acceptable incompleteness
      3. -
    3. "If project board is unknown, write needs triage and continue" — forward progress allowed
      4. -
    4. "Ask facilitator to review your one-sentence reason before posting" — quality check option
      5. -
    -
    • -
-

Learning Moment

-

Verified:

-
    -
  • "Triage is about clarity, not authority" — reframes triage as collaborative
    • -
  • Supports students who fear making wrong decisions
    • -
-

Recommendations

-

Minor improvement only:

-
    -
  1. Add explicit time estimate in challenge overview: "Estimated time: 5-10 minutes"
    2. -
-

Chapter 10: Notifications

-

[WARN] — Carefully designed but time estimate and screen reader testing may reveal gaps.

-

Prerequisites Check

-

Verified:

-
    -
  • No hard prerequisites; can be taken standalone
    • -
  • Assumes: GitHub account, browser, basic GitHub familiarity
    • -
  • Timing: Good placement after PR workflow chapters (students know what notifications they'll receive)
    • -
-

Instructions Clarity

-

ISSUE FOUND - Workflow clarity:

-
    -
  • Challenge explicitly states: "No bot-graded challenge" and "No Actions-based validation"
    • -
  • Problem: Students may wonder if they've completed it correctly
    • -
  • Documentation states: Issue comment should be posted, but challenge description says "guided walkthrough"
    • -
  • Ambiguity: Is posting a completion comment required, or only the actions?
    • -
- -

Verified:

-
    -
  • .github/ templates reference correct
    • -
  • PODCASTS.md link (Episode 10) verified
    • -
  • Notification filters reference GitHub standard features
    • -
  • Main chapter documentation (docs/10-notifications.md) exists
    • -
-

Time Estimate Accuracy

-

ISSUE FOUND - Estimate optimism:

-
    -
  • Stated: "5-8 minutes"
    • -
  • Reality assessment:
      -
    • Navigate to Watch settings: 1-2 minutes
      • -
    • Open notifications inbox: 1 minute
      • -
    • Apply Review Requested filter: 1-2 minutes
      • -
    • Apply Assigned filter: 1-2 minutes
      • -
    • Open one notification: 1 minute
      • -
    • Perform one inbox action: 1 minute
      • -
    -
    • -
  • Subtotal: 6-9 minutes — consistent with estimate
    • -
  • BUT: First-time users discovering filters might take 10-15 minutes
    • -
  • CAVEAT: If student has no notifications, exploring becomes slower
    • -
-

"If You Get Stuck" Guidance

-

Strong guidance provided:

-
    -
  1. "Reload the notifications page and reapply one filter at a time" — specific recovery
    2. -
  2. "If inbox is empty, switch to Done and practice action flow there" — workaround for sparse notifications
    3. -
  3. "If shortcuts conflict with screen reader mode, focus the notification row and retry" — accessibility-specific help
    4. -
  4. "Ask facilitator to model one inbox action live, then repeat" — hands-on escalation
    5. -
-

Accessibility Assessment

-

ISSUE FOUND - Screen reader variability:

-
    -
  • Guidance assumes students know notification keyboard shortcuts
    • -
  • Problem: Shortcuts vary between screen readers (M = mute, E = mark done)
    • -
  • Impact: Screen reader users may not know shortcuts exist section mentions M and E shortcuts but doesn't confirm they work with all assistive tech
    • -
  • Needs verification: Testing with NVDA, JAWS, and VoiceOver on GitHub's notification UI
    • -
-

Recommendations

-

Changes strongly recommended:

-
    -
  1. Add completion evidence requirement: "After completing the walkthrough, post an issue comment saying: Has completed Chapter 10 notification setup (Watch level set, filters applied, one action tested)."
    2. -
  2. Add screen reader testing note: "If keyboard shortcuts don't work with your screen reader, use the mouse/trackpad to perform actions. We're working to improve shortcut coverage."
    3. -
  3. Add time note: "Note: Estimate assumes notifications exist. If your inbox is empty, use the Done or All tabs as shown in the 'If You Get Stuck' section."
    4. -
-

Chapter 5: VS Code Accessibility

-

[WARN] — Platform accessibility varies; parity issues need flagging.

-

Prerequisites Check

-

Verified:

-
    -
  • Explicit: Complete Pre-Workshop Setup first
    • -
  • Assumes: GitHub account, browser, screen reader (implied)
    • -
  • Realistic progression: happens after GitHub web skills
    • -
-

Instructions Clarity

-

ISSUE FOUND - Platform assumption:

-
    -
  • Challenge explicitly uses github.dev (web-based VS Code)
    • -
  • Issue: Desktop VS Code installation is mentioned as alternative but not integrated into challenge steps
    • -
  • Impact: Students with desktop VS Code may be unclear if they should follow different steps
    • -
  • Text says: "Open github.dev with . (period key)" — but only works on GitHub.com
    • -
- -

Verified:

-
    -
  • Reference to Accessible Help in VS Code (product feature) exists
    • -
  • Reference to Accessible View exists in VS Code Help
    • -
  • Main chapter documentation (docs/05-vscode-accessibility.md) exists
    • -
  • Podcast reference (Episode 11) verified
    • -
-

Time Estimate Accuracy

-

ISSUE FOUND - Competitive estimate:

-
    -
  • Stated: "8-10 minutes"
    • -
  • Reality assessment:
      -
    • Open github.dev with period key: 1 minute
      • -
    • Enable screen reader mode (Shift+Alt+F1): 1 minute
      • -
    • Verification/troubleshooting if not already enabled: 1-3 minutes
      • -
    • Open Explorer (Ctrl+Shift+E or menu): 1-2 minutes
      • -
    • Open README.md: 1 minute
      • -
    • Open Symbols (Ctrl+Shift+O): 1-2 minutes
      • -
    • Open Command Palette (Ctrl+Shift+P): 1 minute
      • -
    • Run a command: 1-2 minutes (navigating and selecting)
      • -
    -
    • -
  • Total: 8-14 minutes — estimate is tight
    • -
  • Risk: Keyboard shortcut discovery time can extend this significantly
    • -
-

"If You Get Stuck" Guidance

-

Verified:

-
    -
  • 4 steps provided:
      -
    1. "Confirm you are in a repository page before pressing ." — targets root cause
      2. -
    2. "Retry screen reader mode toggle once, then verify in settings" — persistence + verification
      3. -
    3. "Use Command Palette to run commands when shortcut memory is hard" — adaptive workaround
      4. -
    4. "Ask facilitator for a side-by-side demo and repeat the same 5 steps" — hands-on escalation
      5. -
    -
    • -
-

Accessibility Assessment

-

ISSUES FOUND:

-
    -

  1. Screen reader mode availability varies:

    -
      -
    • Shift+Alt+F1 (Windows) is documented
      • -
    • Shift+Option+F1 (Mac) is documented
      • -
    • Problem: VoiceOver users on Mac don't need vs-code screen reader mode (they already have VoiceOver)
      • -
    • Impact: Documentation may confuse Mac + VoiceOver users
      • -
    -
    2. -

  2. No mention of accessibility extensions:

    -
      -
    • "Accessible View" and "Accessible Help" are VS Code features
      • -
    • Problem: Not clear if these are built-in or require installation
      • -
    • Risk: Students may search for extensions that don't exist
      • -
    -
    3. -
-

Recommendations

-

Changes required:

-
    -

  1. Clarify screen reader mode steps for Mac + VoiceOver:

    -
    If you use VoiceOver on Mac, skip the Shift+Option+F1 step. 
-VoiceOver is already your screen reader - VS Code will detect it automatically.
-Proceed directly to opening Explorer.
    -
    2. -

  2. Add feature availability note:

    -
    Accessible Help and Accessible View are built into VS Code 1.75+.
-If these features don't appear, update VS Code (Help → Check for Updates).
    -
    3. -

  3. Add realistic time note:

    -
    Note: First-time setup may take 10-12 minutes if you need to explore 
-the VS Code UI to find these features. That's expected!
    -
    4. -
  4. Separate section for desktop vs github.dev if length allows, OR -Add footnote: "This challenge uses github.dev (browser-based). You can also complete it with VS Code Desktop following the same steps. See VS Code Desktop Guide for setup."
    5. -
-

Chapter 11: Git & Source Control

-

[WARN] — Important prerequisites and time estimates need review.

-

Prerequisites Check

-

ISSUE FOUND - Prerequisites incomplete:

-
    -
  • Challenge states prerequisites in chapter header but not in challenge hub summary
    • -
  • Missing from CHALLENGES.md Hub: Explicit statement: "Must have completed Chapter 6 first"
    • -
  • Hub text says: Challenge Set 1 = "Clone the sci-fi themes repository"
    • -
  • Problem: Students may not know they need github.dev or VS Code setup first
    • -
  • Risk: Students attempt challenge without proper environment configured
    • -
-

Instructions Clarity

-

Verified:

-
    -
  • Challenge set is clear: Clone → Commit → Push/PR
    • -
  • Examples provided with specific repository URL: https://github.com/community-access/vscode-sci-fi-themes.git
    • -
  • Fun context added (sci-fi themes) to motivate learners
    • -
  • Command examples clear and well-formatted
    • -
- -

Verified:

-
    -
  • Reference to sci-fi themes repository is a real, public repository
    • -
  • Command examples reference real git commands
    • -
  • Main chapter documentation (docs/11-git-source-control.md) exists
    • -
  • Podcast reference (Episode 12) exists
    • -
  • Cross-references to Chapter 6, 7, 5 all exist
    • -
-

Time Estimate Accuracy

-

ISSUE FOUND - Estimate is aggressive:

-
    -
  • Stated: "Under 10 minutes each challenge"
    • -

  • Detailed assessment:

    -
      -

    • Challenge 1: Clone repository

      -
        -
      • Open Command Palette: 1 minute
        • -
      • Type "Git: Clone": 1-2 minutes (searching)
        • -
      • Paste URL: 1 minute
        • -
      • Choose folder: 1-2 minutes (folder picker interaction)
        • -
      • Wait for clone: 1-3 minutes (network dependent)
        • -
      • Open folder when prompted: 1 minute
        • -
      • Subtotal: 6-10 minutes at the edge
        • -
      -
      • -

    • Challenge 2: Make one small commit

      -
        -
      • Open Source Control panel (Ctrl+Shift+G): 1 minute
        • -
      • Edit a file: 2-5 minutes (depends on file and change)
        • -
      • Stage the file: 1-2 minutes (find file in Source Control, stage with spacebar or menu)
        • -
      • Write commit message: 2-3 minutes (short message, enter)
        • -
      • Commit (Ctrl+Enter): 1 minute
        • -
      • Subtotal: 7-12 minutes (exceeds estimate for slower users)
        • -
      -
      • -

    • Challenge 3: Push and open PR

      -
        -
      • Push branch: 1-2 minutes (find push button or use terminal)
        • -
      • Navigate to GitHub PR creation: 1 minute
        • -
      • Create PR title and description: 2-3 minutes
        • -
      • Reference issue with Closes #XX: 1 minute
        • -
      • Submit: 1 minute
        • -
      • Subtotal: 6-8 minutes
        • -
      -
      • -
    -
    • -
  • Total estimate: 19-30 minutes for all 3 challenges vs. stated "Under 10 minutes each" (each is under 10, but barely)
    • -
-

"If You Get Stuck" Guidance

-

Verified:

-
    -
  • 5-step recovery plan provided:
      -
    1. Confirm Command Palette works (Ctrl+Shift+P)
      2. -
    2. Use keyboard shortcut for Source Control (Ctrl+Shift+G)
      3. -
    3. Verify authentication with Ctrl+Shift+P → "Git: Fetch"
      4. -
    4. Confirm VS Code is in cloned folder (status bar shows branch name)
      5. -
    5. Ask facilitator to verify clone and help with push
      6. -
    -
    • -
-

Accessibility Assessment

-

Verified:

-
    -
  • All keyboard shortcuts provided with Windows and Mac variants
    • -
  • Source Control panel navigation explained for screen readers (uses tree structure)
    • -
  • Command Palette references how to access (searchable interface)
    • -
  • File navigation accessible with keyboard
    • -
-

Learning Moment

-

Well-written: "Local Git operations give you full control and immediate feedback."

-

Recommendations

-

CHANGES REQUIRED:

-
    -

  1. Emphasize prerequisites in CHALLENGES.md hub:

    -
    **Prerequisites:** Complete Chapter 5 (VS Code Accessibility) and have github.dev or VS Code Desktop open.
    -
    2. -

  2. Revise time estimate:

    -
    Note: Estimated time reflects local Git familiarity. 
-First-time cloning may take 12-15 minutes. 
-Commit and push steps should take 5-8 minutes each if you've already staged changes.
    -
    3. -

  3. Add note about network speed:

    -
    Repository clone time depends on your internet connection. 
-If download seems slow (>3 minutes), check your connection and resubmit the clone command.
    -
    4. -
-

Chapter 12: GitHub Pull Requests Extension

-

[WARN] — Critical assumption about write access not addressed upfront.

-

Prerequisites Check

-

ISSUE FOUND - Write access assumption:

-
    -
  • Challenge states: "Install the GitHub Pull Requests extension" and "Check out a challenge PR"
    • -
  • Implicit assumption: Students have write access to at least one repository to "check out" a PR branch
    • -
  • Problem: If student only has read access to the workshop repo, they cannot check out branches
    • -
  • Risk: Challenge becomes unachievable without remediation
    • -
-

Instructions Clarity

-

Verified:

-
    -
  • Challenge set is clear: Install → Authenticate → Check out PR → Review → Post feedback
    • -
  • Steps are in logical order
    • -
  • Expected outcomes are specific
    • -
- -

Verified:

-
    -
  • Main chapter documentation (docs/12-github-pull-requests-extension.md) exists
    • -
  • Podcast reference (Episode 13) verified
    • -
  • Cross-references to Chapter 6 and 11 exist
    • -
  • Extension reference is to official Microsoft/GitHub extension
    • -
-

Time Estimate Accuracy

-

ISSUE FOUND - Setup time underestimated:

-
    -
  • Stated: "2 guided challenges" with no time estimate visible in hub
    • -

  • Detailed assessment:

    -
      -

    • Challenge 1: Install extension

      -
        -
      • Open Extensions: 1 minute
        • -
      • Search for "GitHub Pull Requests": 1-2 minutes
        • -
      • Install: 1-2 minutes (wait for download)
        • -
      • Reload VS Code if prompted: 1 minute
        • -
      • Subtotal: 4-6 minutes
        • -
      -
      • -

    • Challenge 2: Auth + check out + review

      -
        -
      • Sign in with GitHub: 1-2 minutes (may open browser, return to VS Code)
        • -
      • Locate PR list in Explorer: 1-2 minutes (finding new UI element)
        • -
      • Filter or find a PR: 1-2 minutes
        • -
      • Check out PR branch: 1-2 minutes (understand menu action)
        • -
      • Read PR changes: 5-10 minutes (depends on diff size)
        • -
      • Write review comment: 3-5 minutes
        • -
      • Submit review: 1 minute
        • -
      • Subtotal: 13-24 minutes
        • -
      -
      • -
    -
    • -
  • Total for Chapter 12: 17-30 minutes — no time estimate provided in hub, but implied significance
    • -
-

"If You Get Stuck" Guidance

-

Verified:

-
    -
  • 5-step recovery plan:
      -
    1. Reload VS Code if install doesn't work
      2. -
    2. Verify GitHub account active in browser first (before OAuth)
      3. -
    3. Switch to "All Open" view if PR list empty (discovers filtering)
      4. -
    4. Ask facilitator about write access if checkout fails
      5. -
    5. Side-by-side facilitator demo for single checkout
      6. -
    -
    • -
-

Accessibility Assessment

-

ISSUE FOUND - Screen reader testing needed:

-
    -
  • Extension is developed by Microsoft/GitHub and integrates VS Code UI
    • -
  • Question: Is PR list navigation accessible with screen readers?
    • -
  • Risk: VS Code extensions sometimes have accessibility gaps not documented
    • -
  • Needs verification: Test with NVDA, JAWS, VoiceOver before deployment
    • -
-

Learning Moment

-

Well-written: "PR tooling multiplies your impact. Reviewing others' work refines your own standards and builds community trust."

-

Recommendations

-

CHANGES REQUIRED:

-
    -

  1. Add explicit write-access note:

    -
    **Write Access Note:** You can check out PR branches only if you have write access to the repository. 
-If you receive an error "Permission denied," ask your facilitator for access or use a personal fork instead.
    -
    2. -

  2. Add screen reader testing disclaimer:

    -
    **Screen Reader Note:** The GitHub Pull Requests extension uses VS Code's UI elements, which have been tested for NVDA/JAWS access. 
-If the PR list doesn't appear in Explorer or navigation feels broken, try reloading VS Code or ask your facilitator.
    -
    3. -

  3. Add time estimate:

    -
    Note: Estimated time is 20-30 minutes for first-time extension users. 
-Authentication setup and discovering the PR list in VS Code are learning experiences.
    -
    4. -
-

Chapter 13: GitHub Copilot

-

[WARN] — Subscription prerequisite not clearly flagged; sci-fi theme is engaging but adds scope.

-

Prerequisites Check

-

ISSUE FOUND - Subscription requirement buried:

-
    -
  • Challenge assumes: "GitHub Copilot Chat extension installed and authenticated"
    • -
  • Problem: GitHub Copilot requires a paid subscription ($20/month) OR organization access
    • -
  • Risk: Students without paid licenses will fail immediately
    • -
  • Impact: This is a major blocker not flagged in CHALLENGES.md hub
    • -
-

Instructions Clarity

-

Verified:

-
    -
  • Challenge set is clear: Install → Configure → Use
    • -
  • Sci-fi theme context (vscode-sci-fi-themes repo) is fun and motivating
    • -
  • Examples of prompts provided (Ctrl+Shift+I)
    • -
  • Settings.json customization is explained (but assumes YAML familiarity)
    • -
- -

Verified:

-
    -
  • Reference to vscode-sci-fi-themes repository is real and public
    • -
  • Main chapter documentation (docs/13-github-copilot.md) exists
    • -
  • Podcast reference (Episode 14) exists
    • -
  • Cross-references to Chapter 6, 11 exist
    • -
-

Time Estimate Accuracy

-

ISSUE FOUND - Reality testing needed:

-
    -
  • Stated: "3 guided challenges" with no time estimate in hub
    • -

  • Detailed assessment:

    -
      -

    • Challenge 1: Install and sign in

      -
        -
      • Open Extensions: 1 minute
        • -
      • Search "GitHub Copilot Chat": 1-2 minutes
        • -
      • Install: 1-2 minutes
        • -
      • Authenticate: 1-2 minutes (may open browser)
        • -
      • Subtotal: 4-7 minutes
        • -
      -
      • -

    • Challenge 2: Clone repo + ask Copilot

      -
        -
      • Clone sci-fi themes repo: 2-5 minutes (depends on network)
        • -
      • Open Copilot Chat: 1 minute
        • -
      • Ask a question: 1 minute
        • -
      • Wait for Copilot response: 2-5 minutes (depends on API latency, token usage)
        • -
      • Read and understand response: 2-5 minutes
        • -
      • Apply theme to settings.json: 2-3 minutes (if comfortable with JSON)
        • -
      • Reload VS Code: 1 minute
        • -
      • Subtotal: 11-22 minutes
        • -
      -
      • -

    • Challenge 3: Create custom theme

      -
        -
      • Ask Copilot for custom prompt: 1 minute
        • -
      • Wait for generation: 2-5 minutes
        • -
      • Copy response: 1 minute
        • -
      • Paste into settings.json: 2-3 minutes (understand JSON format)
        • -
      • Reload: 1 minute
        • -
      • Test in Chat: 1-2 minutes
        • -
      • Subtotal: 8-14 minutes
        • -
      -
      • -
    -
    • -
  • Total: 23-43 minutes — no estimate provided, but likely 30-45 minutes for first-timers
    • -
-

"If You Get Stuck" Guidance

-

Verified:

-
    -
  • 5-step recovery:
      -
    1. Reload VS Code if install fails
      2. -
    2. Verify GitHub account active in browser first
      3. -
    3. Try Ctrl+Shift+I or check model selector at bottom
      4. -
    4. Click model selector to confirm sign-in
      5. -
    5. Ask facilitator to verify Copilot activation and show one prompt
      6. -
    -
    • -
-

Accessibility Assessment

-

Verified:

-
    -
  • Copilot Chat requires Accessible View (Alt+F2 / Option+F2) for screen reader users to read responses
    • -
  • This is documented in main chapter text (lines discussing Accessible View)
    • -
  • Mac keyboard shortcuts provided
    • -
  • No emoji in challenge instructions themselves
    • -
-

Learning Moment

-

Excellent: "AI assistance amplifies clarity... May your code always load with cosmic flair! "

-

Recommendations

-

CHANGES REQUIRED:

-
    -

  1. Add subscription warning at top of CHALLENGES.md Chapter 13 section:

    -
     **Prerequisite: GitHub Copilot Subscription**
-
-GitHub Copilot Chat requires either:
-- An active GitHub Copilot subscription ($20/month), OR
-- Access through your school/organization
-
-If you don't have access:
-1. Ask your facilitator if the workshop has org access
-2. Start a free trial ($20/month but you can cancel immediately after workshop)
-3. Skip to next chapter and come back when you have access
-
-This is a real constraint, not a learning challenge. We want you to know upfront!
    -
    2. -

  2. Add JSON editing note:

    -
    **For non-programmers:** Modifying settings.json can feel intimidating if you've never edited JSON before. 
-This is normal! The settings.json file uses a format called JSON. 
-When you copy Copilot's generated settings:
-- Match the indentation (spaces)
-- Make sure commas separate the entries
-- If something seems wrong, ask facilitator to verify before reloading.
    -
    3. -

  3. Add time estimate:

    -
    Note: Estimated time is 30-45 minutes for first-time Copilot users. 
-This includes waiting for API responses and learning settings.json syntax.
    -
    4. -
-

Chapter 14: Accessible Code Review

-

[PASS] — Well-structured review practice with excellent accessibility focus.

-

Prerequisites Check

-

Verified:

-
    -
  • Explicit: Complete Chapter 6 (PRs) and Chapter 12 (PR extension)
    • -
  • Stated prerequisites: "Complete Ch 6 and Ch 12"
    • -
  • Accessible progression: move from opening PRs (Ch 6) to reviewing them (Ch 14)
    • -
-

Instructions Clarity

-

Verified:

-
    -
  • Challenge set is clear: Review PR → Leave 2-3 comments → Submit verdict (approve/request-changes/comment)
    • -
  • Expected outcomes are specific:
      -
    • Can navigate diff with screen reader
      • -
    • Can post inline comments
      • -
    • Can write constructive feedback
      • -
    -
    • -
  • Learning Room examples explained (files from learning-room docs)
    • -
- -

Verified:

-
    -
  • References to chapter documentation files exist:
      -
    • docs/keyboard-shortcuts.md (shortcut tables with intentional errors)
      • -
    • docs/setup-guide.md (broken links and incomplete steps)
      • -
    • docs/welcome.md ([TODO] sections)
      • -
    -
    • -
  • Chapter 15 link references exist
    • -
  • Main chapter documentation (docs/14-accessible-code-review.md) exists
    • -
  • Podcast reference (Episode 15) exists
    • -
-

Time Estimate Accuracy

-

Verified:

-
    -
  • Stated: "2 guided challenges" with no explicit time in hub
    • -

  • Detailed assessment:

    -
      -

    • Challenge 1: Review PR + leave 2-3 comments

      -
        -
      • Navigate to PR: 1-2 minutes
        • -
      • Open Files Changed tab: 1 minute
        • -
      • Read diff (depends on file size, assume 3-5 line changes): 3-5 minutes
        • -
      • Find inline comment button on 3 lines: 3-5 minutes (screen reader users may need to use context menu / Shift+F10)
        • -
      • Write 3 constructive comments: 5-8 minutes (requires thought, not just typing)
        • -
      • Subtotal: 13-21 minutes
        • -
      -
      • -

    • Challenge 2: Submit review verdict

      -
        -
      • Find "Review changes" button: 1-2 minutes
        • -
      • Select verdict (Approve/Request changes/Comment): 1 minute
        • -
      • Add summary comment if needed: 2-3 minutes
        • -
      • Submit: 1 minute
        • -
      • Subtotal: 5-7 minutes
        • -
      -
      • -
    -
    • -
  • Total: 18-28 minutes — reasonable for first code review
    • -
-

"If You Get Stuck" Guidance

-

EXCELLENT guidance provided:

-
    -
  1. "If Files Changed tab won't open, reload the PR page and retry" — specific recovery
    2. -
  2. "If inline comment button is hard to find, use the file tree to jump between files (Press 3 in NVDA/JAWS)" — screen reader–specific workaround
    3. -
  3. "If you're unsure what to comment on, focus on clarity: heading structure, link text, missing steps, or typos" — concrete guidance
    4. -
  4. "If submitting the review fails, check that you're not in draft mode and have write access" — common gotchas
    5. -
  5. "Ask facilitator to help you navigate one diff and model one constructive comment" — hands-on escalation
    6. -
-

Accessibility Assessment

-

EXCEPTIONAL:

-
    -
  • Files Changed tab navigation for screen readers is thoroughly documented in main chapter
    • -
  • Inline comment button locations explained specifically for NVDA/JAWS (Press 3 in file tree)
    • -
  • Focus mode vs browse mode navigation explained
    • -
  • Diff reading strategies documented (jump headings first to understand file sections)
    • -
  • Learning moment connects review to community building (not just technical quality)
    • -
-

Recommendations

-

No changes required — Chapter 14 is a strong model for teaching accessible workflows. The "If You Get Stuck" section is particularly well-written.

-

Chapter 15: Issue Templates

-

[WARN] — Prerequisites scattered; YAML complexity underestimated; guidance clarity needs improvement.

-

Prerequisites Check

-

ISSUE FOUND - Prerequisites are fragmented:

-
    -
  • Challenge mentions prerequisites in chapter header:
      -
    • Chapter 4 (understand issues)
      • -
    • Chapter 13 (YAML highlighting)
      • -
    • Chapter 10 (notifications)
      • -
    • "A GitHub repository where you have write access"
      • -
    • "Terminal/Command line basic comfort"
      • -
    -
    • -
  • Problem: Scattered across chapter instead of single prerequisite block
    • -
  • Risk: Students may not realize they need write access to their own repo BEFORE starting challenges
    • -
-

Instructions Clarity

-

ISSUE FOUND - Complexity underestimated:

-
    -
  • Challenge Set 1 (Analyze): "Read the registration template" — straightforward
    • -
  • Challenge Set 2 (Remix): "Adapt registration template for new context" — vague
      -
    • Says "Update field names, labels, descriptions, and dropdown options"
      • -
    • But doesn't show what a remixed template looks like
      • -
    • YAML syntax complexity not visualized upfront
      • -
    -
    • -
  • Challenge Set 3 (Create): "Create a Markdown template" — optional but needs syntax example
    • -
- -

Verified:

-
    -
  • .github/ISSUE_TEMPLATE/workshop-registration.yml exists and is readable
    • -
  • Main chapter documentation (docs/15-issue-templates.md) exists
    • -
  • Podcast reference (Episode 16) verified
    • -
  • Cross-reference to Chapter 16 provided
    • -
  • Appendix C (Accessibility Standards) referenced
    • -
-

Time Estimate Accuracy

-

ISSUE FOUND - Time may be significantly high:

-
    -
  • Stated: In chapter header: "1.5 hours"
    • -

  • Detailed assessment:

    -
      -

    • Challenge 1: Analyze registration template

      -
        -
      • Read YAML structure: 5-10 minutes (first time seeing YAML)
        • -
      • Understand field types (input, dropdown, textarea, markdown): 5-10 minutes
        • -
      • Compare with existing forms: 5 minutes
        • -
      • Write short analysis comment: 5-8 minutes
        • -
      • Subtotal: 20-33 minutes (potentially high for beginners)
        • -
      -
      • -

    • Challenge 2: Remix template

      -
        -
      • Decide on new context (bug report, feedback, audit form): 3-5 minutes
        • -
      • Copy registration template: 2 minutes
        • -
      • Modify field names/labels/descriptions: 10-20 minutes (depends on comfort with YAML)
        • -
      • Update dropdown options: 10-15 minutes
        • -
      • Commit and push: 5-10 minutes (or create PR)
        • -
      • Subtotal: 30-52 minutes
        • -
      -
      • -

    • Challenge 3: Create Markdown template (optional)

      -
        -
      • Create YAML frontmatter from scratch: 10-20 minutes (significant learning)
        • -
      • Write Markdown body with 3-4 sections: 15-25 minutes
        • -
      • Test in template chooser: 5 minutes
        • -
      • Subtotal: 30-50 minutes (OPTIONAL)
        • -
      -
      • -
    -
    • -
  • Total base (Ch1 + Ch2): 50-85 minutes
    • -
  • Total with optional (Ch1 + Ch2 + Ch3): 80-135 minutes
    • -
  • Against stated estimate: "1.5 hours (90 minutes)" = might fit baseline but is at ceiling for average students
    • -
-

"If You Get Stuck" Guidance

-

Adequate coverage:

-
    -
  • 6-step recovery plan provided:
      -
    1. Can't find registration template → direct path: .github/ISSUE_TEMPLATE/workshop-registration.yml
      2. -
    2. YAML structure confusing → "Copy the registration template. Modify only field descriptions and labels first. Leave structure intact."
      3. -
    3. Not sure what context to remix for → examples: bug report, feature request, workshop feedback, accessibility audit, event signup
      4. -
    4. Template doesn't appear in chooser → debugging steps (filename, location, push confirmation)
      5. -
    5. Repository permissions issue → ask facilitator for write access to test repo
      6. -
    6. Want to see how it works → ask facilitator to share their template
      7. -
    -
    • -
-

Accessibility Assessment

-

ISSUE FOUND - YAML syntax complexity:

-
    -
  • YAML is inherently less accessible than Markdown due to whitespace sensitivity
    • -
  • Problem: Indentation errors are hard to catch with screen readers (spaces vs tabs)
    • -
  • Problem: No guidance provided for validating YAML syntax after editing
    • -
  • Solution needed: Show students how to validate YAML (VS Code linter, or online validator)
    • -
-

Learning Moment

-

Excellent: Explains why professional templates exist and how students' remix becomes a teaching example.

-

Recommendations

-

CHANGES REQUIRED:

-
    -

  1. Add consolidated prerequisites block at top of CHALLENGES.md Chapter 15:

    -
    **Prerequisites:**
-- Complete Chapter 4 (understand GitHub issues)
-- Complete Chapter 13 (YAML syntax highlighting installed in VS Code)
-- Have write access to a GitHub repository (your fork or personal repo)
-- Basic comfort with terminal/command line (git commit, git push)
-- ~1.5 - 2 hours available (account for learning YAML syntax)
    -
    2. -

  2. Add YAML syntax validation guidance:

    -
    **Before commit:** Check your YAML syntax:
-- Ensure all lines starting content are indented with spaces (not tabs)
-- Every `key:` has a value or list below it
-- Curly braces `{}` and square brackets `[]` are balanced
-
-If unsure, paste your YAML into https://www.yamllint.com/ to check before committing.
    -
    3. -

  3. Add a before/after remix example:

    -
    **Example remix:**
-Original (registration):
-```yaml
-body:
-  - type: input
-    id: first-name
-    attributes:
-      label: First Name
    -

    Remixed (bug report):

    -
    body:
-  - type: input
-    id: bug-title
-    attributes:
-      label: Brief Bug Title
    -
    -
    4. -

  4. Revise complexity statement:

    -
    **Warning:** This chapter requires learning YAML format, which is new for most students. 
-This is normal! The "If You Get Stuck" section includes examples and a YAML validator link. 
-Don't hesitate to ask your facilitator if YAML indentation confuses you—this is a common question.
    -
    5. -
-

Chapter 16: Accessibility Agents

-

[WARN] — Unfocused scope (55 agents); discovery method unclear; prerequisite "Skill First" principle needs reinforcement.

-

Prerequisites Check

-

ISSUE FOUND - Skill-first prerequisite needs upfront validation:

-
    -
  • Challenge states: "Verify you have completed manual skill before using agent"
    • -
  • Provides prerequisite table mapping agents to skills
    • -
  • Problem: Students may skip manual work and jump to agents (tempting!)
    • -
  • Problem: No validation mechanism to ensure students DID the manual work
    • -
  • Risk: Students use agents without understanding their limitations
    • -
-

Instructions Clarity

-

ISSUE FOUND - Discovery method is unclear:

-
    -
  • Challenge describes 3 main activities:
      -
    1. Agent Discovery Mapping (match agents to skills)
      2. -
    2. Agent Skill Validation (run one agent, evaluate)
      3. -
    3. Agent Instructions Deep Dive (read .agent.md file)
      4. -
    -
    • -
  • Problem: "Discovery Mapping" assumes students know how to find agents
    • -
  • Problem: No guidance on WHERE the accessibility-agents repo is or how to explore .github/agents/ folder
    • -
  • Problem: 55 agents is overwhelming with no taxonomy or recommended starting points
    • -
- -

ISSUE FOUND - External repo link:

-
    -
  • Challenge references: https://github.com/community-access/accessibility-agents
    • -
  • Problem: This is external to git-going-with-github repo
    • -
  • Problem: No offline fallback if external repo is down or changes
    • -
  • Risk: Challenge becomes inaccessible if upstream project changes structure
    • -
-

Time Estimate Accuracy

-

ISSUE FOUND - Highly variable scope:

-
    -
  • Stated time in chapter header: "1.5 hours"
    • -

  • Detailed assessment:

    -
      -

    • Challenge 1: Agent Discovery Mapping (20 min stated)

      -
        -
      • Read ecosystem section: 5-10 minutes
        • -
      • Review agent list: 5-10 minutes (55 agents is a lot to review)
        • -
      • Match 3-5 agents to skills: 5-10 minutes
        • -
      • Write evidence comment: 3-5 minutes
        • -
      • Subtotal: 18-35 minutes (variable)
        • -
      -
      • -

    • Challenge 2: Agent Skill Validation (30 min stated)

      -
        -
      • Clone repo or open it: 2-5 minutes
        • -
      • Open Copilot Chat: 1 minute
        • -
      • Find agent reference in .github/agents/: 3-5 minutes (if structure is unclear, this is long)
        • -
      • Run agent with prompt: 1 minute
        • -
      • Wait for response and understand: 3-10 minutes (depends on agent complexity)
        • -
      • Answer 3 evaluation questions: 5-10 minutes
        • -
      • Subtotal: 15-31 minutes (highly variable)
        • -
      -
      • -

    • Challenge 3: Agent Instructions Deep Dive (15 min stated)

      -
        -
      • Find .agent.md or .prompt.md file: 3-5 minutes
        • -
      • Read instructions: 5-15 minutes (length varies by agent)
        • -
      • Answer questions about intent and mistakes: 5-10 minutes
        • -
      • Write evidence comment: 3-5 minutes
        • -
      • Subtotal: 16-35 minutes
        • -
      -
      • -
    -
    • -
  • Total (3 challenges): 49-101 minutes against stated 1.5 hours (90 minutes) — tight fit
    • -
-

"If You Get Stuck" Guidance

-

Adequate coverage:

-
    -
  • 6-step recovery:
      -
    1. Can't find agents → examples: @daily-briefing, @issue-tracker
      2. -
    2. Agent output doesn't make sense → file issue with error
      3. -
    3. Can't see agents in Chat → checklist (extension installed, signed in, .github/agents/ exists)
      4. -
    4. Clone failed → terminal command provided
      5. -
    5. Feedback form feels overwhelming → start with one question, any feedback is valuable
      6. -
    6. Still stuck → show facilitator agent output and expected result
      7. -
    -
    • -
-

Accessibility Assessment

-

Generally accessible:

-
    -
  • Agents run in Copilot Chat (requires Accessible View for screen reader users)
    • -
  • Agent instructions are text-based (accessible)
    • -
  • GitHub agent file exploration is browser-based (accessible)
    • -
  • No specific accessibility concerns
    • -
-

Learning Moment

-

Excellent: Explains "Skill First, Agent Second" principle and connects agents to manual expertise.

-

Recommendations

-

CHANGES REQUIRED:

-
    -

  1. Add Agent Discovery Framework:

    -
    **How to Find and Explore Agents:**
-
-Agents are organized in the accessibility-agents repository in the `.github/agents/` folder.
-
-**Three ways to discover agents:**
-
-1. **Browse by filename:** Open `.github/agents/` on GitHub and look for `.agent.md` files (naming pattern: `@agent-name.agent.md`)
-
-2. **Search by workflow:** Ask Copilot "Show me agents for [task]" — Copilot knows the agent ecosystem
-
-3. **Start with these beginner agents:**
-   - `@daily-briefing` — Summarizes your GitHub activity
-   - `@issue-tracker` — Helps track and organize issues
-   - `@pr-review` — Assists with code review
-
-You do NOT need to use all 55 agents. Pick 3-5 that match YOUR workflows.
    -
    2. -

  2. Add "Skill First" validation:

    -
    **Before using any agent, answer this question:**
-"Could I do this task manually right now, without the agent?"
-
-- If YES → You're ready to use the agent. It will amplify your skill.
-- If NO → Learn the manual skill first (see prerequisites table). The agent won't teach you the skill—only automate it.
-
-This is not about limiting you. It's about using AI as a multiplier, not a crutch.
    -
    3. -

  3. Add local exploration option:

    -
    **If you prefer to explore locally:**
-```bash
-# Clone the accessibility-agents repository
-git clone https://github.com/community-access/accessibility-agents.git
-cd accessibility-agents
-
-# List all agents
-ls .github/agents/*.agent.md
-
-# Read agent instructions
-cat .github/agents/daily-briefing.agent.md
    -
    -
    4. -

  4. Reduce overwhelm:

    -
    **Note:** There are 55 agents in the ecosystem. You are NOT expected to explore all of them.
-
-For this workshop, focus on these 3-5 agents that match Day 1 skills:
-- `@daily-briefing` (repository navigation)
-- `@issue-tracker` (working with issues)
-- `@pr-review` (working with PRs)
-- (Pick 1-2 more based on your interests)
-
-You can explore more agents after the workshop. This challenge is about understanding the principle, not seeing everything.
    -
    5. -

  5. Add "Capstone" emphasis:

    -
    **Most Important: Capstone Feedback Challenge**
-
-The feedback form is not optional, even though other challenges are optional.
-
-Why? Your honest feedback shapes the next cohort. 
-We read every response. We act on patterns we see.
-
-You've invested two days learning and building skills. 
-Your experience — what worked, what confused you, what you'll remember — 
-is the most valuable data we can collect.
-
-**If time is short:** Answer just one question on the feedback form. 
-Any feedback is better than none.
    -
    6. -
-

Summary Table: Issue Severity & Priority

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ChapterIssue CategorySeverityActionTimeline
4NoneDeploy as-is-
5NoneDeploy as-is-
6NoneDeploy as-is-
7Evaluation criteria clarityMediumAdd eval criteria + time estimateBefore Day 2
8Time estimate missingMinorAdd time estimateBefore Day 2
9Time estimate + screen reader testingMediumAdd completion evidence, test with ATBefore Day 2
10Platform + AT parity gapsHighTest Mac/VoiceOver; clarify github.dev vs desktopBefore Day 2
11Prerequisites + time estimateMediumEmphasize prereqs; revise timeBefore Day 2
12Write access assumption + AT testingHighAdd access note; test extension with screen readersBefore Day 2
13Subscription requirement buriedHighFlag upfront; add warning; add time estimateBefore Day 2
14NoneDeploy as-is (model chapter)-
15Prerequisites scattered + complexity underestimatedHighConsolidate prereqs; add YAML validation; show exampleBefore Day 2
16Overwhelm (55 agents) + discovery unclear + skill validationHighAdd discovery framework; reduce scope guidance; emphasize capstoneBefore Day 2
-

Critical Issues Requiring Immediate Action

-

Before Students Begin Day 2:

-
    -

  1. Chapter 13 (Copilot): Add Subscription Requirement Warning

    -
      -
    • Impact: High — students may not discover subscription requirement until running into authentication errors
      • -
    • Fix Time: 15 minutes
      • -
    -
    2. -

  2. Chapter 15 (Templates): Consolidate Prerequisites + Add YAML Validation

    -
      -
    • Impact: High — students with write access issues will be blocked; YAML errors are hard to debug
      • -
    • Fix Time: 30 minutes
      • -
    -
    3. -

  3. Chapter 16 (Agents): Add Discovery Framework + Reduce Scope

    -
      -
    • Impact: High — 55 agents without guidance leads to overwhelm and low completion
      • -
    • Fix Time: 45 minutes
      • -
    -
    4. -

  4. Chapter 5 (VS Code) + Chapter 12 (PR Extension): Screen Reader Testing

    -
      -
    • Impact: High — accessibility-first workshop cannot proceed without confirming AT compatibility
      • -
    • Fix Time: 2-4 hours (testing with NVDA, JAWS, VoiceOver)
      • -
    -
    5. -
-

Before Students Begin (or Early Day 1 Follow-up):

-
    -
  1. Chapter 10: Add completion evidence requirement + test notifications UI with screen readers
    2. -
  2. Chapter 11: Emphasize prerequisites; test git clone UI accessibility
    3. -
  3. Chapters 8, 8: Add missing time estimates
    4. -
-

Files Requiring Updates

-

CHALLENGES.md (learning-room/docs/)

-
    -
  • Chapter 8: Add evaluation criteria and time estimate
    • -
  • Chapter 9: Add time estimate
    • -
  • Chapter 10: Add completion evidence requirement
    • -
  • Chapter 5: Clarify Mac/VoiceOver; add realistic time range
    • -
  • Chapter 11: Emphasize prerequisites in hub summary
    • -
  • Chapter 12: Add write-access assumption note
    • -
  • Chapter 13: ADD SUBSCRIPTION WARNING (URGENT)
    • -
  • Chapter 15: Consolidate and expand prerequisites (URGENT)
    • -
  • Chapter 16: Add discovery framework and scope reduction (URGENT)
    • -
-

Chapter-specific docs (docs/NN-*.md)

-
    -
  • 05-vscode-accessibility.md: Clarify Mac/VoiceOver; github.dev vs desktop distinction
    • -
  • 13-github-copilot.md: Add JSON editing guidance and real-world time expectations
    • -
  • 15-issue-templates.md: Add YAML validation section; show before/after remix example
    • -
  • 16-accessibility-agents.md: Add local exploration alternative; agent discovery framework
    • -
-

Issue Template

-
    -
  • .github/ISSUE_TEMPLATE/challenge-hub.md: May need template variables for Chapter 13 subscription callout
    • -
-

Testing &Validation Checklist

-

Before deploying challenges to students:

-

Screen Reader Testing (NVDA, JAWS, VoiceOver)

-
    -
  • Ch 10: Notification inbox navigation and shortcuts
    • -
  • Ch 5: VS Code screen reader mode (Windows + Mac) and feature discovery
    • -
  • Ch 12: GitHub PR Extension UI accessibility
    • -
  • Ch 13: Copilot Chat response reading with Accessible View
    • -
-

Hands-on Flow Testing (Windows + Mac)

-
    -
  • Ch 4: Issue creation and claim workflow (end-to-end)
    • -
  • Ch 6: PR opening with Closes #XX template
    • -
  • Ch 7: Conflict marker resolution workflow
    • -
  • Ch 11: git clone → commit → push (on both platforms)
    • -
  • Ch 13: Copilot Chat without subscription (confirm error message is clear)
    • -
-

Prerequisite Verification

-
    -
  • Students can complete Chapter N without having completed Chapter N-1 (if claimed as standalone)
    • -
  • Time estimates hold true for 3-5 real students of varying backgrounds
    • -
-

Conclusion

-

The challenges are well-intentioned and generally well-designed, with strong pedagogical progression and accessibility-focused documentation. However, four chapters (10, 12, 13, 15, 16) require significant revisions before student deployment to avoid frustration and blockers.

-

Recommended action: Prioritize the High-severity issues (Chapters 13, 15, 16) for immediate fixes, then conduct screen reader testing on Chapters 5 and 12. All changes can be completed in 4-6 hours.

-

Audit Prepared: March 5, 2026
Audit Performed By: GitHub Copilot (Validation Agent)
Next Review: Post-deployment feedback incorporation (recommended after Day 2)

- -
- - - \ No newline at end of file diff --git a/html/CONTRIBUTING.html b/html/CONTRIBUTING.html index 5161460..d7d7243 100644 --- a/html/CONTRIBUTING.html +++ b/html/CONTRIBUTING.html @@ -401,5 +401,6 @@

11. Questions and Discussion

GIT Going with GitHub - A workshop by Community Access

View on GitHub · community-access.org

+ - \ No newline at end of file + diff --git a/html/DAY1_AGENDA.html b/html/DAY1_AGENDA.html deleted file mode 100644 index 04fa2ad..0000000 --- a/html/DAY1_AGENDA.html +++ /dev/null @@ -1,929 +0,0 @@ - - - - - - - Day 1 Agenda - GIT Going with GitHub - - - - - - - - -
-

Day 1 Agenda

-

Open Source Assistive Technology Hackathon - GitHub Learning Lab

-
-

Day 1 Focus: The GitHub web interface - navigating repositories, filing and responding to issues, understanding pull requests, and contributing through the browser using only your keyboard and screen reader.

-

How learning works today: Each participant works through two tracks in parallel. GitHub Skills modules give you a real repository in your own GitHub account, with a bot called Mona that responds to your actions automatically and guides you through each step. The shared learning-room repo is for group exercises and the collaborative contribution sprint. The two tracks reinforce exactly the same skills.

-
-

GitHub Skills Modules Used Today

-

Three modules run across Day 1. You will set each one up during the block where it is introduced - no pre-work required.

- - - - - - - - - - - - - - - - - - - - - - - -
ModuleWhenWhat Mona teaches
Introduction to GitHubBlocks 1-3Branches, commits, pull requests, merge
Communicate Using MarkdownBlock 3Headings, emphasis, links, code, task lists, tables
Review Pull RequestsBlock 4Assign reviewers, leave comments, suggest changes, approve, merge
-

How GitHub Skills modules work:

-
    -
  1. You navigate to the module URL and activate "Start course" - this copies the repository to your GitHub account
    2. -
  2. Mona (a GitHub Actions bot) reads your account's new repo, creates an issue with Step 1 instructions, and waits
    3. -
  3. You follow the instructions in the issue. When you complete a step - create a branch, open a PR, merge - Mona detects it and responds with the next step
    4. -
  4. Repeat until completion. You receive a course completion badge on your profile.
    5. -
-

Why this is different from a tutorial: You are not reading about GitHub. You are doing GitHub, in your own repository, and an automated system is verifying each step and giving you feedback. The mechanics are identical to what happens when you contribute to any real open source project.

-

Read This BEFORE Day 1 Starts

-

Chapter 3: The Learning Room - Your complete guide to the shared repo, PR sharing workflow, and how the automation system works. Read this before Block 0 to understand the environment where you'll be making real contributions.

-

At a Glance

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
BlockTimeTopicSkills Module
09:00 AMWelcome, setup verification, and introductions-
19:30 AMScreen reader orientation to GitHubIntroduction to GitHub (setup)
210:10 AMNavigating repositories and Markdown module setupIntroduction to GitHub (Steps 1-2) + Communicate Using Markdown (setup)
-11:00 AMBreak-
311:15 AMWorking with Issues and Pull RequestsIntroduction to GitHub (Steps 2-4)
412:10 PMPull Request review and mergeReview Pull Requests
-1:00 PMLunch-
52:00 PMYour first real contribution sprintlearning-room (group)
-3:00 PMBreak-
63:15 PMCommunity: culture, etiquette, labels, and notificationslearning-room (group)
-4:30 PMWrap-up, completions, and Day 2 preview-
-

Total: ~7.5 hours of structured time

-

Pre-Day Checklist

-

Before entering the room (or joining the call), participants should have completed everything in Pre-Workshop Setup. The facilitator will do a quick verification at the start.

-

GitHub Skills modules require no pre-work - they are set up together, in-session, during the blocks where they are used.

-

Block 0 - Welcome and Orientation (9:00 AM, 45 min)

-

Date & Location

-

Saturday, March 7, 2026 | 9:00 AM - 5:00 PM
Sunday, March 8, 2026 | 9:00 AM - 5:00 PM

-

Purpose

-

Make participants comfortable, set expectations, verify setups, and create a psychologically safe space for the day.

-

Activities

-

Facilitator introduces:

-
    -
  • The purpose of this session: building real, usable GitHub skills for open source AT contribution
    • -
  • What "contribution" means - it is not only code. Documentation, accessibility testing, issue triage, and feedback are all valuable contributions.
    • -
  • The "ask before you assume" norm - it is always OK to ask what something means
    • -
  • The two-track learning model: GitHub Skills (your own account) + learning-room (group exercises)
    • -
-

Quick setup verification (10 minutes):

-
    -
  • Can everyone navigate to the repo URL?
    • -
  • Does everyone's screen reader announce page headings?
    • -
  • Is hovercards turned off? (If not - navigate to Accessibility Settings now)
    • -
  • Can everyone access GitHub Issues and Pull Requests? (Modern experience may already be active - if not, verify via User Menu → Feature preview; see Step 4 in Pre-Workshop Setup)
    • -
-

Clone the learning-room repository (15 minutes): -Everyone will work in the shared learning-room repository today. Clone it now so it's ready for Block 5:

-
    -
  1. Open your terminal (or GitHub Desktop if you prefer GUI)
    2. -
  2. Navigate to where you store projects: cd ~/Documents (or your preferred location)
    3. -
  3. Clone the repository:
    git clone https://github.com/Community-Access/learning-room.git
-cd learning-room
    -
    4. -
  4. Verify you can see the files: ls (you should see README.md, docs/, etc.)
    5. -
  5. Optional: Open the folder in your code editor to explore the file structure
    6. -
-

Introductions:

-
    -
  • Each participant: your name, your screen reader and OS, what brings you here
    • -
-

Block 1 - Screen Reader Orientation to GitHub (9:30 AM, 40 min)

-

Purpose

-

Establish a shared navigation foundation AND set up the Introduction to GitHub Skills module. Every participant leaves this block with a real repository in their own account and a message from Mona waiting for them.

-

Key Concepts Covered

-
    -
  • Browse Mode vs Focus Mode - when to be in each
    • -
  • Single-key navigation: H (headings), D (landmarks), K (links), B (buttons), F (form fields)
    • -
  • The Elements List (NVDA+F7 / Insert+F3 JAWS / VoiceOver Rotor VO+U)
    • -
  • How GitHub uses landmarks - navigation, main, search-results
    • -
  • Submitting text with Ctrl+Enter
    • -
-

Part A - Navigate GitHub Together (15 min)

-

Navigate the GitHub homepage:

-
    -
  1. Open GitHub.com - what is announced? (heading level, landmark)
    2. -
  2. Press H repeatedly - list the headings aloud
    3. -
  3. Press D - what landmarks exist?
    4. -
  4. Open Elements List - how many links are on the page?
    5. -
-

Navigate the learning-room repo (group):

-
    -
  1. Go to github.com/Community-Access/learning-room
    2. -
  2. Find the repo name with 1 (h1)
    3. -
  3. Find the tab bar (Issues, Pull Requests, etc.) with D → repository navigation landmark
    4. -
  4. Navigate the files table with T then Ctrl+Alt+↓
    5. -
  5. Open README.md - read the "What Is in This Repository" table
    6. -
-

Explore the practice files: -The docs/ folder contains three files with intentional issues that you will fix during today's contribution sprint:

- - - - - - - - - - - - - - - - - - - - - - - -
FileWhat it containsWhat students will fix
docs/welcome.mdIntroduction to open source contributionThree [TODO] sections to complete (contributor backgrounds, evaluating issues, GitHub profile impact)
docs/keyboard-shortcuts.mdNVDA, JAWS, and VoiceOver shortcut tablesIntentional errors in keyboard shortcut references
docs/setup-guide.mdStep-by-step GitHub setup instructionsBroken links and incomplete steps
-
    -
  1. Open docs/welcome.md - navigate with H to read the headings. Notice the [TODO] markers. You will fix these during the contribution sprint in Block 5.
    2. -
-
-

Key insight: These files are intentionally imperfect. You will explore them in detail during Block 5 when you are ready to contribute. For now, notice the structure - headings, tables, links - and how your screen reader announces each one.

-
-

Part B - Set Up Your First GitHub Skills Repository

-
-

Magic Moment #1: You are about to copy a real repository to your own GitHub account. When you complete this, you will have made your first GitHub action - and Mona will respond automatically.

-
-

Group activity - follow together:

-
    -
  1. Navigate to the Introduction to GitHub skills course
    2. -
  2. Read the repository description with your screen reader
    3. -
  3. Find and activate the "Start course" button (NVDA/JAWS: B to navigate buttons; VoiceOver: VO+Right → find the button → VO+Space)
    4. -
  4. GitHub opens a "Create a new repository" page - fill in:
      -
    • Owner: your account
      • -
    • Repository name: accept the pre-filled name
      • -
    • Public or private: Public
      • -
    -
    5. -
  5. Activate "Create repository"
    6. -
-

Wait together: GitHub redirects you to your new repository. Mona is running in the background. Within 20 seconds, Mona will:

-
    -
  • Create an issue: "Welcome to GitHub!"
    • -
  • Tag you in it with @[your-username]
    • -
  • Post Step 1 instructions
    • -
-

Verify: Navigate to the Issues tab → open Issue #1. What does Mona say? Read it aloud using your screen reader.

-
-

This is the same mechanism used by open source projects with bot-assisted workflows - Dependabot, GitHub Actions CI, automated labelers. You are experiencing that pattern for the first time right now.

-
-

Reference Document

-

Screen Reader Cheat Sheet

-

Block 2 - Navigating Repositories (10:10 AM, 50 min)

-

Purpose

-

Participants can confidently explore any GitHub repository using only their screen reader and keyboard - both your own (Skills repo) and others.

-

Key Concepts Covered

-
    -
  • Anatomy of a repository page (tabs, description, files table, README)
    • -
  • Switching branches
    • -
  • Viewing a file's history
    • -
  • Reading a commit
    • -
  • Finding contributor information
    • -
-

Part A - Introduction to GitHub: Step 1 (20 min)

-

Mona's issue told you to create a branch. Before doing that, explore your new repository with your screen reader.

-
-

Screen reader navigation practice: Answer these questions using only keyboard navigation - no mouse.

-
-
    -
  1. How many files are in the root of your repo?
    2. -
  2. What is the repository description?
    3. -
  3. When was the README last committed (find the commit date in the file table)?
    4. -
  4. Who created the repo? (find the "About" sidebar)
    5. -
-

Now follow Mona's Step 1 instructions: Create a branch named my-first-branch

-
    -
  • Find the branch switcher button on the Code tab (B to navigate buttons → find "main")
    • -
  • Activate it, type the new branch name: my-first-branch
    • -
  • Activate "Create branch: my-first-branch"
    • -
-

Mona detects the new branch and updates the issue with Step 2 instructions.

-

Part B - Exploring the learning-room Repo (25 min)

-

Now practice the same navigation skills in the shared group repo.

-

Activity 2A - Repo Exploration: -Find the answers to these questions using keyboard navigation in learning-room:

-
    -
  1. How many files are in the docs/ folder?
    2. -
  2. What is the description of the repo?
    3. -
  3. Who opened the last commit?
    4. -
  4. When was docs/welcome.md last edited?
    5. -
  5. How many branches exist?
    6. -
-

Activity 2B - Reading Practice File Content:

-
    -
  1. Open docs/keyboard-shortcuts.md
    2. -
  2. Navigate to the NVDA section using 2 (H2 headings)
    3. -
  3. Find the "Single-Key Navigation" table with T
    4. -
  4. Read through the table rows - how many shortcuts are listed for NVDA?
    5. -
  5. Navigate to the VoiceOver section - what is the VoiceOver modifier key combination?
    6. -
  6. Open docs/CHALLENGES.md - navigate to "Beginner Challenges" with 2
    7. -
  7. Read Challenge 1 - which file does it ask you to fix, and what is the issue?
    8. -
-

Activity 2C - Reading a Commit:

-
    -
  1. Navigate to the Commits tab
    2. -
  2. Find the most recent commit - read its message aloud
    3. -
  3. Open that commit - navigate the diff with your screen reader
    4. -
  4. What file(s) changed, and what specifically changed?
    5. -
-

Activity 2D - Branch Navigation:

-
    -
  1. Open the branch dropdown (find the "main" button)
    2. -
  2. Switch to the day1-practice branch
    3. -
  3. Navigate to docs/ - do any files differ from main?
    4. -
  4. Switch back to main
    5. -
-

Part C - Set Up Communicate Using Markdown Skills Module (10 min)

-
-

The Markdown module runs alongside everything else you do today. Every comment you write, every issue you file, every PR description - you are practicing Markdown in real GitHub contexts.

-
-
    -
  1. Navigate to the Communicate Using Markdown skills course
    2. -
  2. "Start course" → create the repo in your account
    3. -
  3. Wait for Mona to create Issue #1 with Step 1 instructions
    4. -
  4. Read the instructions - Mona will walk you through: headers, emphasis, images, code blocks, task lists, and tables
    5. -
-

You will work through each Markdown step during the natural pauses in Blocks 3 and 4. Your facilitator will call out when to switch.

-

Reference Document

-

Navigating Repositories

-

Break (11:00 AM, 15 min)

-

Encourage participants to stand, stretch, and rest their ears. Screen reader listening is cognitively demanding work.

-

Block 3 - Working with Issues and Pull Requests (11:15 AM, 55 min)

-

Purpose

-

Participants can file, read, respond to, and navigate issues - and open their first pull request.

-

Catch-Up Buffer (5 min)

-

If you are still completing a Skills module step from Block 2, finish it now. If you are on pace, start a Communicate Using Markdown step - you will use Markdown in every activity from this point forward.

-

Key Concepts Covered

-
    -
  • What issues are and why they matter
    • -
  • Searching and filtering the issues list
    • -
  • Filing a new issue using a template
    • -
  • Commenting with Markdown - headings, bold, links, code, task lists
    • -
  • @mentions and cross-references
    • -
  • good first issue label
    • -
-

Part A - Introduction to GitHub: Step 2 - Add a File (15 min)

-

Mona's Step 2 instructions ask you to commit a new file to your my-first-branch branch.

-
    -
  1. Navigate to your Skills repo → switch to my-first-branch
    2. -
  2. Find and activate "Add file" button → "Create new file"
    3. -
  3. Name the file: PROFILE.md
    4. -
  4. In the editor (switch to Focus Mode): type a brief self-introduction:
    5. -
-
# Hello, I am [your name]
-
-I use [your screen reader] on [your OS].
-
-I am contributing to open source because...
-
    -
  1. Commit the file to my-first-branch (fill in a commit message → "Commit new file")
    2. -
-

Mona detects your commit and responds with Step 3 instructions: open a pull request.

-

Part B - Introduction to GitHub: Step 3 - Open a Pull Request (15 min)

-

Return to your introduction-to-github Skills repo. Mona has asked you to open a pull request from my-first-branch into main.

-
    -
  1. Navigate to the Pull Requests tab
    2. -
  2. Activate "New pull request"
    3. -
  3. The base should be main, the compare branch my-first-branch
    4. -
  4. Review the diff - your PROFILE.md appears as an addition
    5. -
  5. Fill in the PR title: Add my profile
    6. -
  6. In the PR description field (Focus Mode), write:\
    7. -
-
## What this adds
-
-A profile introduction for [your name].
-
-## Why
-
-Getting started with open source AT contributions.
-
    -
  1. Submit the PR
    2. -
-
-

Magic Moment #2: Mona will respond to your PR within seconds. Navigate to the Conversations tab of your new PR. Mona has left a comment - read it with your screen reader. This is automated feedback on your real GitHub action, from an actual GitHub Actions workflow running in your repository.

-
-

Part C - Issues Practice in learning-room (20 min)

-

Activity 3A - Find and read a challenge issue:

-
    -
  1. Navigate to learning-room Issues tab
    2. -
  2. Filter by good first issue label: type is:open label:"good first issue" in the filter bar
    3. -
  3. Open issue #1 - "Welcome! Introduce yourself"
    4. -
  4. Read the full issue description with your screen reader
    5. -
-

Activity 3B - Leave a comment on the welcome issue:

-
    -
  1. Navigate to the comment box (D → "Add a comment" landmark or region)
    2. -
  2. Switch to Focus Mode - type your introduction using Markdown:
      -
    • Use ## for a heading with your name
      • -
    • Bold your screen reader name with **NVDA** or **JAWS** or **VoiceOver**
      • -
    • Add a task list of things you want to learn:
      - [ ] Fix a broken link in setup-guide.md
-- [ ] Complete a [TODO] section in welcome.md
-- [ ] Add a keyboard shortcut to keyboard-shortcuts.md
      -
      • -
    -
    3. -
  3. Submit with Ctrl+Enter
    4. -
-

Activity 3C - File a new issue based on what you found:

-
    -
  1. Navigate to Issues → New issue
    2. -
  2. Choose the "Beginner Challenge" template (this maps to Challenge 1, 2, or 3 from CHALLENGES.md)
    3. -
  3. In the title, be specific: "Fix broken link in docs/welcome.md" or "Add missing NVDA shortcut to keyboard-shortcuts.md"
    4. -
  4. In the description, reference the file and line where you found the issue:
    ## What I found
-The `[DATE]` placeholder at the bottom of `docs/welcome.md` needs to be updated with today's date.
-
-## Which challenge
-Challenge 1: Update [DATE] Placeholder (from CHALLENGES.md)
    -
    5. -
  5. Submit - note the issue number. You will use Closes #XX in your PR during Block 5
    6. -
-

Reference Document

-

Working with Issues | GitHub Concepts Glossary

-

Block 4 - Understanding Pull Requests (12:10 PM, 50 min)

-

Purpose

-

Participants understand what pull requests are, how to read one, and how to participate in a review - by reviewing a PR that Mona creates specifically for them.

-

Catch-Up Buffer (5 min)

-

If you are still completing Step 2 or Step 3 from the Introduction to GitHub module, finish your current step now. If you are on pace, work through a Communicate Using Markdown step.

-

Key Concepts Covered

-
    -
  • Anatomy of a PR (title, description, base/compare branches)
    • -
  • Navigating the three PR tabs: Conversation, Commits, Files Changed
    • -
  • Reading a diff - additions, deletions, context lines
    • -
  • Reviewing a PR - inline comments, overall comments, approvals
    • -
  • Status checks
    • -
-

Part A - Set Up Review Pull Requests Skills Module (10 min)

-
-

Magic Moment #3: Instead of reviewing a pre-built PR in a shared repo, you are about to review a pull request that Mona creates exclusively for you, in your own repository. The content of the PR is real. Your review will be read by Mona and trigger the next step.

-
-
    -
  1. Navigate to the Review Pull Requests skills course
    2. -
  2. "Start course" → create the repo in your account
    3. -
  3. Wait for Mona to create Issue #1 and a practice pull request titled "Update the game over message"
    4. -
  4. Navigate to the Pull Requests tab - open the PR Mona created
    5. -
-

Part B - Review the Pull Request (25 min)

-

Work through Mona's instructions for the review:

-

Navigate the PR with your screen reader:

-
    -
  1. Read the PR title and description (Conversation tab)
    2. -
  2. Navigate to Commits tab - how many commits? Who authored them?
    3. -
  3. Navigate to Files Changed tab
    4. -
  4. Navigate the diff - what changed in which file?
    5. -
-

Leave an inline comment:

-
    -
  1. In Files Changed, navigate to the changed line
    2. -
  2. Find the comment button (screen reader note: in the New Files Changed Experience, changed lines have a comment button - use B to find it, or right-click/Shift+F10 on the line)
    3. -
  3. Type an inline comment: "This change improves clarity for users who have lost - good improvement."
    4. -
  4. Submit as "Start a review"
    5. -
-

Submit your review:

-
    -
  1. Back on the Conversation tab, navigate to "Finish your review"
    2. -
  2. Add an overall comment: "Good change. I've left one inline note."
    3. -
  3. Select "Approve"
    4. -
  4. Submit your review
    5. -
-
-

Mona responds: After you submit the approval, Mona merges the PR automatically and creates the next step.

-
-

Part C - Introduction to GitHub: Step 4 - Merge Your PR (10 min)

-

Return to your introduction-to-github Skills repo. Mona has been waiting for you to merge your own PR.

-
    -
  1. Navigate to your open PR ("Add my profile")
    2. -
  2. Confirm there are no merge conflicts (Mona will have noted this)
    3. -
  3. Find and activate the "Merge pull request" button
    4. -
  4. Confirm the merge
    5. -
  5. Navigate back to the Code tab - PROFILE.md now appears on main
    6. -
-
-

Magic Moment #4: The introduction-to-github course is now complete. Navigate to the Introduction to GitHub skills course - your completion badge appears on the course page. Your GitHub profile now shows this course as completed.

-
-

Reference Document

-

Working with Pull Requests

-

Lunch (1:00 PM, 60 min)

-

Block 5 - Your First Real Contribution Sprint (2:00 PM, 60 min)

-

Purpose

-

Every participant makes at least one real contribution to the learning-room repo. This block is where the mechanics practiced in the Skills modules get applied to a collaborative, real-world contribution - with both automated bot feedback AND another human reviewer on the other end.

-
-

The difference from Skills modules: Mona gave you instant, automated feedback. Now you will experience TWO types of feedback:

-
    -
  1. Bot feedback - instant, technical checking (accessibility, formatting, links)
    2. -
  2. Human feedback - considered, contextual suggestions (what matters most, creative ideas, encouragement)
    3. -
-

Both are valuable. Both are part of professional open source development.

-
-

Merge Conflicts: What to Expect (10 min)

-

When multiple contributors edit the same file at the same time, Git cannot automatically combine the changes. This is called a merge conflict. During this sprint, conflicts are likely because several participants will be editing docs/welcome.md simultaneously.

-

Before you start your challenge, read the conflict prevention strategies and resolution steps in Chapter 7: Merge Conflicts. Key points:

-
    -
  • Communicate with your team. If two people are both working on docs/welcome.md, coordinate who edits which [TODO] section.
    • -
  • Pull before you push. Always sync with the latest main before opening a PR.
    • -
  • If you see conflict markers (<<<<<<<, =======, >>>>>>>), do not panic. The markers show both versions. Keep the correct content, delete the markers, and commit.
    • -
-

The facilitator will walk through a live conflict resolution if one occurs during the sprint.

-

Setup

-

The learning-room repo has a docs/ folder with three intentionally imperfect practice files. Each participant will work on one of the first three challenges from docs/CHALLENGES.md:

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
ChallengeFileWhat to fixDifficulty
Challenge 1: Fix Broken Linkdocs/welcome.mdUpdate the [DATE] placeholder with today's date5-10 min
Challenge 2: Add Keyboard Shortcutdocs/keyboard-shortcuts.mdAdd a missing shortcut to the correct table15-20 min
Challenge 3: Complete Welcome Guidedocs/welcome.mdFill in the three [TODO] sections20-30 min
-

Know Your File Before You Fix It (5 min)

-

Before starting your challenge, explore the file you will be editing. This is the reconnaissance you previewed in Block 1 - now with purpose.

-

If your challenge targets docs/welcome.md (Challenges 1 and 3):

-
    -
  1. Open docs/welcome.md - press H to navigate through all headings
    2. -
  2. Find the [TODO] markers - these are the sections you will complete
    3. -
  3. Press K to check the internal links - is there a broken one?
    4. -
  4. Note the heading hierarchy: H1, H2, H3. Your additions must follow this pattern.
    5. -
-

If your challenge targets docs/keyboard-shortcuts.md (Challenge 2):

-
    -
  1. Open docs/keyboard-shortcuts.md - press 2 to navigate H2 sections (NVDA, JAWS, VoiceOver)
    2. -
  2. Press T to navigate into the shortcut tables
    3. -
  3. Read through the table rows - can you spot the intentional errors?
    4. -
  4. Check: does every screen reader section have the same set of shortcuts?
    5. -
-

If your challenge targets docs/setup-guide.md (Advanced):

-
    -
  1. Open docs/setup-guide.md - press K to navigate all links
    2. -
  2. Which links are broken? Where should they point?
    3. -
  3. Read the step-by-step instructions - which steps are incomplete?
    4. -
-

The challenges in docs/CHALLENGES.md map directly to these files and list success criteria for each. -Each participant will:

-
    -
  1. Find their assigned issue (which maps to one of these challenges)
    2. -
  2. Edit the practice file on GitHub
    3. -
  3. Commit, branch, and open a PR
    4. -
  4. Wait for bot feedback (watch for comment within 30 seconds)
    5. -
  5. Address bot feedback if needed
    6. -
  6. Request review from another participant
    7. -
  7. Review someone else's PR
    8. -
-

Full Workflow

-

Example walkthrough: Challenge 3 - Complete the welcome guide

-

This example shows the full workflow for filling in [TODO] sections in docs/welcome.md. Your actual challenge may differ.

-
Step 1: Find your issue
-  Issues tab → filter by Assignee: me
-  Open the issue - it says: "Complete the [TODO] sections in docs/welcome.md"
-  Read the full description - it references Challenge 3 from CHALLENGES.md
-
-Step 2: Navigate to the file
-  Code tab → docs/ folder → welcome.md
-  Read the file - find the [TODO] markers:
-    • "Who Can Contribute?" section: [TODO: Add a paragraph explaining 
-      that contributors come from all backgrounds...]
-    • "Finding Something to Work On" section: [TODO: Add two or three 
-      sentences about how to read an issue...]
-    • "After Your Contribution Is Merged" section: [TODO: Add a sentence
-      or two about what this means for someone's GitHub profile...]
-
-Step 3: Edit the file on GitHub
-  Find the edit pencil button (B for buttons → "Edit this file")
-  Switch to Focus Mode → replace each [TODO] with real content
-  Example for the first [TODO]:
-    "Contributors come from all backgrounds, skill levels, and 
-    countries. Using assistive technology is not a barrier to 
-    contribution - in fact, AT users bring a perspective that 
-    improves projects for everyone."
-
-Step 4: Commit and branch
-  Commit changes → select "Create a new branch"
-  Name: fix/[your-name]-issue-[number]
-  "Propose changes"
-
-Step 5: Open the Pull Request
-  Fill in the PR description using the template:
-    ## What Changed
-    Completed the three [TODO] sections in docs/welcome.md
-
-    ## Related Issue
-    Closes #[your-issue-number]
-
-    ## Checklist
-    - [x] All [TODO] markers removed
-    - [x] Content matches the style of existing sections
-    - [x] Heading hierarchy is correct (H1 → H2 → H3)
-
-WAIT FOR BOT (30 seconds)
-  The Learning Room bot will automatically comment on your PR
-  Read the comment carefully - it checks for:
-    • Issue reference (did you include "Closes #XX"?)
-    • File location (are changes in docs/ only?)
-    • Heading hierarchy (no H1→H3 skips)
-    • Link text quality (no "click here")
-    • [TODO] markers (did you remove them all?)
-  The bot explains WHY each issue matters and links to resources
-
-Step 6: Fix bot issues (if any)
-  Address any required checks the bot flagged
-  Push your changes to the same branch - the bot re-checks automatically
-
-Step 7: Request human review
-  Click "Reviewers" → select another participant
-  THE BOT IS NOT A SUBSTITUTE FOR HUMAN REVIEW
-  You need both: bot technical feedback + human judgment
-
-Step 8: Review someone else's PR
-  Find the PR opened by another participant
-  Leave a constructive comment addressing:
-    • The issues the bot flagged (did they fix them well?)
-    • Content quality (is the writing clear and inclusive?)
-    • Accessibility (do headings, links, and structure work for screen readers?)
-  Approve if it looks good
-

Other challenge examples:

-

Challenge 1 (Fix Broken Link): Open docs/welcome.md, find the broken internal link, determine the correct file path, and update the link. The bot will verify the link resolves correctly.

-

Challenge 2 (Add Keyboard Shortcut): Open docs/keyboard-shortcuts.md, find the appropriate screen reader section (NVDA, JAWS, or VoiceOver), add a missing shortcut to the table using proper Markdown table syntax. The bot checks that table formatting is preserved.

-

What the Bot Checks

-

The automation bot validates these things:

-
    -
  • Broken links - do internal and external links work?
    • -
  • Heading hierarchy - no skips (H1→H3), proper structure
    • -
  • Image descriptions - all images have meaningful alt text
    • -
  • Link text quality - links use descriptive text (not "click here")
    • -
  • [TODO] markers - all must be completed
    • -
  • Document formatting - tables, code blocks, lists are correct
    • -
-

The bot is educational. Every issue includes:

-
    -
  • What the problem is
    • -
  • WHY it matters (accessibility, clarity, usability)
    • -
  • HOW to fix it (with examples)
    • -
  • Links to learning resources
    • -
-

See: Learning Room Automation Guide for detailed explanation of bot feedback

-

What to look for in each practice file

-

docs/welcome.md (Challenges 1 and 3):

-
    -
  • Three [TODO] sections that need real content (see "Who Can Contribute?", "Finding Something to Work On", "After Your Contribution Is Merged")
    • -
  • A broken internal link to verify and fix
    • -
  • Heading hierarchy to check (H1 → H2 flow)
    • -
-

docs/keyboard-shortcuts.md (Challenge 2):

-
    -
  • NVDA, JAWS, and VoiceOver shortcut tables
    • -
  • Intentional errors in some shortcut references
    • -
  • Missing shortcuts that should be added
    • -
  • Table formatting that must be preserved
    • -
-

docs/setup-guide.md (Advanced challenges):

-
    -
  • Broken links to GitHub settings pages
    • -
  • Incomplete setup steps
    • -
  • A note at the bottom referencing [TODO] items
    • -
-

docs/CHALLENGES.md lists all 12 challenges with success criteria for each. When reviewing a peer's PR, check their work against the success criteria listed for their challenge.

-

docs/GROUP_CHALLENGES.md has 7 collaborative exercises if your study group wants to tackle something together after individual challenges.

-

Break (3:00 PM, 15 min)

-

Stand, stretch, and rest your ears. The contribution sprint demands focus. The final block is discussion-centered and lower intensity.

-

Block 6 - Community: Culture, Etiquette, Labels, and Notifications (3:15 PM, 75 min)

-

Purpose

-

Participants understand the human side of open source: how to communicate well, how to stay organized, and how to manage their GitHub notification experience.

-

Part 6A - Community Health Files (15 min)

-

Discussion: What makes an open source project a welcoming place?

-

Hands-on: Navigate the community health files in learning-room:

-
    -
  1. Read CODE_OF_CONDUCT.md - what does it commit to?
    2. -
  2. Read CONTRIBUTING.md - what does the project ask of contributors?
    3. -
  3. Read the Issue Templates - navigate to .github/ISSUE_TEMPLATE/ and open the beginner challenge template. What information does it require and why?
    4. -
  4. Read AUTOMATION.md - find the "Common Validation Issues and Fixes" section. This explains every bot feedback message you might see.
    5. -
-

Key insight: These files exist to lower barriers AND set expectations. A project with these files sends a signal of maturity and intention.

-

Part 6B - Communication and Review Culture (30 min)

-

Discussion: How to communicate in open source (10 min)

-

Open source communication is asynchronous. Your comment will be read out of context, by many people, over a long time. These principles matter:

-
    -
  • Clarity and precision: "I noticed X, which might cause Y" vs "This is wrong"
    • -
  • The difference between critiquing code and critiquing people
    • -
  • Handling disagreement: "I see it differently because..." rather than "No, that's incorrect"
    • -
  • Acknowledging effort: starting with what's working before identifying problems
    • -
  • Avoiding jargon and acronyms that exclude newcomers
    • -
-

The anatomy of a good review comment (10 min)

-

A useful comment includes:

-
    -
  1. What you noticed
    2. -
  2. Why it matters
    3. -
  3. A suggestion (optional but helpful)
    4. -
-

Example:

-
-

"The alt attribute on line 42 is empty. Screen readers will skip this image entirely, which means blind users miss the chart. A description like 'Bar chart showing monthly downloads from January to June' would help. Happy to help draft one if useful!"

-
-

Practices to demonstrate:

-
    -
  • Separating factual observations from preferences ("This might be a typo" vs "I personally prefer single quotes")
    • -
  • Using nit: to signal non-blocking suggestions
    • -
  • Asking clarifying questions instead of assuming intent
    • -
  • Marking your review as "Comment" when you are not sure whether something is a blocker
    • -
-

Exercise: Rewrite and write (10 min)

-

Rewrite these comments to be more inclusive:

-
    -
  1. "This is obviously wrong - anyone can see it doesn't handle nulls."
    2. -
  2. "LGTM but TBH this feels like over-engineering IMO."
    3. -
  3. "Fix this before EOD."
    4. -
-

Then write a review comment for this change: "A PR removes the <main> landmark element from a page."

-

Part 6C - Labels, Milestones, and Cross-References (20 min)

-

Labels - organizing intent:

-
    -
  • Creating a label: Issues → Labels → New label
    • -
  • Applying labels from the issue sidebar
    • -
  • Filtering issues by multiple labels
    • -
  • Label naming conventions
    • -
-

Milestones - organizing time:

-
    -
  • Navigate to Issues → Milestones
    • -
  • Open the "Hackathon Day 1" milestone
    • -
  • Add your issue to it from the sidebar
    • -
-

Cross-references - linking work:

-
    -
  • From a PR description: Closes #42 auto-closes the issue on merge
    • -
  • Referencing across repos: owner/repo#42
    • -
  • From comments: type # and a number
    • -
-

Part 6D - Notifications: Taking Control of Your Inbox (10 min)

-

Concepts:

-
    -
  • GitHub Notifications inbox: github.com/notifications
    • -
  • Subscribed vs Participating vs @mentioned
    • -
  • Notification preferences per repository
    • -
  • The "Done" button
    • -
-

Hands-on:

-
    -
  1. Navigate to your Notifications inbox
    2. -
  2. Find the notification from your PR comment
    3. -
  3. Mark it as Done
    4. -
  4. Change learning-room Watch settings to "Participating and @mentions only"
    5. -
-

Wrap-Up and Day 2 Preview (4:30 PM, 30 min)

-

Skills Module Completion Check (10 min)

-
-

Magic Moment #5: Before the Day 2 preview, check your completions.

-
-
    -
  1. Navigate to the Introduction to GitHub skills course - completed?
    2. -
  2. Navigate to the Review Pull Requests skills course - completed?
    3. -
  3. Navigate to the Communicate Using Markdown skills course - how many steps complete?
    4. -
  4. Navigate to your GitHub profile - what appears there now?
    5. -
-

These completions are yours permanently. They travel to every GitHub profile page you have. They are evidence of skills, not just reading.

-

Reflection (10 min)

-
    -
  • What is one thing you did not know before today?
    • -
  • What is one thing you want to get better at?
    • -
  • What is one contribution you want to make to a real accessibility project this week?
    • -
-

Day 2 Preview (10 min)

-

Tomorrow we move from the browser to Visual Studio Code. Here is what is coming:

-
    -
  • VS Code Screen Reader Mode - Accessible Help (Alt+H), Accessible View (Alt+F2), Accessible Diff Viewer (F7)
    • -
  • Accessibility Agents - your earned reward for completing Day 1. An ecosystem of 55 AI agents across 3 teams and 5 platforms that amplify the exact skills you built today. Explore the agents that match your interests and workflows - there is no fixed subset you are required to use.
    • -
  • Ship a real PR upstream - community-access/accessibility-agents is a live repository. Your name in its commit history is the Day 2 capstone.
    • -
-
-

Start thinking now: Accessibility Agents has 26 agents for accessibility auditing (web, documents, mobile, ePub), 12 for GitHub workflows, and 6 for developer tools. As you reflect on today's experience - navigating repositories, filing issues, reviewing PRs by hand - ask yourself:

-
    -
  • What took the longest? What was repetitive?
    • -
  • What would be easier if an AI agent could handle the mechanical parts?
    • -
  • What accessibility problem have you encountered that no tool addresses well?
    • -
-

Tomorrow you will see the agents in action and have the opportunity to contribute new agents, improve existing ones, or shape the project's roadmap. The best contributions come from people who have done the manual work first - and that is exactly what you did today.

-
-

Tonight (optional):

-
    -
  • Install VS Code and the GitHub Copilot Chat extension (see Pre-Workshop Setup)
    • -
  • Complete any Markdown Skills module steps you didn't finish
    • -
  • Explore docs/GROUP_CHALLENGES.md - 7 collaborative exercises your study group can tackle together
    • -
  • Fork accessibility-agents - it will be ready and waiting when you open VS Code tomorrow
    • -
  • Browse the 55 agents by team - which ones spark ideas for you?
    • -
-

Facilitator Notes

-

Sandbox Repo Setup Required Before Day 1

-

Create the learning-room repo in your org with the following:

-

Pre-seeded issues:

-
    -
  • #1 - "Welcome! Introduce yourself" (open, labeled good first issue, no assignee)
    • -
  • #2 through #N - pre-assigned to each participant, each mapping to a specific challenge from docs/CHALLENGES.md:
      -
    • Challenges 1-3 (Beginner): Fix broken link in welcome.md, add shortcut to keyboard-shortcuts.md, complete [TODO] sections in welcome.md
      • -
    • Challenges 4-6 (Intermediate): Fix heading hierarchy, improve link text, add alt text across docs
      • -
    • Advanced challenges for faster students: review, documentation creation, mentoring
      • -
    -
    • -
  • Several unlabeled "triage practice" issues for Part 6E
    • -
  • One issue labeled accessibility with a realistic AT-related bug report for reference
    • -
-

Pre-seeded PR:

-
    -
  • "Fix typo in keyboard-shortcuts.md" - a clean PR fixing a minor error in the NVDA shortcuts table, with a meaningful diff, at least two commits, and active status checks. This is the PR students examine in Block 4.
    • -
-

Pre-created branch: day1-practice with edits to docs/welcome.md and docs/setup-guide.md that differ from main (used in Block 2 Activity 2D)

-

Files included in learning-room repo:

-
learning-room/
-├── README.md                           ← Getting started guide with file inventory
-├── AUTOMATION.md                       ← Bot feedback guide with fix examples
-├── CODE_OF_CONDUCT.md
-├── CONTRIBUTING.md
-├── .github/
-│   ├── ISSUE_TEMPLATE/
-│   │   ├── config.yml
-│   │   ├── beginner-challenge.yml
-│   │   ├── intermediate-challenge.yml
-│   │   └── advanced-challenge.yml
-│   ├── PULL_REQUEST_TEMPLATE.md        ← Checklist template students fill out
-│   ├── workflows/
-│   │   ├── learning-room-pr-bot.yml    ← PR validation + educational feedback
-│   │   ├── skills-progression.yml      ← Progress tracking + badge awards
-│   │   └── student-grouping.yml        ← Auto-assigns peer reviewers
-│   └── scripts/
-│       └── validate-pr.js              ← Validation logic (checks headings, links, TODOs)
-├── docs/
-│   ├── CHALLENGES.md                   ← 12 challenges: Beginner → Expert
-│   ├── GROUP_CHALLENGES.md             ← 7 collaborative exercises
-│   ├── welcome.md                      ← 3 [TODO] sections + broken link (Challenges 1, 3)
-│   ├── keyboard-shortcuts.md           ← NVDA/JAWS/VO tables with errors (Challenge 2)
-│   └── setup-guide.md                  ← Broken links + incomplete steps (Advanced)
-└── [GITHUB_SKILLS.md]                  ← Self-paced GitHub Skills module reference
-

Pacing Tips for Skills Modules

-
    -
  • Block 1, Part B: Allow 10 minutes for every participant to copy the Skills repo and see Mona's first message. If someone does not see Mona's response within 2 minutes, check: was the repo created as public? (Mona requires public visibility on the free tier.)
    • -
  • Block 3, Part A: Participants work at different speeds. Have a "bonus" ready: while waiting for Mona, participants can start the Communicate Using Markdown module setup.
    • -
  • Block 4, Part A: The review-pull-requests module creates its PR automatically. Give everyone 5 minutes to copy the repo before moving to Part B - Mona needs time to set up the PR.
    • -
  • If a Skills module step gets stuck: Do not spend more than 5 minutes unblocking one participant's bot issue. Have them watch your screen while you continue with the group, and revisit during activity periods.
    • -
  • Completion badges: Not all participants will complete every module in-session. This is fine - the repos are theirs, Mona is waiting, and they can finish on their own time.
    • -
-

Day 2: Day 2 Agenda -Related: Navigating Repositories | Working with Issues | Working with Pull Requests

- -
- - - \ No newline at end of file diff --git a/html/DAY2_AGENDA.html b/html/DAY2_AGENDA.html deleted file mode 100644 index 3b240e2..0000000 --- a/html/DAY2_AGENDA.html +++ /dev/null @@ -1,714 +0,0 @@ - - - - - - - Day 2 Agenda - GIT Going with GitHub - - - - - - - - -
-

Day 2 Agenda

-

From Contributor to Product Maker - Igniting the Forge

-

Date: Sunday, March 8, 2026 | 9:00 AM - 5:00 PM

-
-

The premise of Day 2: You spent Day 1 (Saturday, March 7) learning how GitHub works - by hand, in the browser, with your screen reader. You filed real issues. You opened a real pull request. You reviewed someone else's work. Those skills are yours now.

-

Day 2 is about what you can build with those skills. You will deepen your contributions using VS Code and GitHub Copilot. You will use Accessibility Agents - a live, public accessibility project built by your facilitator - not as a shortcut around the skills you learned, but as a product you can understand, evaluate, critique, and improve because you now know exactly what it is doing and why.

-

You will leave with your name in the commit history of a real open source project and a set of tools you can use on any GitHub repository you ever work on.

-
-

At a Glance

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TimeBlockTheme
9:00-9:30Block 0 - Day 1 DebriefReinforce skills, surface questions, set goals
9:30-10:30Block 1 - VS Code SetupScreen reader mode, Accessibility Agents as workspace, navigation
10:30-10:45Break-
10:45-12:00Block 2 - Deep ContributionCopilot Chat, inline suggestions, richer PR work
12:00-13:00Lunch-
13:00-14:00Block 3 - Activate the AgentsFirst live agent commands - after earning them
14:00-15:00Block 4 - Agentic WorkflowsCloud agents, GitHub Actions, the full reach
15:00-15:15Break-
15:15-16:15Block 5 - Ship Your ContributionReal PR upstream to community-access/accessibility-agents
16:15-17:00Block 6 - Spec Kit: Design the FutureGroup speccing session - what comes next
17:00-17:30Wrap-UpNames in history, reflections, next steps
-

Block 0 - Day 1 Debrief

-

9:00-9:30

-

Purpose

-

Close the loop on Day 1. Celebrate what was shipped. Surface anything incomplete. Set the Day 2 mindset: you are not a learner today - you are a product maker.

-

Facilitator-Led Discussion

-
    -
  • "Show me your merged PR from yesterday." (30-second screen reader tour - navigate to pull requests tab, filter by closed, confirm the merge)
    • -
  • "What did you file an issue about? Is it still open or was it triaged?"
    • -
  • "What felt hard yesterday? What clicked?"
    • -
-

Day 2 Goal-Setting

-

Each participant states one contribution goal for the day. Examples:

-
    -
  • "I want to add a new slash command to accessibility-agents for tracking accessibility issues."
    • -
  • "I want to improve the screen reader output of the @daily-briefing report."
    • -
  • "I want to write documentation for the @insiders-a11y-tracker agent."
    • -
-

Write it down. You will check it against reality at 5pm.

-

Block 1 - VS Code Setup

-

9:30-10:30

-
-

This block builds on VS Code: Setup & Accessibility Basics, Git & Source Control in VS Code, and GitHub Pull Requests Extension for full reference.

-
-

Purpose

-

Move from browser-based GitHub to VS Code as your contribution environment. Set up screen reader mode. Open accessibility-agents as a workspace. Understand what you are looking at before any agent runs.

-

Step 0 - Bridge: Try github.dev Before Installing Anything

-

Before touching the desktop install, spend five minutes in github.dev. This is VS Code - running in your browser - with no install required. The keyboard shortcuts and screen reader mode are identical to the desktop app.

-
    -
  1. Open github.dev/community-access/accessibility-agents in your browser
    2. -
  2. Press Shift+Alt+F1 to enable screen reader mode inside github.dev
    3. -
  3. Press Ctrl+Shift+E - the Explorer panel opens with the full file tree
    4. -
  4. Navigate to .github/agents/daily-briefing.agent.md and press Enter to open it
    5. -
  5. Press Ctrl+Shift+P and type markdown preview - select "Markdown: Open Preview"
    6. -
-

You just used VS Code. The desktop is the same experience. The only differences: github.dev has no terminal, no Copilot, and no Accessibility Agents. Those are precisely what the desktop adds - and why the desktop is worth installing.

-
-

All keyboard shortcuts you practice here (Ctrl+Shift+E, Ctrl+P, Ctrl+Shift+P, Ctrl+G, F3) will work identically on the desktop. There is no ramp-up - you are already there.

-
-

Step 1 - Enable Screen Reader Mode

-

VS Code has a dedicated screen reader accessibility mode that adjusts verbosity, focus behavior, and announcement patterns.

- - - - - - - - - - - - - - - - - - - -
Screen ReaderHow to Activate VS Code Screen Reader Mode
NVDAOpen VS Code → VS Code detects NVDA automatically → or press Shift+Alt+F1
JAWSOpen VS Code → JAWS detection is automatic → or press Shift+Alt+F1
VoiceOverOpen VS Code → Shift+Alt+F1 → confirm the dialog
-

Verify it is active: Open the Command Palette (Ctrl+Shift+P) → type accessibility → you should see "Toggle Screen Reader Accessibility Mode" with a checkmark.

-

Key setting to check: Open Settings (Ctrl+,) → search accessibility support → confirm it shows on.

-

Step 2 - Fork, Clone, and Open Accessibility Agents

-

Before you can work on Accessibility Agents locally, you need your own copy (a fork) and a local clone of that fork.

-

Fork the repository (browser - a Day 1 skill):

-
    -
  1. Navigate to github.com/community-access/accessibility-agents
    2. -
  2. Find and activate the Fork button (B to navigate buttons)
    3. -
  3. Keep the defaults and activate Create fork
    4. -
  4. GitHub redirects you to your fork: github.com/[your-username]/accessibility-agents
    5. -
-

Clone the fork (VS Code terminal - your first Git command):

-
    -
  1. Open a terminal in VS Code (Ctrl+Backtick)
    2. -
  2. Navigate to where you want to store projects: cd ~/Documents (or your preferred folder)
    3. -
  3. Clone your fork:
    git clone https://github.com/[your-username]/accessibility-agents.git
    -
    4. -
  4. Enter the project folder: cd accessibility-agents
    5. -
  5. Open VS Code in that folder: code .
    6. -
  6. VS Code opens with the accessibility-agents repository as your workspace
    7. -
-
-

Screen reader note: The git clone command prints progress messages. When you hear the terminal go quiet, it is done. The folder now exists on your machine.

-
-

What to navigate first (with screen reader):

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
VS Code AreaKeyWhat You Hear
Explorer sidebarCtrl+Shift+EFile and folder tree
.github/agents/ folderArrow keys55 .agent.md files across three teams
.github/prompts/ folderArrow keys54+ slash command template files
Documentation/ folderArrow keysGETTING-STARTED.md, GUIDE.md
ai-instructions/ folderArrow keysCopilot, Claude, OpenAI integration guides
-

Hands-on task: Navigate to .github/agents/daily-briefing.agent.md. Open it. Read the first 20 lines using Ctrl+Home then Down Arrow. You are reading the instructions that tell Copilot how to think about your GitHub account. This is how agents work - plain language, no magic.

-

Step 3 - Read One Agent File Before Anything Else

-

Before you issue a single agent command, read the .agent.md file for that agent.

-
    -
  • What repositories does it target by default?
    • -
  • What output format does it produce?
    • -
  • What permissions does it need?
    • -
-

This is the same quality check you would apply to any open source code: read it before you run it.

-

Step 4 - Open Copilot Chat

-

Press Ctrl+Shift+I to open the Chat panel.

-

NVDA users: The chat input field is announced as "Chat input." Use Tab to move between the input and the response area. Use Ctrl+Alt+Arrow to navigate within the response.

-

JAWS users: The chat interface is a web-based panel. Switch to Forms Mode (Enter on the input field) to type. Tab out of the input to reach the conversation area in Virtual/Reading mode.

-

VoiceOver users: VO+Tab to the chat input. VO+Shift+Down to interact with it. VO+Escape to stop interacting and navigate the response.

-

Block 2 - Deep Contribution with Copilot

-

10:45-12:00

-

Copilot Orientation (15 min)

-

Before diving into contributions, get familiar with how Copilot works as a writing partner.

-

Inline suggestions (Ctrl+I):

-
    -
  1. Open any .md file in the workspace
    2. -
  2. Place your cursor at the end of a line and press Ctrl+I
    3. -
  3. Type a prompt: Add a sentence explaining why this agent uses heading navigation
    4. -
  4. Copilot suggests text inline. Press Tab to accept, Escape to dismiss
    5. -
  5. Screen reader note: NVDA announces "Inline suggestion" when one appears. Press Alt+] to read the suggestion before accepting
    6. -
-

Chat as a thinking partner:

-
    -
  1. Open Chat (Ctrl+Shift+I) if not already open
    2. -
  2. Type: Explain what the daily-briefing agent does in plain English
    3. -
  3. Read the response. Use H (heading navigation) to jump between sections
    4. -
  4. Try: What are three ways I could improve this agent for screen reader users?
    5. -
-

Key principle: Copilot drafts. You decide. Every suggestion should be read, evaluated, and edited before committing. Your name goes on the commit.

-

Purpose

-

Make a richer contribution to your fork of accessibility-agents using Copilot as a writing partner - not a replacement for your judgment. Copilot helps you articulate ideas you already have. The idea - the product intention - is yours.

-

What "Product Maker" Means Here

-

A product maker does not just report bugs or fix typos. A product maker looks at something that exists, understands what it is for, identifies a gap, and proposes a meaningful improvement.

-

In the context of accessibility-agents, that might be:

-
    -
  • A new slash command (a .md file in .github/prompts/)
    • -
  • An improvement to an existing agent's output format for screen reader users
    • -
  • A missing section in the Documentation/GUIDE.md
    • -
  • An accessibility improvement to the HTML output format
    • -
  • A new AI platform integration in ai-instructions/
    • -
-

Your contribution does not require code. Every agent, every prompt, every documentation improvement is a Markdown file.

-

Using Copilot as a Writing Partner

-

Open the file you want to improve. Press Ctrl+I to open inline chat.

-

Examples of effective Copilot prompts for this context:

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
What You WantWhat to Type
Explain what an existing agent file doesExplain what this agent does in plain English. What are its strengths and limitations?
Draft a new slash commandHelp me write a new prompt template for [your idea]. It should follow the same structure as the existing files.
Improve screen reader outputThis agent generates HTML output. How can I improve the heading hierarchy and ARIA landmark structure for screen reader users?
Write documentationWrite a documentation section explaining [concept] for someone who uses a screen reader and is new to GitHub.
Check your own writingReview this Markdown file for clarity, tone, and completeness. Flag anything that might be unclear to a first-time contributor.
-

Hands-On Activity: Draft Your Contribution

-
    -
  1. Identify one file in accessibility-agents you want to improve
    2. -
  2. Read the file completely using your screen reader before suggesting any changes
    3. -
  3. Use Copilot Chat to help you draft your improvement
    4. -
  4. Review Copilot's output critically - edit, improve, make it yours
    5. -
  5. Commit the change to your branch: git add . → git commit -m "your message"
    6. -
-

Branch naming: Follow the accessibility-agents contributing conventions:

-
    -
  • Features: feature/your-description
    • -
  • Fixes: fix/what-you-fixed
    • -
  • Documentation: docs/what-you-documented
    • -
-

Contribution Checkpoint (before lunch)

-

Before leaving for lunch, check your progress:

-
    -
  • On pace: You have at least one commit on a named branch. You are ready for Block 3.
    • -
  • Almost there: You have identified a file and started drafting but have not committed yet. Use the first 10 minutes after lunch to finalize your commit before the agent demonstrations begin.
    • -
  • Still exploring: You have not yet identified a file to improve. During lunch, read through the .github/agents/ files and pick one. When Block 3 starts, the facilitator will demo agents on the repository - watching those demos will help you see where improvements are needed.
    • -
-

Block 3 - Activate the Agents

-

13:00-14:00

-
-

This block is the payoff. You earned it yesterday. You understand what GitHub is, how repositories work, what issues and pull requests are, and how notifications flow. Now you watch an agent do the work you know how to verify.

-

If you have any doubt about whether you have earned a particular agent: the prerequisite is simple. Can you do the equivalent step manually, right now, from memory? If yes - the agent is ready to amplify you. If no - do the manual step first. The block is structured so this never happens, but the standard is worth knowing.

-
-

Why the Order Matters

-

Agents are run in a specific sequence - from broadest to most specific, from observation to action. This is not arbitrary. Each agent in this block builds on the skill directly before it.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StepAgentSkill It AmplifiesDay 1 Source
1@daily-briefingReading your notification inbox and activity summaryNavigating Repos + Notifications
2@issue-trackerTriaging and prioritizing issues manuallyWorking with Issues + Labels & Milestones
3@pr-reviewManually reviewing a PR diff and writing inline commentsWorking with Pull Requests
4@insiders-a11y-trackerFiling accessibility bugs and applying WCAG labelsWorking with Issues + Labels & Milestones
-

@analytics is available as an extension if Block 3 runs ahead of schedule - it requires understanding contribution graphs and activity history.

-

The Demonstration Sequence

-

The facilitator runs each command live. Participants follow along in their own VS Code + Copilot Chat.

-

Before each command, the facilitator asks: -"If you ran this command manually - without an agent - what would you do? Where would you go? What would you look for?"

-

Participants answer from their Day 1 knowledge. Then the command runs. Then the room compares the agent's output to the manual process.

-

1. @daily-briefing morning briefing

-

What the agent does: Sweeps every repository you have access to - issues opened in the last 24 hours, PR review requests awaiting you, CI failures on your branches, security alerts, community reactions to your comments - and delivers it as one prioritized document.

-

What you already know: You navigated each of these areas manually yesterday. The Issues tab. The Pull Requests tab. The Actions tab. The notification inbox. The agent is visiting all of those places - you know exactly what it found because you know where it went.

-

Screen reader tip: The briefing output is announced as a long document. Use H (heading navigation in virtual mode) to jump between sections: "Open Issues," "Review Requests," "CI Alerts," etc. Each section is a heading level 2.

-

Verify one item: The agent lists an issue. Navigate to that issue in your browser using the link in the output. Confirm the information matches. This is your quality check - you still know how to verify independently.

-

2. @issue-tracker find open issues labeled good-first-issue

-

What the agent does: Searches every repository you have access to for issues labeled good-first-issue, scores them by community engagement and release timing, and returns a prioritized list with discussion context.

-

What you already know: Yesterday you filtered the Issues tab by label. You read issue descriptions. You identified which ones had active discussion. The agent is applying a scoring algorithm to the same information.

-

Hands-on: From the agent's list, pick one issue in a repository you have not contributed to before. Read the full issue - navigate to it in your browser. Is the agent's priority score reasonable? What context does the agent's summary miss?

-

3. @pr-review review PR #[your PR number]

-

What the agent does: Generates a full review document for your pull request: line-numbered diff, change map, risk assessment, before-and-after snapshot, CI results, and suggested inline review comments.

-

What you already know: Yesterday you read diffs manually on the Files Changed tab. You wrote inline comments. You submitted a batched review. You know what a good review looks like.

-

Critical exercise: Compare the agent's suggested comments to what you wrote manually in your Day 1 review.

-
    -
  • Did the agent catch things you missed?
    • -
  • Did the agent miss context you knew from the issue thread?
    • -
  • Is the agent's tone aligned with the community standards from Culture and Etiquette?
    • -
-

Edit the agent's output before posting any of it. Your name goes on it.

-

4. @insiders-a11y-tracker - Accessibility Change Monitoring

-

What the agent does: Monitors accessibility-relevant changes across your configured repositories - WCAG/ARIA cross-referenced, tracking anything that touches keyboard navigation, ARIA attributes, focus management, color contrast, or screen reader labels.

-

Hands-on: Run @insiders-a11y-tracker check recent changes in accessibility-agents. Look at the HTML output files. Does your Day 2 contribution affect any accessibility-sensitive areas? If yes, the agent flags it. If no, confirm that is accurate.

-

This agent is quality assurance for the accessibility quality of your own contribution - before you submit it for review.

-

Stand and Stretch (5 min)

-

The agents are running. Step away from the screen for five minutes. Screen reader listening for an hour after lunch is demanding. When you return, Block 4 shows you how these same agents run in the cloud - without you pressing a key.

-

Block 4 - GitHub Agentic Workflows

-

14:00-15:00

-
-

Reference: GitHub Actions and Workflows - read the "Day 2 Bridge" section at the bottom before this block.

-
-

The Cloud Extension: What Agentic Workflows Are

-

Everything in Block 3 ran in VS Code - on your machine, on demand, when you asked for it. GitHub Agentic Workflows run in the cloud, inside GitHub Actions, on any trigger you define: when an issue is opened, on a schedule, when a PR is created.

-

The .agent.md pattern in Accessibility Agents and the GitHub Agentic Workflows .md pattern share the same philosophy: describe your intent in plain language, let a coding agent execute it. Both are plain text files in .github/. Both travel with every fork.

-

Reading a Workflow File - Step by Step

-

Open accessibility-agents/.github/ in VS Code Explorer. If a .github/workflows/ directory exists, navigate to it. The facilitator will walk through an example agentic workflow file.

-

Anatomy of a GitHub Agentic Workflow:

-
on:
-  issues:
-    types: [opened]
-permissions:
-  issues: write
-safe-outputs:
-  - add-comment
-  - add-label
-tools:
-  - copilot
-
-When a new issue is opened, read its title and body.
-Determine which category it belongs to: bug report, feature request,
-accessibility issue, documentation gap, or question.
-Apply the matching label. Post a friendly first-response comment
-acknowledging the issue and explaining what happens next.
-Do not close the issue. Do not merge anything. Do not modify any files.
-

What to notice:

-
    -
  • on: issues: types: [opened] - this is the same trigger system from standard GitHub Actions YAML
    • -
  • permissions: issues: write - explicit, minimal permissions; the agent cannot write to code or PRs
    • -
  • safe-outputs - a whitelist of what the agent is allowed to do; anything not listed is blocked
    • -
  • The instructions are plain English - readable, auditable, understandable by any contributor
    • -
-

Live Demonstration: File an Issue, Watch the Agent Respond

-
    -
  1. The facilitator has a demo workflow configured in a test repository
    2. -
  2. A participant files a new issue (using the manual process they learned on Day 1)
    3. -
  3. The room watches the Actions tab - the agentic workflow triggers within 60 seconds
    4. -
  4. The workflow reads the issue, applies a label, and posts a first-response comment
    5. -
  5. The participant reads the agent's comment using their screen reader
    6. -
  6. Discussion: "Is the label correct? Is the comment tone right? What would you change in the workflow instructions?"
    7. -
-

Screen reader tip for Actions tab: Navigate to the repository's Actions tab (T from the tab bar). The workflow run list is a series of list items. Each is announced with the workflow name, run status (queued/in progress/completed), and timestamp. Press Enter to open a run and read its steps.

-

Key Principles of Safe Agentic Workflows

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PrincipleWhat It Means
Read-only by defaultAgents cannot write code, merge PRs, or push to branches
Safe-outputs modelOnly explicitly listed actions are permitted
Defense-in-depthSandboxing, tool allowlisting, network isolation
No auto-mergeEvery change goes through a human-reviewed pull request
TransparentEvery action the agent takes is logged in the Actions run
AuditableThe plain-language workflow file is the contract
-

The Reach of Agentic Thinking

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ScopeToolWhere It Runs
Your editor, on demandAccessibility Agents in VS CodeYour machine
Your repo, travels with forksAccessibility Agents .github/agents/Any contributor's machine
Cloud, runs on any triggerGitHub Agentic WorkflowsGitHub Actions infrastructure
Cloud, scheduledAgentic Workflow with schedule: triggerGitHub Actions, no human required
-

Block 5 - Ship Your Contribution

-

15:15-16:15

-

Purpose

-

Polish and submit your real pull request upstream to community-access/accessibility-agents. Not to your fork - to the original. This is the moment the product maker mindset becomes tangible.

-

If Your Contribution Is Still in Progress

-

If you did not finish your commit during Block 2, use the first 15 minutes of this block to finalize:

-
    -
  1. Open the file you were working on in VS Code
    2. -
  2. Use Copilot (Ctrl+I) to help you finish any incomplete sections
    3. -
  3. Commit: git add . then git commit -m "your message"
    4. -
  4. Then proceed to the Pre-Submission Checklist below
    5. -
-

Pre-Submission Checklist

-

Before opening the PR, run through this with your screen reader:

-
□ My branch has a clear descriptive name (feature/, fix/, or docs/)
-□ I committed with a clear, present-tense message
-□ I read my changes back using VS Code's diff view (Ctrl+Shift+G → select file)
-□ I ran @insiders-a11y-tracker to confirm no accessibility regressions
-□ I filled in the accessibility-agents PR template completely:
-    □ Description: what this adds or fixes and why
-    □ Type of change: feature / fix / documentation
-    □ Testing: how to verify the improvement
-    □ Accessibility: any screen reader considerations
-    □ Related issue: linked to the issue I filed (if applicable)
-□ I reviewed my PR description tone against the Culture & Etiquette guide
-□ I requested a review from the repo maintainer
-

Opening the PR to community-access/accessibility-agents

-

Option A - from your browser:

-
    -
  1. Navigate to your fork on GitHub
    2. -
  2. GitHub will show a yellow banner: "Your branch is N commits ahead of community-access:main"
    3. -
  3. Activate "Contribute" → "Open a pull request"
    4. -
  4. Confirm the base repository is community-access/accessibility-agents and base branch is main
    5. -
  5. Fill in the PR template
    6. -
  6. Submit
    7. -
-

Option B - from VS Code GitHub Pull Requests extension:

-
    -
  1. Open the Source Control panel (Ctrl+Shift+G)
    2. -
  2. Navigate to "Pull Requests" in the sidebar
    3. -
  3. Activate "Create Pull Request"
    4. -
  4. Select base: community-access/accessibility-agents → main
    5. -
  5. Fill in the title and description
    6. -
  6. Submit
    7. -
-

What happens next: The maintainer (Jeff, your facilitator) reviews the PR. If it meets the contribution standards, it gets merged. Your name goes into the commit history of a live, public, accessibility-focused open source project - permanently.

-

Forge Partner Review

-

While your PR is awaiting review, review a forge partner's PR:

-
    -
  1. Use @pr-review review PR #[their PR number] to generate a starting point
    2. -
  2. Edit the output for tone and accuracy
    3. -
  3. Post your review in the browser (or via GitHub PR extension)
    4. -
  4. For each comment, ask: "Is this the kind of feedback I would want to receive?"
    5. -
-

Block 6 - Spec Kit: Design the Future

-

16:15-17:00

-
-

What is Spec-Driven Development? It is the practice of writing the intent of a feature before anyone builds it. The specification becomes the source of truth - AI uses it to plan tasks, contributors use it to stay aligned, and the community uses it to evaluate whether the feature actually delivered what was intended.

-
-

The Exercise: Specify the Next Version of Accessibility Agents

-

The facilitator opens Copilot Chat and types /specify to initiate a spec session. The group collaborates to answer:

-
    -
  • What is missing from the 55 agents that would make the ecosystem more useful for screen reader users?
    • -
  • Which of the three teams (Accessibility, GitHub Workflow, Developer Tools) has the biggest gap?
    • -
  • The roadmap lists mobile native agents and document remediation - what would you prioritize?
    • -
  • What if Accessibility Agents had a searchable web interface - what accessibility requirements would it need on day one?
    • -
-

How to participate (no typing required): -Speak your requirements aloud. The facilitator types them. Copilot helps convert them into a structured specification.

-

Accessibility requirements you might suggest:

-
    -
  • All output must have proper heading hierarchy (never skip H1→H3)
    • -
  • All links must have descriptive text, never bare URLs
    • -
  • All tables must have captions and scoped column headers
    • -
  • The web interface must work with NVDA, JAWS, and VoiceOver tested
    • -
  • Color must not be the only means of communicating status
    • -
-

The output: A spec.md file committed to accessibility-agents. A record of what the community intended. Anyone who wants to build it next week has a starting point.

-

The Spec Kit toolkit (for self-directed use after the workshop):

-
    -
  • Repo: Spec Kit repository on GitHub
    • -
  • Init command: uvx --from git+https://github.com/github/spec-kit.git specify init accessibility-agents-v2
    • -
  • Slash commands: /specify → /plan → /tasks → implement
    • -
-

Wrap-Up

-

17:00-17:30

-

The Moment: Find Your Name in History

-
    -
  1. Navigate to https://github.com/community-access/accessibility-agents
    2. -
  2. Go to the Insights tab → Contributors
    3. -
  3. Or: navigate to the commit history of the file you contributed to
    4. -
  4. Find your username in the list
    5. -
-

This is real. This is permanent. This is yours.

-

What You Are Taking Home

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ArtifactWhere It LivesWhat You Can Do With It
Your fork of accessibility-agentsgithub.com/[your-username]/accessibility-agents55 agents across 3 teams - use them on any GitHub repo, on 5 platforms
Your name in the upstream commit historygithub.com/community-access/accessibility-agentsShare it - it is a real open source contribution to an accessibility project
VS Code + Copilot setupYour machineThe development environment is configured; use it on your next contribution
The GitHub skill set from Day 1Your knowledgeNavigate any repo, file any issue, open any PR - without an agent doing it for you
Accessibility Agents as a modelYour thinkingKnow that any project can have agents in .github/agents/ - and you know how to write, improve, and contribute them
-

Personalizing Accessibility Agents After the Workshop

-

Accessibility Agents is designed to be personalized. In .github/agents/preferences.example.md:

-
    -
  1. Copy it to .github/agents/preferences.md
    2. -
  2. Add your GitHub username and the repositories you care about most
    3. -
  3. Set your preferred output format
    4. -
  4. Commit it to your fork - now your agents know who you are and what you work on
    5. -
-

This is your own instance. The agents respond to your preferences. Start with the example and make it yours.

-

The Skills That Stay

-

The most important thing you take home is not a tool. It is the ability to look at any GitHub repository - any open source project in the world - and know:

-
    -
  • How to find a good first issue
    • -
  • How to understand what the project needs
    • -
  • How to make a contribution that will be welcomed
    • -
  • How to receive feedback without losing confidence
    • -
  • How to give feedback that helps rather than discourages
    • -
-

Those skills are yours. No one can take them. Every project you ever encounter is now within reach.

-

Facilitator Notes - Day 2

-

Pre-Day Setup

-
    -
  • Clone accessibility-agents to a demo machine where the facilitator is signed into a GitHub account
    • -
  • Configure preferences.md with the facilitator's account and the demo repository
    • -
  • Pre-create one issue in the demo repo with an intentional gap for the agentic workflow to triage
    • -
  • Test all 5 agent commands the day before - especially @daily-briefing and @pr-review
    • -
  • Enable the agentic workflow on the demo repo (GitHub Agentic Workflows technical preview)
    • -
  • Have a backup: if the agentic workflow doesn't trigger in time, show the run from a pre-recorded session
    • -
-

Pacing Adjustments

-
    -
  • If Block 1 runs long (VS Code setup issues): compress Block 2 to 45 minutes, prioritize getting one commit per participant
    • -
  • If Block 3 runs short: extend with @analytics - team velocity, contribution patterns, what the agents say about the group's collective Day 1 work
    • -
  • If Block 5 produces a wave of PRs before Jeff can review: use the time to have participants review each other's PRs instead
    • -
-

The Emotional Arc

-

Day 2 has two peaks:

-
    -
  1. The first agent command (Block 3) - participants recognize the output because they know the source material
    2. -
  2. The name in history (Wrap-Up) - this should have a moment of silence and genuine acknowledgment
    3. -
-

Do not rush the wrap-up. The moment of seeing your name in a public commit history is one of the most meaningful things a first-time open source contributor experiences.

-

Previous: Notifications ← -Next: VS Code: Setup & Accessibility Basics -Related: Day 1 Agenda | GitHub Actions & Workflows | Resources

- -
- - - \ No newline at end of file diff --git a/html/FACILITATOR.html b/html/FACILITATOR.html deleted file mode 100644 index 324f2a7..0000000 --- a/html/FACILITATOR.html +++ /dev/null @@ -1,1107 +0,0 @@ - - - - - - - Facilitator Guide - GIT Going with GitHub - - - - - - - - -
-

Facilitator Guide

-

Open Source Assistive Technology Hackathon

-
-

This document is for workshop facilitators only. Participants should start with README.md and docs/00-pre-workshop-setup.md.

-
-

** If you're looking for Challenge Management (issue generation, monitoring, bot setup): See FACILITATOR_CHALLENGES.md**

-

Quick Reference Timeline

-

Skip to your current phase:

-

Phase 1: Setup (2 weeks before)

-
    -
  • Create GitHub org/repo
    • -
  • Configure repo settings (Issues, Discussions, branch protection)
    • -
  • Enable Actions with write permissions
    • -
  • Test GitHub Skills modules (Introduction to GitHub, Markdown, Review PRs)
    • -
  • Time: ~2 hours
    • -
-

Phase 2: Launch (1 week before)

-
    -
  • Create 10 labels (accessibility, bug, documentation, good first issue, etc.)
    • -
  • Create "Hackathon Day 1" milestone
    • -
  • Create 1 Welcome issue (unassigned)
    • -
  • Create pre-seeded practice PR on practice-review branch
    • -
  • Create participant issues (10 per student for Chapters 4,5,6,11; e.g., 100 issues for 10 students)
    • -
  • Update .github/data/student-roster.json with participant names/usernames
    • -
  • Create day1-practice branch (differs from main by 2-3 files)
    • -
  • Time: ~3-4 hours
    • -
-

Phase 3: Day 1 (30 min before session)

-
    -
  • Verify all participant issues created, assigned, labeled
    • -
  • Verify bot automation is working (test a PR comment)
    • -
  • Connect screen share: show learning-room repo structure
    • -
  • Time: 30 min checklist
    • -
-

Phase 4: Day 1 Session - Saturday, March 7, 2026 (7.5 hours)

-
    -
  • Block 0 (9:00-9:45): Welcome, setup verification, git clone learning-room
    • -
  • Block 1 (9:30-10:10): Screen reader orientation to GitHub
    • -
  • Block 2 (10:10-11:00): Navigating repositories & Markdown setup
    • -
  • Break (11:00-11:15)
    • -
  • Block 3 (11:15-12:10): Working with Issues & Pull Requests
    • -
  • Block 4 (12:10-1:00 PM): Pull Request review and merge
    • -
  • Lunch (1:00-2:00 PM)
    • -
  • Block 5 (2:00-3:00 PM): Contribution sprint (students work on assigned learning-room issues)
    • -
  • Break (3:00-3:15 PM)
    • -
  • Block 6 (3:15-4:30 PM): Community tools & wrap-up
    • -
-

Phase 5: Day 2 Morning (30 min before session)

-
    -
  • Verify VS Code + extensions are installed (demo machine)
    • -
  • Test Copilot Chat + Accessibility Agents
    • -
  • Test slash commands (/find-issues, /daily-briefing)
    • -
  • Check all student PRs from Day 1 (merge any ready ones)
    • -
  • Time: 30 min checklist
    • -
-

Phase 6: Day 2 Session - Sunday, March 8, 2026 (7.5 hours)

-
    -
  • Block 0 (9:00-9:30): Day 1 debrief & goal-setting
    • -
  • Block 1 (9:30-10:30): VS Code setup & screen reader mode
    • -
  • Break (10:30-10:45)
    • -
  • Block 2 (10:45-12:00): Deep contribution with Copilot Chat
    • -
  • Lunch (12:00-1:00 PM)
    • -
  • Block 3 (1:00-2:00 PM): Accessibility Agents activation
    • -
  • Block 4 (2:00-3:00 PM): Agentic workflows in action
    • -
  • Break (3:00-3:15 PM)
    • -
  • Block 5 (3:15-4:15 PM): Ship your contribution (upstream PR to accessibility-agents)
    • -
  • Block 6 (4:15-5:00 PM): Spec kit & future planning
    • -
-

Phase 7: Post-Workshop

-
    -
  • Post completion stats/badges
    • -
  • Collect feedback on automation
    • -
  • Archive student roster
    • -
  • Schedule retrospective
    • -
-

Full Details

-

(See sections below for complete instructions on each phase)

-

Repository Structure

-

This is the single repository students clone. Everything they need for both days is here:

-
learning-room/                  ← workshop repository root
-├── README.md                   ← participant-facing start page
-├── CONTRIBUTING.md             ← contribution guide
-├── CODE_OF_CONDUCT.md          ← community standards
-├── FACILITATOR.md              ← this file
-├── .gitignore
-├── .github/
-│   ├── ISSUE_TEMPLATE/
-│   │   ├── config.yml          ← disables blank issues, links to Skills modules
-│   │   ├── accessibility-bug.yml ← accessibility bug report YAML form
-│   │   └── feature-request.yml ← feature/improvement request YAML form
-│   ├── PULL_REQUEST_TEMPLATE.md ← PR template with accessibility checklist
-│   ├── agents/                 ← Accessibility Agents - 55 Copilot agents across 3 teams
-│   │   ├── daily-briefing.agent.md
-│   │   ├── issue-tracker.agent.md
-│   │   ├── pr-review.agent.md
-│   │   ├── analytics.agent.md
-│   │   ├── insiders-a11y-tracker.agent.md
-│   │   ├── template-builder.agent.md
-│   │   └── preferences.example.md
-│   └── prompts/                ← 54+ slash commands for Copilot Chat
-│       ├── a11y-update.prompt.md
-│       ├── create-issue.prompt.md
-│       ├── daily-briefing.prompt.md
-│       ├── explain-code.prompt.md
-│       ├── review-pr.prompt.md
-│       ├── triage.prompt.md
-│       └── ... (48 more - see docs/appendix-v-accessibility-agents-reference.md)
-├── docs/                       ← full workshop curriculum (17 chapters + appendices A-Z)
-│   ├── 00-pre-workshop-setup.md
-│   ├── 01-understanding-github-web-structure.md
-│   ├── 02-navigating-repositories.md
-│   ├── 03-the-learning-room.md
-│   ├── 04-working-with-issues.md
-│   ├── 05-vscode-accessibility.md
-│   ├── 06-working-with-pull-requests.md
-│   ├── 07-merge-conflicts.md
-│   ├── 08-culture-etiquette.md
-│   ├── 09-labels-milestones-projects.md
-│   ├── 10-notifications.md
-│   ├── 11-git-source-control.md
-│   ├── 12-github-pull-requests-extension.md
-│   ├── 13-github-copilot.md
-│   ├── 14-accessible-code-review.md
-│   ├── 15-issue-templates.md
-│   ├── 16-accessibility-agents.md
-│   ├── appendix-a-glossary.md              ← every term explained
-│   ├── appendix-b-screen-reader-cheatsheet.md ← full shortcut reference
-│   ├── appendix-c through appendix-x      ← deep-dive references (C-X)
-│   └── (see appendix-u-resources.md for complete file listing)
-└── learning-room/              ← practice content (contribution sprint targets)
-    ├── README.md
-    └── docs/
-        ├── welcome.md          ← has [TODO] gaps for participants to complete
-        ├── keyboard-shortcuts.md ← has intentional errors and a heading hierarchy problem
-        └── setup-guide.md      ← has a broken URL and [TODO] markers
-

Two Weeks Before the Workshop

-

Create the GitHub Organization and Repository

-
    -
  1. Create a GitHub org (recommended) or use your personal account
    2. -
  2. Create a new repository named learning-room (or your preferred name)
    3. -
  3. Make it Public - participants need read access without being org members
    4. -
  4. Push the contents of this repository to it:
    git remote add origin https://github.com/[org]/learning-room
-git push -u origin main
    -
    5. -
-

Configure the Repository

-

Enable Issues: -Settings → Features → check Issues

-

Enable Discussions (optional): -Settings → Features → check Discussions (useful for async Q&A)

-

Branch protection for main: -Settings → Branches → Add rule:

-
    -
  • Require pull request before merging:
    • -
  • Require at least 1 approving review:
    • -
  • Do not require up-to-date branches before merging (reduces friction for beginners)
    • -
-

Mark as Template Repository (recommended): -Settings → check "Template repository" -This allows you to create a fresh copy for each cohort with one click.

-

One Week Before the Workshop

-

Create Labels

-

Navigate to Issues → Labels → create these labels (delete GitHub defaults if desired):

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
LabelColorDescription
accessibility#0075caKeyboard, screen reader, WCAG
good first issue#7057ffGood for new contributors
documentation#0075caImprovements to docs
needs triage#e4e669Awaiting review by a maintainer
bug#d73a4aSomething isn't working
enhancement#a2eeefNew feature or request
help wanted#008672Extra attention needed
question#d876e3More information needed
wontfix#ffffffThis will not be addressed
duplicate#cfd3d7This issue already exists
-

Create a Milestone

-

Issues → Milestones → New milestone:

-
    -
  • Title: Hackathon Day 1
    • -
  • Due date: Day 1 date
    • -
  • Description: "Issues targeted for the Day 1 contribution sprint"
    • -
-

Pre-Seed Issues for the Contribution Sprint

-

Create one issue per participant, assigned to them. Each issue points to a specific problem in learning-room/docs/. Template:

-

Issue title: Fix: [specific problem] in [filename] -Issue body:

-
## What to Fix
-
-[Specific description of the problem - be precise enough that the participant knows exactly
-what line or section to look at.]
-
-## File to Edit
-
-`learning-room/docs/[filename].md`
-
-## Acceptance Criteria
-
-- [ ] [Specific thing that should be true when the fix is complete]
-- [ ] No new heading-level skips introduced
-- [ ] Link text is descriptive (not "click here")
-
-## How to Contribute
-
-See [Working with Issues](docs/04-working-with-issues.md) and the [Day 1 Agenda](DAY1_AGENDA.md) for the full contribution workflow.
-

Pre-seeded issues to create (by file):

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FileProblem to fixLabel
keyboard-shortcuts.mdHeading jumps from # (h1) to #### (h4) for NVDA section sub-headings - should be ## and ###accessibility, good first issue
keyboard-shortcuts.mdThe Accessibility Settings link is broken: htps:// has a typobug, good first issue
setup-guide.mdStep 2 link has a typo: htps://github.com/settings/accessibility - missing one tbug, good first issue
setup-guide.md"Note: Links marked [TODO]" callout at the bottom - replace with actual links to the workshop repodocumentation, good first issue
welcome.mdLast reviewed: [DATE] placeholder at the bottom - replace with today's date (format: YYYY-MM-DD)documentation, good first issue
welcome.md[TODO] paragraph about who can contribute (line 22)documentation, good first issue
welcome.md[TODO] paragraph about reading an issue to decide if it's right for you (line 40)documentation, good first issue
welcome.md[TODO] sentence about what a merged PR means for GitHub profile (line 52)documentation, good first issue
-

Create extras for any additional participants.

-

Create the Welcome Issue

-

Create this issue, unassigned, labeled good first issue:

-

Title: Welcome! Introduce yourself -Body:

-
Welcome to the workshop repository! This issue is for introductions.
-
-## How to participate
-
-Leave a comment on this issue introducing yourself:
-
-- Your name (first name or preferred name)
-- Your screen reader and operating system
-- One thing you are hoping to learn or do during this workshop
-
-Use Markdown in your comment:
-- Use `**bold**` to highlight your screen reader name
-- Use a task list (`- [ ]`) for things you want to accomplish
-
-There is no wrong answer. This is practice, and it is also a real community.
-

Create the Pre-Seeded PR

-

Create a PR from a practice-review branch with a meaningful change to learning-room/docs/welcome.md - add one paragraph, change one heading, correct one small issue. This PR exists so participants can practice reviewing in Block 4 before the contribution sprint.

-

PR title: Expand the "What Is Open Source?" section -Description: Use the PR template. Fill in all fields.

-

Day 1 - Pre-Session Checklist

-

Run through this 30 minutes before participants arrive:

-
    -
  • All participant issues created, assigned, and labeled
    • -
  • Welcome issue open and unlabeled
    • -
  • Pre-seeded practice PR open on practice-review branch
    • -
  • learning-room milestone created and linked to all participant issues
    • -
  • All labels created
    • -
  • day1-practice branch created (differs from main by 2-3 files - for Branch Navigation exercise in Block 2)
    • -
  • Repository is public and accessible without login
    • -
  • GitHub Skills modules tested (go through the first 2 steps of each to verify Mona responds)
    • -
-

GitHub Skills Pre-Test (Important)

-

Test each module at least 3 days before the workshop:

-
    -
  1. Introduction to GitHub - complete Steps 1-3 in a test account
    2. -
  2. Communicate Using Markdown - start and verify Mona creates the first issue
    3. -
  3. Review Pull Requests - start and verify Mona creates the practice PR
    4. -
-

Note: GitHub Skills modules occasionally have delayed Mona responses. If Mona does not respond within 2 minutes:

-
    -
  1. Check that the repo was created as Public (Mona requires this on the free tier)
    2. -
  2. Navigate to the Actions tab of the student's new repo - confirm a workflow run is listed
    3. -
  3. If the workflow failed: click it → read the error → the most common cause is a rate limit (wait 1-2 minutes and re-trigger by creating another commit)
    4. -
  4. Have backup screenshots of Mona's expected responses ready for demo purposes
    5. -
-

Day 2 - Pre-Session Checklist

-
    -
  • VS Code installed on any shared/demo machine
    • -
  • GitHub Copilot Chat extension installed and authenticated
    • -
  • GitHub Pull Requests extension installed
    • -
  • Accessibility Agents agents verified: open Copilot Chat → type @daily-briefing morning briefing → confirm a response
    • -
  • Slash commands verified: type /find-issues good first issue → confirm a response
    • -
  • Each participant's upstream PR target ready (if doing the accessibility-agents contribution)
    • -
-

GitHub Skills - Facilitator Script

-

Block 1: Introducing Introduction to GitHub

-
-

"Before we explore the learning-room repo, I want you to do something first. We're going to navigate to a GitHub Skills module - this is an interactive learning course built into GitHub itself. When you activate it, GitHub creates a copy of the course repository in your own account. Then a bot called Mona starts guiding you through steps - and it responds to real GitHub actions that you take."

-
-

Walk through the setup together. Wait until everyone sees Mona's Issue #1 before continuing.

-
-

"Look at your repositories list. You now own a repository on GitHub. Mona is waiting inside it. Keep that tab open - we'll come back to it throughout the day."

-
-

Block 3: Mona Responds to the PR

-

When participants create their PR and Mona responds:

-
-

"Pause what you're doing. Navigate to your Pull Request tab in your Skills repo. What does Mona say? Read it with your screen reader."

-
-

Wait a moment.

-
-

"What just happened is exactly how real open source bots work. Dependabot, GitHub Actions CI, automated labelers - they all watch for GitHub events and respond automatically. You just experienced that for the first time on your own repository."

-
-

Wrap-Up: Completion Certificates

-

When checking Skills module completions:

-
-

"Navigate to github.com/skills/introduction-to-github. Do you see your completion badge? That's yours. It's tied to your GitHub profile. It will be there when you apply for jobs, when you introduce yourself to a new open source community, when you want to demonstrate that you know how to use GitHub."

-
-

Managing Learning Room Automation

-

The Learning Room includes comprehensive automation that provides instant feedback while preserving the educational value of human peer review.

-

Automation Components

-

1. PR Validation Bot (.github/workflows/learning-room-pr-bot.yml)

-
    -
  • Welcomes first-time contributors
    • -
  • Validates PRs against quality standards
    • -
  • Checks accessibility (headings, links, alt text, broken links)
    • -
  • Provides educational feedback with links to resources
    • -
  • Auto-applies labels (first-time-contributor, documentation, needs-work, accessibility)
    • -
  • Responds to keywords: @bot help, "merge conflict", "request review"
    • -
-

2. Skills Progression Engine (.github/workflows/skills-progression.yml)

-
    -
  • Tracks student progress through skill levels (Beginner → Intermediate → Advanced → Expert)
    • -
  • Awards badges for specific achievements (Markdown Master, Accessibility Advocate, etc.)
    • -
  • Unlocks new challenges based on merged PR count
    • -
  • Celebrates milestones (1st, 5th, 10th, 25th merged PRs)
    • -
  • Posts progress updates with stats
    • -
-

3. Student Pairing & Grouping (.github/workflows/student-grouping.yml)

-
    -
  • Automatically assigns peer reviewers to PRs
    • -
  • Balances review load using "least_reviews" strategy
    • -
  • Creates study groups when triggered manually
    • -
  • Provides review guidance to both author and reviewer
    • -
-

Before the Workshop: Configure Automation

-

Update Student Roster (.github/data/student-roster.json)

-
{
-  "cohort": "Your Cohort Name 2024",
-  "facilitators": ["your-github-username"],
-  "students": [
-    {
-      "username": "student-github-username",
-      "name": "Student Display Name",
-      "timezone": "America/Los_Angeles",
-      "interests": ["accessibility", "frontend"],
-      "pronouns": "they/them",
-      "screenReader": false,
-      "mergedPRs": 0,
-      "currentLevel": "Beginner",
-      "badges": [],
-      "joinedDate": "2024-01-15"
-    }
-  ]
-}
-

Verify Workflows Are Enabled

-
    -
  • Navigate to Actions tab
    • -
  • Ensure workflows are enabled (not disabled by GitHub)
    • -
  • Check that GitHub Actions has write permissions:
      -
    • Settings → Actions → General → Workflow permissions
      • -
    • Select "Read and write permissions"
      • -
    • Check "Allow GitHub Actions to create and approve pull requests"
      • -
    -
    • -
-

Test Automation

-
    -
  1. Open a test PR before workshop
    2. -
  2. Verify bot comments within ~30 seconds
    3. -
  3. Check that labels are applied
    4. -
  4. Verify validation results are accurate
    5. -
  5. Test @bot help keyword response
    6. -
-

During the Workshop: Interacting with Automation

-

Introducing the Bot (Day 1, Block 5)

-
-

"When you open your PR, you'll see a comment from a bot within about 30 seconds. This bot is not grading you - it's teaching you. Read its feedback carefully. It will tell you about accessibility issues, link you to resources, and celebrate things you did well."

-
-

Walk through a sample bot comment:

-
    -
  • Required checks (must pass)
    • -
  • Suggestions (optional improvements)
    • -
  • Accessibility analysis (detailed feedback with fixes)
    • -
  • Learning resources (relevant documentation links)
    • -
-
-

"The bot is consistent and instant, but it's not perfect. If you disagree with its feedback, comment on your PR explaining why. Always request human review - peer review teaches things the bot cannot."

-
-

Monitoring Bot Behavior

-

Watch for:

-
    -
  • Bot comments that are incorrect (file issues with label automation-feedback)
    • -
  • Bot overwhelming participants (adjust timing if needed)
    • -
  • Students relying solely on bot without requesting reviews (remind them of human review value)
    • -
-

Overriding Bot Checks

-

If bot incorrectly flags something:

-
    -
  1. Facilitator comments: "Bot feedback incorrect here - [explanation]"
    2. -
  2. Approve PR despite bot warning
    3. -
  3. File issue to improve validation script later
    4. -
-

Manual Skill Progression Adjustments

-

If a student completes work outside tracked PRs:

-
    -
  1. Update their entry in .github/data/student-roster.json
    2. -
  2. Increment mergedPRs count
    3. -
  3. Update currentLevel if appropriate
    4. -
  4. Add badges to badges array
    5. -
  5. Commit and push to apply
    6. -
-

Creating Study Groups

-

Manual Creation: -Run the student-grouping workflow manually:

-
    -
  1. Navigate to Actions tab
    2. -
  2. Select "Student Pairing & Grouping"
    3. -
  3. Click "Run workflow"
    4. -
  4. Choose pairing strategy:
      -
    • random: Shuffle and divide
      • -
    • skill_match: Mix skill levels (recommended)
      • -
    • timezone_match: Group by timezone
      • -
    -
    5. -
  5. Bot creates issue thread for each group
    6. -
-

Group Sizes:

-
    -
  • 2-3 students: Ideal for focused collaboration
    • -
  • 4-5 students: Good for larger cohorts
    • -
  • Edit groupSize variable in workflow to adjust
    • -
-

Monitoring Groups:

-
    -
  • Check group issue threads for activity
    • -
  • Ensure all members are participating
    • -
  • Intervene if one person dominates or is left out
    • -
-

Automation Philosophy

-

Automation Provides:

-
    -
  • Instant feedback (students don't wait)
    • -
  • Educational resources (links to learning materials)
    • -
  • Consistency (same standards for everyone)
    • -
  • Unlimited patience (can run on every commit)
    • -
-

Human Review Provides:

-
    -
  • Creative suggestions (beyond rule-checking)
    • -
  • Contextual judgment (understanding nuance)
    • -
  • Social learning (building relationships)
    • -
  • Encouragement (celebrating growth)
    • -
-

The Goal: Automation handles technical checks so humans can focus on higher-level feedback, mentorship, and community building.

-

Troubleshooting Automation

-

Bot not commenting:

-
    -
  • Check Actions tab for workflow runs
    • -
  • Verify workflow triggered (visible in Actions)
    • -
  • Check workflow permissions (Settings → Actions)
    • -
  • Review workflow logs for errors
    • -
-

Incorrect validation results:

-
    -
  • Review .github/scripts/validate-pr.js logic
    • -
  • Check if file paths match expectations
    • -
  • Test validation script locally: node .github/scripts/validate-pr.js
    • -
  • File issue with details for post-workshop fixes
    • -
-

Bot commenting multiple times:

-
    -
  • Should only update one comment per PR
    • -
  • If creating multiple: check workflow logic in find-comment step
    • -
  • May be multiple workflows triggering (check Actions tab)
    • -
-

Skills not unlocking:

-
    -
  • Verify PR was merged (not just closed)
    • -
  • Check that issue was linked with "Closes #XX"
    • -
  • Review skills-progression.yml workflow logs
    • -
  • Manually update student-roster.json if needed
    • -
-

Peer reviewers not assigned:

-
    -
  • Check that student-roster.json has active students
    • -
  • Verify pairing workflow triggered
    • -
  • Review logs for errors
    • -
  • Manually request reviewers as fallback
    • -
-

Customizing Automation

-

Adjusting Validation Rules: -Edit .github/scripts/validate-pr.js:

-
    -
  • Modify checkDescription() to change min character count
    • -
  • Add new validation functions
    • -
  • Adjust accessibility checks (heading hierarchy, link text patterns)
    • -
  • Update messages and resources
    • -
-

Changing Skill Progression: -Edit .github/data/challenge-progression.json:

-
    -
  • Adjust required PR counts per level
    • -
  • Add new skill levels
    • -
  • Create new badge types
    • -
  • Change challenge lists
    • -
-

Adding New Challenges:

-
    -
  1. Create issue template in .github/ISSUE_TEMPLATE/
    2. -
  2. Add to learning-room/docs/CHALLENGES.md
    3. -
  3. Document in .github/docs/LEARNING_PATHS.md
    4. -
  4. Add to progression data
    5. -
-

Post-Workshop: Reviewing Automation Impact

-

After the workshop, analyze:

-
    -
  • Did bot feedback help students improve faster?
    • -
  • Were validation messages clear and educational?
    • -
  • Did automation reduce facilitator burden?
    • -
  • Was peer review still valued despite automation?
    • -
  • What false positives/negatives occurred?
    • -
  • Did skills progression motivate continued participation?
    • -
-

Collect Feedback: -Create issue labeled automation-retrospective asking:

-
    -
  • What bot feedback was most helpful?
    • -
  • What feedback was confusing?
    • -
  • Did automation enhance or detract from learning?
    • -
  • Would you want more or less automation?
    • -
-

Iterate: -Use feedback to improve validation scripts, messages, and workflows for next cohort.

-

Accessibility Notes for Facilitators

-
    -
  • Deliver all verbal instructions slowly - participants are simultaneously navigating and listening
    • -
  • When demonstrating on screen, describe what you are doing out loud: "I am pressing Tab three times to reach the Issues tab, then pressing Enter"
    • -
  • Pause after introducing each new concept before moving to the next
    • -
  • When a participant is stuck: ask "what does your screen reader say right now?" before any other question - this locates them precisely
    • -
  • Respect different reading speeds. Some participants' screen readers read faster, some slower. Build buffer time into each activity.
    • -
  • If the room has mixed screen reader experience: pair advanced and new users during the contribution sprint - code review is a natural collaboration opportunity
    • -
  • Bot accessibility: Automation comments are standard GitHub comments, fully accessible with screen readers. Bot uses clear headings, lists, and links for easy navigation.
    • -
-

Personalizing This Workshop

-

The curriculum, agent files, and practice documents are designed to be adapted:

-
    -
  • Rename learning-room to reflect your project or organization
    • -
  • Replace the practice issues with real issues from an AT project you support
    • -
  • Edit the agent files in .github/agents/ to be project-specific
    • -
  • Add more slash commands by creating new .prompt.md files in .github/prompts/
    • -
  • Add more practice docs to learning-room/docs/ with intentional issues relevant to your project's actual documentation
    • -
-

The workshop is licensed under Creative Commons Attribution. Attribution: "Based on the Open Source AT Hackathon Learning Room by [your name]."

-

Chapter-by-Chapter Facilitation Guide

-

Chapters 0-2: Pre-Workshop & Orientation (Day 1 Blocks 0-1)

-

Chapter 0: Pre-Workshop Setup

-
    -
  • Facilitator role: Verify everyone completed this before arriving
    • -
  • Common issues:
      -
    • Screen reader not announcing page headings (turn off hovercards)
      • -
    • GitHub modern experience disabled (enable in Feature Options)
      • -
    • Accessibility settings not found (keyboard shortcut: G then D then A)
      • -
    -
    • -
  • What to watch for: Participants may not realize page titles are headings - emphasize pressing 1 to find them
    • -
  • Talking point: "The first heading on every GitHub page tells you where you are. It's your anchor point."
    • -
-

Chapter 1: Understanding GitHub's Web Structure

-
    -
  • Purpose: Mental model - three levels of organization + landmark structure
    • -
  • Key concept demo: Have everyone press D to navigate landmarks on the learning-room repo page; call out "Navigation Menu," "Repository Navigation," "Main," "Search Results"
    • -
  • Common confusion: The difference between repository navigation (Code, Issues, PRs tabs) and global navigation (top bar)
    • -
  • Accessibility teaching point: "Landmarks are not visual features - they are semantic markers your screen reader uses to let you jump around instead of reading every line"
    • -
  • Demo script:
    "I'm opening github.com/community-access/learning-room
- I press 1, twice - what do I hear? [let people answer]
- Yes, the first heading is the page title. The second is a section heading.
- Now I press D - I move through landmarks.
- I hear Navigation Menu - that's the top bar.
- I move forward with D again - Repository Navigation - that's where Code, Issues, PRs live.
- Now I press D again - Main - that's the content area where the file list is.
- If I press D one more time - it might say Search Results landmark, but there's nothing there right now.
- These landmarks are the skeleton of every GitHub page."
    -
    • -
-

Chapter 2: Navigating Repositories

-
    -
  • Purpose: Concrete navigation patterns using single-key shortcuts
    • -
  • Key practice: Have everyone navigate the learning-room repo using H to browse headings, then T to find tables, then open docs/welcome.md
    • -
  • Common struggle: Memorizing which key does what - reassure them that pressing H-H-H is faster than searching visually
    • -
  • Demo the Elements List: NVDA+F7 / Insert+F3 / VO+U - show everyone that the list view of headings, links, and buttons exists
    • -
  • Accessibility insight: "The Elements List is a speed tool. When you know what you're looking for, listing all links or buttons gets you there faster than pressing K fifteen times."
    • -
  • Demo script:
    "Let's open the learning-room README together.
- We're looking for the section that explains what files to work on.
- I could press H to go heading-by-heading. That's fine.
- But I could also press NVDA+F7 to open the Elements List, jump to Headings tab, and see all of them at once.
- I can see [describes list] - let me jump to 'The Practice Files' heading.
- Much faster than stepping through."
    -
    • -
-

Chapter 3: The Learning Room (Day 1 Block 1-5)

-

Key before starting: Everyone must read this chapter before Day 1 begins. It explains the environment, PR workflow, bot feedback, and peer review model.

-
    -
  • Facilitator role: Reinforce the fork-edit-PR workflow
    • -
  • What not to do: Don't let participants edit the learning-room repo directly. They must fork first.
    • -
  • Automation introduction: Explain that the bot comments are not grading - they are teaching
    • -
  • Common errors: Editing main instead of creating a branch; committing directly instead of PRing; not requesting a human review
    • -
  • Demo the bot feedback:
    "When you open your PR, within 30 seconds you'll see a comment from a bot.
- The bot is checking: does your heading hierarchy go H1, H2, H3 (not skipping)?
- Are your links descriptive (not 'click here')?
- Did you spell everything correctly?
- It will link you to resources explaining the rules.
- But here's the important part: the bot is not rejecting your PR.
- It's teaching. You can learn from the bot feedback and still ask your reviewers for human judgment."
    -
    • -
-

Chapters 4-6: Issues, VS Code Accessibility & Pull Requests (Day 1 Blocks 2-4)

-

Chapter 4: Working with Issues

-
    -
  • Purpose: Understanding issue lifecycle, templates, labeling
    • -
  • Live demo: Open an issue in the learning-room repo, show the anatomy - title, description, labels, assignee, milestone, comments
    • -
  • Interactive activity: Have participants navigate an issue end-to-end with their screen reader
      -
    • Find the issue title (should be first heading)
      • -
    • Navigate to the description with H or by scrolling
      • -
    • Find the labels (usually below description)
      • -
    • See the comments section
      • -
    -
    • -
  • Accessibility teaching point: "An issue is a conversation. Each comment is timestamped. Your screen reader can navigate them with D to find the 'Comments' section, then use arrow keys through the list."
    • -
  • Demo script for issue anatomy:
    "I'm opening issue #1 in the learning-room repo.
- My screen reader announces it: heading level 1, 'Welcome! Introduce yourself'.
- That's the issue title. Below it is the issue body - the full description.
- If I press H, I move to the next heading. There shouldn't be one - just the comments below.
- If I press D, I move through landmarks until I find the Comments section.
- Then I can use arrow keys to navigate each comment one by one.
- The bot comment, the first person's introduction, the second person's - they're all visible
- because they're in the same accessibility tree."
    -
    • -
-

Chapter 6: Working with Pull Requests

-
    -
  • Purpose: Understanding PR anatomy, creating a PR, reviewing, merging
    • -
  • Emphasize: A PR is a proposal. It asks, "Can you merge these commits to main?" It is not automatic.
    • -
  • Interactive activity: Have everyone read the sample PR (pre-seeded on practice-review branch) with their screen reader
    • -
  • Common confusion: Difference between suggesting changes (non-blocking) versus requesting changes (blocking)
    • -
  • Accessibility insight: "A PR conversation is denser than issues because diffs are involved. Your screen reader will announce code blocks as such. You may find it easier to read diffs by requesting changes (which shows the side-by-side) than by trying to parse the raw diff."
    • -
  • Demo the diff navigation:
    "Opens a PR with a change to a markdown file
- The diff section uses <pre> tags - screen readers announce them as code blocks.
- Instead of reading the raw diff, I can press R to request changes.
- That opens a suggestion editor where I can see the old and new side-by-side.
- Much more readable."
    -
    • -
-

Chapter 7: Merge Conflicts (Reference; covered in-context)

-

When it matters: Usually NOT during the workshop, but valuable for future contribution

-
    -
  • Facilitator talking point: "Merge conflicts happen when two people edit the same line. GitHub shows you both changes and asks you to pick. You will probably not see this in the workshop - we'll stagger everyone working on different files."
    • -
  • If conflict occurs: Don't panic. Open the file. You'll see markers like <<<<<< and ====== and >>>>>>. They show the conflicting sections. You delete one, keep the other.
    • -
  • Common error: Thinking a merge conflict is a failure. It's not - it's normal in large projects.
    • -
-

Chapter 8: Culture & Etiquette (Day 1 Block 6)

-

Purpose: Building inclusive communities, understanding norms

-
    -
  • Facilitator role: Model the behavior described
    • -
  • Accessibility-specific point: "In this project, we document accessibility decisions because our contributors include people with disabilities. That's not a burden - it's a feature. It's how we ensure no one is left out."
    • -
  • Common misunderstanding: "I don't want to break the build." Reassure participants that CI failures are learning moments, not disasters.
    • -
  • Demo: Show a PR with a helpful, kind review comment versus a curt one. Discuss the difference.
    • -
-

Chapters 9-10: Tracking & Notifications (Day 1 Block 6)

-

Chapter 9: Labels, Milestones, Projects

-
    -
  • In practice: Students won't be creating labels, but they will see them and need to understand what they mean
    • -
  • Facilitator tip: "Before Block 5, create a quick reference list of your labels and what they mean. Pin it to a document. Students can refer to it."
    • -
  • Interactive activity: Show the learning-room repo's label bar. Have everyone navigate labels on an issue: press K to move through links until they find a label link, press Enter, they see all issues with that label
    • -
-

Chapter 10: Notifications

-
    -
  • Value: "Notifications let you stay aware without being overwhelmed. You control what creates a notification - starring, watching, participating in a conversation."
    • -
  • Accessibility point: "Your notification inbox is more reliable than email forwarding. GitHub's inbox is fully accessible."
    • -
  • Demo: Open the notification bell. Navigate to the inbox. Show how to navigate notification history.
    • -
-

Chapters 5 and 11-16: Day 2 Deep Dives (Day 2 Blocks 1-5)

-

Chapter 5: VS Code Accessibility

-
    -
  • Before starting: Everyone should have VS Code installed and VS Code Insiders Extension Pack installed
    • -
  • Screen reader mode: This is critical. Demo it - Shift+Alt+F1 to toggle
    • -
  • Navigation shortcuts:
      -
    • Ctrl+P - quick file open
      • -
    • Ctrl+Shift+P - command palette
      • -
    • Ctrl+Shift+E - explorer/file tree
      • -
    • Ctrl+G - go to line
      • -
    -
    • -
  • Common struggle: "Why is the code so hard to read?" Answer: "You're not meant to read it top-to-bottom. You navigate by symbols, jumps, search. VS Code accessibility mode makes that workflow clear."
    • -
  • Demo script:
    "Opens VS Code with a project
- I press Ctrl+P - Quick Open appears.
- I type the filename I want - say, 'daily-briefing'
- I get instant matches. Press Enter - file opens.
- Now I press Ctrl+Shift+P - Command Palette.
- I'm looking for a command - maybe 'Go to Definition'
- I type it, press Enter, VS Code jumps me to where that function is defined.
- This is how sighted devs navigate with a mouse - using 'Go', 'Find', 'Definition'.
- Screen reader mode + keyboard makes that pattern native."
    -
    • -
-

Chapter 11: Git & Source Control

-
    -
  • Prerequisites: Git installed locally. VS Code's Source Control panel visible.
    • -
  • Workflow recap:
      -
    1. Create a branch (VS Code UI or terminal git checkout -b)
      2. -
    2. Make edits (edit files)
      3. -
    3. Commit (Source Control panel → message → commit)
      4. -
    4. Push (Terminal: git push origin branch-name)
      5. -
    5. Open PR (GitHub web)
      6. -
    -
    • -
  • Common error: Forgetting to push. Changes exist locally but not on GitHub until pushed.
    • -
  • Demo:
    "I've made changes to a file in VS Code.
- I open the Source Control panel - Ctrl+Shift+G
- It shows me which files changed.
- I type a commit message: 'Add documentation for markdown syntax'
- I press Ctrl+Enter to commit.
- Now I'm ready to push.
- But wait - I need a branch first. Let me create one.
- Terminal: git checkout -b fix-docs
- Now I commit to that branch.
- Now I push: git push origin fix-docs
- GitHub sees that push and offers me a button to create a PR from that branch.
- Click it, and I'm in familiar territory - the PR form."
    -
    • -
-

Chapter 12: GitHub Pull Requests Extension

-
    -
  • Value: "This extension brings GitHub into VS Code. No context switching."
    • -
  • Demo: Open the PR panel (click icon in left sidebar). Show how to see all assigned PRs, review right from VS Code.
    • -
  • Advantage for screen reader users: "You can navigate a PR's diff, comments, and details without leaving VS Code. The context is continuous."
    • -
-

Chapter 13: GitHub Copilot (Introduce carefully)

-
    -
  • Important caveat: "Copilot is a tool, not a replacement for thinking. It makes suggestions based on training data. You evaluate them."
    • -
  • Accessibility note: "Copilot inline suggestions appear in the editor. Screen reader users may need to toggle suggestions on/off depending on focus preference. Demo: Ctrl+Alt+\ to toggle."
    • -
  • Use case: "Copilot is great for boilerplate, docstrings, and repetitive patterns. It is not great for novel or domain-specific logic."
    • -
  • Demo:
    "I'm writing a Python function to validate GitHub URLs.
- I type: def validate_github_url(url):
- I press Ctrl+/ wait a moment
- Copilot suggests some code.
- I can press Tab to accept, Escape to reject, or keep typing to override.
- I choose to accept, then I modify it for my specific needs.
- Copilot handled the boilerplate."
    -
    • -
-

Chapter 14: Accessible Code Review

-
    -
  • Purpose: Teaching the review perspective, not just the author's
    • -
  • Key concept: "Good code review feedback is specific, kind, and teaches. It's not gatekeeping."
    • -
  • Interactive activity: Have participants read a sample PR and draft review comments together
    • -
  • Accessibility focus: "When reviewing, check heading hierarchy, link text, alt text, color contrast. These are code quality issues, not afterthoughts."
    • -
-

Chapter 15: Issue Templates (Usually pre-configured; reference only)

-
    -
  • What's happening: Your repo's issue template is guiding participants' reports
    • -
  • If customizing: Make sure template is accessible - test with screen reader before using
    • -
  • Demo: Create a sample issue using the template to show participants what structure they should follow
    • -
-

Chapter 16: Accessibility Agents

-
    -
  • This is the capstone. Participants use the tools from all previous chapters to understand and improve a real open source project.
    • -
  • Facilitator role: Enable not prescribe. Answer questions, don't drive choices.
    • -
  • Common pattern: "I found a bug in the agent tool. Can I fix it?" YES! That's a real contribution. Show them how to file an issue, fork, clone, edit, and PR.
    • -
-

Accessibility Testing Checklist for Facilitators

-

Before Day 1 and Day 2 start, verify the following on your demo machine AND participant machines:

-

Screen Reader Setup (NVDA)

-
    -
  • NVDA installed, latest stable version
    • -
  • Browse Mode / Focus Mode switching works (NVDA+Space)
    • -
  • Single-key navigation active: H (headings), D (landmarks), K (links), T (tables)
    • -
  • Elements List opens (Insert+F3)
    • -
  • GitHub.com announces page headings correctly
    • -
  • GitHub issue/PR pages announce title, description, comments in order
    • -
  • Markdown tables are readable (table mode navigates rows/cols with arrows)
    • -
  • Code blocks announce as code
    • -
  • Buttons and form fields navigate with B and F
    • -
-

Screen Reader Setup (JAWS)

-
    -
  • JAWS installed, latest version
    • -
  • Browse Mode / Forms Mode toggling works
    • -
  • Virtual cursor navigation works
    • -
  • Virtual PC cursor works for mousing interactions
    • -
  • Table reading mode navigates correctly
    • -
  • Headings landmark navigation works
    • -
-

Screen Reader Setup (VoiceOver - macOS)

-
    -
  • VoiceOver enabled (Cmd+F5)
    • -
  • Web rotor works (VO+U)
    • -
  • Rotor shows headings, form fields, links in order
    • -
  • Keyboard navigation works (VO+Right Arrow through elements)
    • -
-

Browser Configuration

-
    -
  • Hovercards are OFF (GitHub Settings → Accessibility → Turn off hovercards)
    • -
  • GitHub modern experience is ON if using Issues/Projects (Feature preview)
    • -
  • JavaScript is enabled (required for GitHub)
    • -
  • Dark mode or light mode is stable (no flashing or flickering when toggling)
    • -
-

VS Code (for Day 2)

-
    -
  • VS Code installed (latest stable)
    • -
  • Screen reader mode enabled (Shift+Alt+F1 or Settings)
    • -
  • Accessibility support setting is on
    • -
  • Single-key file navigation works (Ctrl+P)
    • -
  • Command palette works (Ctrl+Shift+P)
    • -
  • Terminal opens and is readable (Ctrl+Backtick)
    • -
  • Source control panel visible (Ctrl+Shift+G)
    • -
  • Markdown preview renders tables accessibly
    • -
  • Extensions are readable in the sidebar
    • -
-

Exercise Verification

-
    -
  • Learning-room repo is public and accessible without login
    • -
  • Issues tab shows the practice issues clearly
    • -
  • Pull requests tab shows the practice PR
    • -
  • Markdown files in learning-room/docs/ render without errors
    • -
  • No broken links in practice files (if they're supposed to be broken for the exercise, verify they display clearly as broken)
    • -
-

Facilitator Q&A Guide

-

"I pressed H and nothing happens"

-

Problem: Single-key navigation is disabled or broken.
Solution:

-
    -
  1. Are you in Browse Mode? (NVDA: press NVDA+Space)
    2. -
  2. Is the page a GitHub page, or a different website where H might be reserved?
    3. -
  3. Try pressing H again while holding Shift in case it's a mode issue.
    4. -
  4. Refresh the page (Ctrl+R or Cmd+R).
    Escalation: If still broken, it may be a NVDA/screen reader version issue - consider restarting the screen reader.
    5. -
-

"I can't find the Issues tab"

-

Problem: Repository navigation is not visible/not announced.
Solution:

-
    -
  1. Press H to go to the next heading. If you hear "Code," "Issues," "Pull Requests," you're in the repo navigation.
    2. -
  2. If not, press D to jump to the Repository Navigation landmark.
    3. -
  3. Once you hear any of those tabs, press K to navigate the links within it.
    Teaching point: "The tabs are links, not buttons. Press Enter, not Space."
    4. -
-

"The table is hard to read"

-

Problem: Markdown tables are rendering but the screen reader isn't navigating them well.
Solution:

-
    -
  1. Are you in table mode? (NVDA: when in a table, you can press NVDA+Alt+T to toggle table mode)
    2. -
  2. In table mode, arrow keys navigate cells, Ctrl+Home jumps to the first cell.
    3. -
  3. If still hard: read the table headers first (usually first row or first column), then navigate row by row.
    Accessibility note: Markdown tables have limitations - HTML tables are more accessible, but Markdown is what we have here.
    4. -
-

"I filed an issue but the bot didn't respond"

-

Problem: Bot has not commented after 5 minutes.
Solution:

-
    -
  1. Verify the repository is PUBLIC (bots require this on free tier).
    2. -
  2. Navigate to the Actions tab in that repository. You should see a workflow run. Has it completed?
    3. -
  3. If the run failed, click it to see logs. Most common error: GitHub Actions didn't have permission to comment (Settings → Actions → Permissions).
    4. -
  4. If the run is still pending, wait up to 2 minutes more.
    5. -
  5. If 5+ minutes and no action: refresh the page. Sometimes the UI doesn't update.
    Escalation: Manually verify the issue was created (it should be in the Issues tab).
    6. -
-

"I can't commit because 'nothing to commit'"

-

Problem: A student tries to commit but the VS Code terminal says "nothing to commit."
Solution:

-
    -
  1. Did you actually edit a file? Open the file and make sure your changes are there.
    2. -
  2. Did you save the file? (Ctrl+S)
    3. -
  3. Does the Source Control panel show the file as changed? (Ctrl+Shift+G)
    4. -
  4. If you see the file in the Source Control panel but it won't show as changed: the file may not be part of your workspace. Make sure you're working in the right folder.
    Teaching point: Git only tracks changes to files it already knows about. If you create a new file, it will show in Source Control as "Untracked" - you must add it first (click the + next to the filename).
    5. -
-

"I don't understand the diff"

-

Problem: The GitHub diff view is hard to parse on a screen reader.
Solution:

-
    -
  1. If reading a diff on GitHub's web, try requesting changes (R key) to get a suggestion view (side-by-side or inline).
    2. -
  2. If reading in VS Code, the diff viewer is more accessible than GitHub's web diff.
    3. -
  3. Alternative: just read the file as it is now. The diff is additive context - not always necessary to review.
    Accessibility teaching point: "Code reviews aren't always about reading diffs. They're about understanding intent. Ask the author: What changed and why? That conversation might matter more than parsing the diff syntax."
    4. -
-

"I keep getting permission denied when pushing"

-

Problem: Git push fails with "Permission denied" or "Authentication failed."
Solution:

-
    -
  1. Are you authenticated to GitHub? (gh auth status)
    2. -
  2. If not authenticated: gh auth login → follow prompts.
    3. -
  3. If authenticated but still failing: Is the branch name spelled right? (git branch to see your current branch)
    4. -
  4. Is the remote correct? (git remote -v to verify origin points to your fork)
    5. -
  5. Have you pushed this branch before, or is it new? (First push requires git push -u origin branch-name)
    Common beginner error: Trying to push to the upstream repo instead of their fork. Push to your fork first, then open a PR upstream.
    6. -
-

"The agent command didn't work"

-

Problem: User typed @accessibility-lead write a test and got no response.
Solution:

-
    -
  1. Are you in Copilot Chat? (Icon in the left sidebar, or Ctrl+Alt+I)
    2. -
  2. Did you include the @agent-name? Some agents are invoked with @ symbol, some with /slash commands.
    3. -
  3. Did Copilot Chat load correctly? Try closing the panel and reopening.
    4. -
  4. Is the agent installed in your .github/agents/ folder? (Verify by navigating to .github/ and checking the file list)
    5. -
  5. If you're offline, agents won't work (they're running in the cloud).
    Escalation: Check Copilot Chat logs (bottom of chat panel) for error messages.
    6. -
-

"I don't know what commit message to write"

-

Problem: Student is staring at the commit message prompt, uncertain what to say.
Talking point / suggestion:

-
"A good commit message is:
-- First line: one sentence, present tense, no more than 50 characters
-- Example: 'Add keyboard shortcuts for JAWS'
-- Second line: blank line
-- Rest (optional): details explaining why (not what - git diff shows what)
-- Example: 'JAWS users requested this feature in issue #42'"
-

Demo:

-
git commit -m "Add keyboard shortcuts for JAWS
-
-This resolves #42. JAWS users noted the shortcuts were missing from the docs."
-

"What if I make a breaking change?"

-

Problem: Participant is worried their edit might break something.
Reassurance:

-
    -
  1. "You're editing documentation or adding features. Documentation changes don't break anything - they clarify. Feature additions go in a PR where others review first."
    2. -
  2. "If you do break something, that's how we learn. We'll see it in CI (if we have tests) or in code review. You revert it, we move on."
    3. -
  3. "The main branch is protected. You can't accidentally push breaking changes directly - you must PR first, be reviewed, then merge."
    4. -
-

"How do I know if my PR is good enough?"

-

Problem: Participant is uncertain whether their work meets the standard.
Process to explain:

-
    -
  1. Submit your PR (you've already done the hard part).
    2. -
  2. Wait for bot feedback. Does it pass checks?
    3. -
  3. Request human review (ask @ people in the comments).
    4. -
  4. Read their suggestions.
    5. -
  5. Make changes if you agree.
    6. -
  6. When you and the reviewers agree, they'll approve and merge.
    7. -
  7. If you disagree with feedback, explain why in a comment. Conversation happens.
    Philosophy: "There's no 'good enough' - there's 'what did you try?' and 'what did you learn?' Your first contribution might be small, but it counts."
    8. -
-

Common Patterns & How to Explain Them

-

The Fork-Edit-PR Workflow

-

Why it's confusing: It requires working across three repositories (upstream, your fork, local clone). Visual developers see this as click-fork-click-edit-click-PR. Screen reader users navigate three different sites.

-

How to teach it:

-
"Let me walk through the three repositories.
-
-1. Upstream repo - Community-Access/learning-room
-   This is the official repository. You can't edit it directly.
-
-2. Your fork - [your-name]/learning-room
-   When you click Fork, GitHub copies the entire repo to your account.
-   This is your personal copy. You CAN edit this one.
-
-3. Your local clone - on your laptop, in a folder
-   You get the fork onto your laptop with git clone.
-   You edit here, in actual files, then push back to the fork.
-
-The flow: Edit locally → commit → push to fork → open PR from fork to upstream.
-All three repositories are talking to each other, but you're the only one editing the one you control."
-

GitHub Actions / Automation

-

Why it's confusing: Something happens automatically behind the scenes. Users can't see the mechanism.

-

How to teach it:

-
"When you open a PR, GitHub has optional 'watchers' - like automated reviewers.
-A bot watches for the PR and runs checks.
-Did you follow the format? The bot checks.
-Are there any typos? The bot can scan.
-Invalid markdown? The bot flags it.
-All within 30 seconds. The bot isn't smart - it's just very, very fast.
-And it's not mean - it's teaching. It links you to resources, not blocking you."
-

Merge Conflicts

-

Why it's confusing: Two people can't both change the same line. Git doesn't know which version is right.

-

How to teach it:

-
"Imagine a document you and I are both editing.
-You added a sentence to line 10.
-I also added a sentence to line 10.
-You do it first - your sentence is on main now.
-I try to push my sentence to line 10.
-Git says: 'I have TWO sentences here. I don't know which one is correct.'
-I have to go in and pick one, delete the other, or combine them.
-Then I commit the fix and push again.
-It's not a failure - it's just how parallel editing works."
-

Questions about facilitation? Open an issue with the question label. Contributions to this guide are welcome.

- -
- - - \ No newline at end of file diff --git a/html/FACILITATOR_ASSESSMENT.html b/html/FACILITATOR_ASSESSMENT.html deleted file mode 100644 index 81f11a8..0000000 --- a/html/FACILITATOR_ASSESSMENT.html +++ /dev/null @@ -1,313 +0,0 @@ - - - - - - - FACILITATOR.md - Completeness Assessment - GIT Going with GitHub - - - - - - - - -
-

FACILITATOR.md - Completeness Assessment

-

Summary

-

The FACILITATOR.md guide was 50% complete with excellent coverage of:

-
    -
  • Pre-workshop setup (2 weeks before)
    • -
  • Repository configuration (1 week before)
    • -
  • Pre-session checklists (Day 1 & 2)
    • -
  • GitHub Skills module facilitation
    • -
  • Learning Room automation management
    • -
-

However, it was missing critical sections for hands-on facilitation:

-

What Was MISSING (Before)

-

1. Chapter-by-Chapter Facilitation Notes

-

The guide referenced 16 chapters but provided zero facilitator talking points, discussion starters, or common misconceptions for any of them.

-

Impact: Facilitators had to reverse-engineer from student chapters what students were learning and where they might struggle.

-

2. Accessibility Testing Checklist

-

No systematic guide for verifying screen reader functionality before the workshop.

-

Impact: Starting a workshop with misconfigured screen readers derails the day—this was not prevented.

-

3. Facilitator Q&A Guide

-

No troubleshooting guide for common participant questions and errors.

-

Removed: Facilitators had to troubleshoot in real-time, unsure if a problem was a setup issue, a misunderstanding, or a real bug.

-

4. Accessibility Pedagogy

-

Little guidance on how to explain accessibility topics to learners encountering these tools for the first time.

-

Impact: Accessibility teaching became inconsistent—some facilitators better at explaining than others.

-

5. Common Patterns Explained

-

Complex workflows (fork-edit-PR, merge conflicts, automation) lacked clear mental models.

-

Impact: Explanations rambled; students never got the 2-minute clear explanation they needed.

-

What I've ADDED (Now)

-

Chapter-by-Chapter Facilitation Guide

-

Coverage: All 16 chapters plus introduction chapters (0-2)

-

For each chapter, facilitators now have:

-
    -
  • Facilitator role - what the facilitator should be doing
    • -
  • Key concepts - what the learning objective is
    • -
  • Common issues - where students typically struggle
    • -
  • What to watch for - behavioral cues that signal confusion
    • -
  • Talking points - 2-3 sentence explanation of the core concept
    • -
  • Demo scripts - word-for-word demonst on with exact keyboard commands
    • -
  • Demo what to say - exact narration for screen reader users
    • -
-

Example structure:

-
Chapter 1: Understanding GitHub's Web Structure
-- Purpose: Mental model - three levels of organization + landmark structure
-- Key concept demo: Have everyone press D to navigate landmarks...
-- Common confusion: The difference between repository navigation...
-- Accessibility teaching point: "Landmarks are not visual features..."
-- Demo script: "I'm opening github.com/community-access/learning-room..."
-

Accessibility Testing Checklist

-

5 major categories:

-
    -
  1. Screen Reader Setup (NVDA) - 8 specific tests
    2. -
  2. Screen Reader Setup (JAWS) - 5 specific tests
    3. -
  3. Screen Reader Setup (VoiceOver) - 4 specific tests
    4. -
  4. Browser Configuration - 5 settings to verify
    5. -
  5. VS Code (for Day 2) - 9 checks
    6. -
  6. Exercise Verification - 7 content checks
    7. -
-

Sample checklist items:

-
    -
  • NVDA installed, latest stable version
    • -
  • Browse Mode / Focus Mode switching works (NVDA+Space)
    • -
  • Single-key navigation active: H (headings), D (landmarks), K (links), T (tables)
    • -
  • Elements List opens (Insert+F3)
    • -
  • GitHub.com announces page headings correctly
    • -
  • Hovercards are OFF (GitHub Settings → Accessibility)
    • -
  • VS Code screen reader mode enabled (Shift+Alt+F1)
    • -
-

Usage: Print this, run it on your demo machine and each participant's setup before Day 1 starts. Prevents hours of troubleshooting.

-

Facilitator Q&A Guide

-

10 real participant questions with solutions:

-
    -
  1. "I pressed H and nothing happens" - diagnoses Browse Mode, keyboard mode, page reload
    2. -
  2. "I can't find the Issues tab" - navigates landmarks vs tab order
    3. -
  3. "The table is hard to read" - table mode, navigation patterns
    4. -
  4. "I filed an issue but the bot didn't respond" - checks permissions, workflow status, public/private
    5. -
  5. "I can't commit because 'nothing to commit'" - file saves, working directory, git add
    6. -
  6. "I don't understand the diff" - suggests side-by-side view, alternative review strategies
    7. -
  7. "I keep getting permission denied when pushing" - authentication, branch names, fork vs upstream
    8. -
  8. "The agent command didn't work" - verifies Copilot Chat, @ vs /, offline state
    9. -
  9. "I don't know what commit message to write" - provides template and examples
    10. -
  10. "What if I make a breaking change?" - reassures with protection mechanisms and learning philosophy
    11. -
-

Each answer includes:

-
    -
  • Problem statement
    • -
  • Step-by-step diagnostic (1-5 steps)
    • -
  • Escalation path if basic troubleshooting fails
    • -
  • Teaching point (connects to a larger lesson)
    • -
-

Accessibility Pedagogy Section

-

Teaching methods for participant explanations:

-
    -
  • How to narrate screen reader demos out loud
    • -
  • Why landmarks matter (jump vs. reading)
    • -
  • The difference between announcing vs. understanding
    • -
  • How single-key navigation is a speed tool, not a requirement
    • -
  • When to use Elements List vs. sequential navigation
    • -
  • Accessibility as design principle vs. accessibility as accommodation
    • -
-

Example teaching moment:

-
"The Elements List is a speed tool. When you know what you're looking for, 
-listing all links or buttons gets you there faster than pressing K fifteen times."
-

Common Patterns Explained

-

4 complex workflows with mental models:

-
    -
  1. Fork-Edit-PR Workflow - explanation of three repositories and why
    2. -
  2. GitHub Actions / Automation - what automation is, why it's not grading, why it's teaching
    3. -
  3. Merge Conflicts - parallel editing metaphor, resolution process
    4. -
  4. Screen Reader Access - how different devices see the same page differently
    5. -
-

Each includes a 3-5 minute clear explanation suitable for live teaching.

-

File Statistics

-

Original FACILITATOR.md:

-
    -
  • 394 lines
    • -
  • Covered: setup, config, checklists, automation, GitHub Skills demo
    • -
-

Enhanced FACILITATOR.md:

-
    -
  • 850+ lines (2.15x larger)
    • -
  • Added: chapter guidance, testing, Q&A, pedagogy, patterns
    • -
-

How to Use This Enhanced Guide

-

Week Before Workshop

-
    -
  1. Read the Accessibility Testing Checklist
    2. -
  2. Test your demo machine and participant machines using that checklist
    3. -
  3. Fix any issues found
    4. -
-

2 Days Before Workshop

-
    -
  1. Re-read the Chapter-by-Chapter Guide for chapters you'll be teaching that day
    2. -
  2. Practice the Demo Scripts out loud (you'll say these during the workshop)
    3. -
  3. Bookmark the Facilitator Q&A Guide in your web browser for quick access
    4. -
-

During Workshop

-
    -
  1. Use Q&A Guide for real-time troubleshooting (someone stuck? Check the guide)
    2. -
  2. Reference Chapter prep before each block (5 minutes before activity starts, check what students might struggle with)
    3. -
  3. Use Common Patterns section to explain complex topics clearly
    4. -
  4. Refer to Accessibility Pedagogy when explaining why we do things
    5. -
-

After Workshop

-
    -
  1. Collect feedback on which Q&A solutions helped most
    2. -
  2. Collect feedback on which demo scripts were clearest
    3. -
  3. Contribute back: if you discovered a new common question, add it to the Q&A Guide
    4. -
  4. File issues for any demo commands that need updating (GitHub UI changes)
    5. -
-

What Still Exists from Before

-

Pre-workshop setup (Section 1-3)
GitHub Skills facilitator scripts (Section 5)
Automation management (Section 6)
Accessibility notes for facilitators (Section 7)
Personalization guidance (Section 8)

-

All of this remains intact and is now followed by the new comprehensive facilitation sections.

-

Next Step: Facilitator Handbook (Optional)

-

This guide is now technically complete. However, an optional next step would be to create a Facilitator Handbook (separate from this guide) that includes:

-
    -
  • Slide deck outlines (if facilitator wants to present alongside hands-on work)
    • -
  • Time estimates and pace per activity
    • -
  • Suggested ice-breakers and group-building activities
    • -
  • Post-workshop reflection templates for facilitators
    • -
  • Templates for customizing the curriculum for your project
    • -
  • Metrics for measuring learning outcomes
    • -
-

This guide gives you what to teach and how. A handbook would add when and how to measure.

-

Completeness Rating

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CategoryBeforeAfterNotes
Repository setup guidance95%95%No changes needed
Pre-session checklists90%90%No changes needed
GitHub Skills facilitation85%85%No changes needed
Automation management80%80%Added section on automation philosophy
Chapter guidance0%95%ADDED: 400+ lines
Troubleshooting10%90%ADDED: Q&A guide, 10 scenarios
Accessibility testing5%98%ADDED: full checklist
Teaching methodology0%85%ADDED: pedagogy section
Common concepts5%90%ADDED: 4 major patterns explained
Overall completeness~40%~92%2.3x more content, all critical gaps filled
-

Validation Checklist

-

Use this to verify the guide works for your workshop:

-
    -
  • Read the entire Chapter-by-Chapter section (takes ~30 minutes)
    • -
  • Try one Demo Script out loud (verify commands, timing)
    • -
  • Run the Accessibility Testing Checklist on one participant machine
    • -
  • Try the Q&A Guide - ask yourself 3 questions from the list, verify the answers help
    • -
  • Have someone read the Common Patterns section and confirm the explanations are clear
    • -
  • After workshop, gather facilitator feedback: "Which sections were most useful?"
    • -
-

This assessment was generated March 5, 2026 during workshop preparation.

- -
- - - \ No newline at end of file diff --git a/html/FAQ.html b/html/FAQ.html deleted file mode 100644 index a9d5938..0000000 --- a/html/FAQ.html +++ /dev/null @@ -1,869 +0,0 @@ - - - - - - - FAQ: Frequently Asked Questions - GIT Going with GitHub - - - - - - - - -
-

FAQ: Frequently Asked Questions

-

Table of Contents

- -

About This Workshop

-

Q: Is this guide only for programmers?

-

A: No. While it focuses on GitHub (a platform developers use), the concepts apply to anyone collaborating on projects. Documentation improvements, issue filing, accessibility testing, and code reviews are all valuable contributions that require no coding. Start: Chapter 1 - no coding required.

-

Q: Do I need to know how to code to understand this guide?

-

A: Not for most chapters. Chapters 0-10 teach GitHub concepts without requiring code knowledge. Chapters 5 and 11-16 introduce programming tools and concepts but explain them for beginners. If you are non-technical, you can skip code examples and still understand the workflows.

-

Q: How long will this take?

-

A: Depends on your path:

-
    -
  • Core path (Day 1 only): ~7.5 hours of structured time
    • -
  • Full curriculum (Day 1 + Day 2): ~15 hours total
    • -
  • Just the essentials: 3-4 hours (Chapters 0, 1, 4, 6)
    • -
  • Self-paced: Read at your own speed - there is no timer
    • -
-

Q: Can I do this workshop on my own, or do I need a group?

-

A: You can do most of the workshop solo. The chapters, exercises, and appendices are self-contained. A few exercises in the Learning Room (Chapter 3) involve peer review and are designed for groups, but you can still practice the individual challenges on your own.

-

Q: What is the difference between Day 1 and Day 2?

-

A: Day 1 uses the GitHub web interface only - everything happens in your browser. Day 2 moves to VS Code on the desktop and introduces GitHub Copilot and Accessibility Agents. Day 1 skills are prerequisite for Day 2 - the agents only make sense when you understand what they automate.

-

Q: Is there a certificate or badge for completing this workshop?

-

A: The GitHub Skills modules (used during Day 1) award completion badges on your GitHub profile. These are visible to anyone who visits your profile. The workshop itself does not issue a separate certificate, but your merged PR to community-access/accessibility-agents on Day 2 is permanent proof of contribution.

-

Q: Where can I find the course outline and table of contents?

-

A: See the Course Guide for the full table of contents, chapter sequence, timing, and exercises at a glance.

-

Is This For Me?

-

Q: I am a complete beginner to GitHub. Where do I start?

-

A: Start with Chapter 0 (Pre-Workshop Setup) to install tools, then Chapter 1 (Understanding GitHub Web Structure). Both assume zero prior knowledge.

-

Q: I use GitHub at work but do not understand how to use it well. Can this help?

-

A: Yes. Chapter 4 (Working with Issues) and Chapter 6 (Working with Pull Requests) will deepen your understanding. Then jump to Chapter 14 (Accessible Code Review) for best practices.

-

Q: I am a maintainer of an open-source project. What should I read?

-

A: Chapter 9 (Labels, Milestones & Projects) → Chapter 15 (Issue Templates) → Chapter 16 (Accessibility Agents). These focus on organizing projects and automating common tasks.

-

Q: I am teaching GitHub to a group. Do I need to know everything?

-

A: Yes, read the full curriculum first. Also read FACILITATOR.md, DAY1_AGENDA.md, and DAY2_AGENDA.md for lesson plans and pacing tips.

-

Q: I use screen readers (NVDA, JAWS, or VoiceOver). Is this guide accessible?

-

A: Yes. This guide was designed for screen reader users from the beginning. Every chapter includes screen reader instructions and keyboard-only workflows. Start with Appendix B (Screen Reader Cheat Sheet) for a quick command reference.

-

Q: I am sighted. Can I still use this workshop?

-

A: Absolutely. All content is keyboard-navigable. Sighted participants benefit from the same structured approach to GitHub, and the accessibility-first perspective teaches habits that make all collaboration better.

-

Q: I am not a native English speaker. Can I understand this?

-

A: All technical terms are defined in Appendix A (Glossary). The language is intentionally simple and direct. If anything is unclear, open an issue on GitHub or check QUICK_REFERENCE.md.

-

Q: I only have a few hours. What is the minimum I should read?

-

A: Read Chapters 0, 1, 4, and 6. That covers setup, GitHub structure, issues, and pull requests - enough to start contributing to any project.

-

Getting Started

-

Q: I installed Git, but I am getting "git: command not found". What do I do?

-

A: See TROUBLESHOOTING.md → "Problem: Git is not installed". It has platform-specific steps for Windows, macOS, and Linux.

-

Q: I created a GitHub account, but I cannot clone repositories. Why?

-

A: You likely need to set up authentication (SSH key or HTTPS personal access token). See Chapter 0 (Pre-Workshop Setup) or Appendix D (Git Authentication).

-

Q: Do I need to understand branching and merging before starting?

-

A: No. Branching is covered in Chapter 6 (Pull Requests) and merge conflicts are covered in Chapter 7. You learn as you go.

-

Q: What software do I need to install before Day 1?

-

A: For Day 1 (browser only):

-
    -
  • A modern web browser (Chrome, Edge, Firefox, or Safari)
    • -
  • Git (for cloning repositories)
    • -
  • A GitHub account (free tier is fine)
    • -
-

For Day 2 (VS Code):

-
    -
  • Visual Studio Code
    • -
  • GitHub Copilot and Copilot Chat extensions
    • -
  • GitHub Pull Requests and Issues extension
    • -
-

Full instructions: Chapter 0 (Pre-Workshop Setup)

-

Q: Which browser works best with screen readers?

-

A:

-
    -
  • NVDA: Firefox or Chrome both work well. Firefox has slightly better ARIA support.
    • -
  • JAWS: Chrome or Edge are recommended. JAWS has strong support for Chromium-based browsers.
    • -
  • VoiceOver: Safari is the most compatible browser on macOS.
    • -
-

Q: Do I need a paid GitHub account?

-

A: No. A free GitHub account is sufficient for everything in this workshop, including creating repositories, filing issues, opening pull requests, and participating in discussions. GitHub Copilot has a free tier with limited usage, but a paid subscription (~$10/month) provides full access for Day 2 content.

-

Q: Can I use a Chromebook or tablet?

-

A: Day 1 (browser-based) works on any device with a modern browser and a keyboard. Day 2 requires Visual Studio Code, which runs on Windows, macOS, and Linux desktops. If you have a Chromebook, consider GitHub Codespaces as an alternative to a local VS Code install.

-

Screen Readers and Accessibility

-

Q: Which screen readers are supported?

-

A: The workshop is tested with:

-
    -
  • NVDA 2025.3.3 on Windows
    • -
  • JAWS 2026 on Windows
    • -
  • VoiceOver on macOS Sonoma and later
    • -
-

Other screen readers (Narrator, Orca, BRLTTY) may work but are not tested.

-

Q: Do I need to change any screen reader settings before starting?

-

A: The main thing to verify is:

-
    -
  • Browse mode (also called virtual mode or document mode) should be active for web navigation
    • -
  • Hovercards should be turned off in GitHub settings (they interfere with screen reader navigation)
    • -
-

Detailed setup is in Chapter 0 (Pre-Workshop Setup), Step 4.

-

Q: What is the difference between Browse Mode and Focus Mode?

-

A:

-
    -
  • Browse Mode (virtual/document mode): Your screen reader intercepts keystrokes and uses them for navigation (H for headings, B for buttons, K for links). Use this when reading web pages.
    • -
  • Focus Mode (forms/application mode): Keystrokes go directly to the web page or application. Use this when typing in text fields, dropdown menus, or interactive widgets.
    • -
  • Toggle: NVDA uses NVDA+Space, JAWS toggles automatically (or Insert+Z to force), VoiceOver uses VO+Shift+F5.
    • -
-

Q: GitHub is not announcing headings or landmarks. What is wrong?

-

A: Several possible causes:

-
    -
  1. You may be in Focus Mode instead of Browse Mode - press NVDA+Space (NVDA) or Insert+Z (JAWS) to toggle
    2. -
  2. Hovercards may be enabled - go to GitHub Settings → Accessibility → turn off "Hovercards"
    3. -
  3. The page may not have loaded fully - wait a few seconds and try again
    4. -
  4. See TROUBLESHOOTING.md → "Screen Readers & Accessibility" for more solutions
    5. -
-

Q: Can I use a braille display?

-

A: Yes. NVDA and JAWS both support braille output. The workshop documents render as standard text. VS Code supports braille through your screen reader's braille driver. No special configuration is needed beyond your normal braille setup.

-

Q: What keyboard shortcuts do I need to know?

-

A: The most important ones:

-
    -
  • H - Jump to next heading (Browse Mode)
    • -
  • D - Jump to next landmark
    • -
  • B - Jump to next button
    • -
  • K - Jump to next link
    • -
  • F - Jump to next form field
    • -
  • Tab - Move to next interactive element
    • -
  • Ctrl+Enter - Submit text on GitHub
    • -
  • NVDA+F7 / Insert+F3 / VO+U - Elements List / Rotor
    • -
-

Full reference: Appendix B (Screen Reader Cheat Sheet)

-

Q: How do I navigate tables with a screen reader?

-

A:

-
    -
  • NVDA: T jumps to next table. Once inside, use Ctrl+Alt+Arrow keys to move between cells.
    • -
  • JAWS: T jumps to next table. Ctrl+Alt+Arrow keys within cells.
    • -
  • VoiceOver: VO+Right/Left through cells, or use the Rotor (VO+U) set to "Tables."
    • -
-

Q: Can I zoom in or increase font size without breaking the layout?

-

A: Yes. GitHub's web interface is responsive. Use Ctrl++ (or Cmd++ on Mac) to zoom in. The HTML versions of workshop documents (in the html/ folder) are also responsive and work at any zoom level.

-

Q: How do I know if a page element is interactive?

-

A: Your screen reader announces the role of each element - "button," "link," "edit text," "checkbox," etc. If it announces "clickable" without a more specific role, it may not be fully accessible. In that case, try Enter or Space to activate it.

-

GitHub Accounts and Authentication

-

Q: I forgot my GitHub password. How do I reset it?

-

A: Go to https://github.com/password_reset, enter your email, and follow the reset link. If you use two-factor authentication (2FA) and lost access to your second factor, see GitHub's account recovery documentation.

-

Q: Should I use SSH or HTTPS for Git authentication?

-

A:

-
    -
  • SSH: More secure, no password prompts after setup, recommended for regular use
    • -
  • HTTPS with Personal Access Token: Easier initial setup, works through corporate firewalls that block SSH
    • -
  • Recommendation: Use SSH if you can. See Appendix D (Git Authentication) for setup instructions for both.
    • -
-

Q: What is a Personal Access Token (PAT) and why do I need one?

-

A: GitHub no longer allows password authentication for Git operations over HTTPS. A PAT is a generated string that replaces your password. Create one at https://github.com/settings/tokens. Give it repo scope for full repository access. Treat it like a password - do not share it.

-

Q: How do I store my credentials so I do not have to enter them every time?

-

A:

-
    -
  • Windows: git config --global credential.helper manager (stores securely in Windows Credential Manager)
    • -
  • macOS: git config --global credential.helper osxkeychain (stores securely in Keychain)
    • -
  • Linux: git config --global credential.helper cache (temporary - expires after 15 minutes by default) or use a keyring-based helper
    • -
-

Never use credential.helper store on shared or multi-user systems - it saves credentials in plaintext.

-

Q: How do I set up two-factor authentication?

-

A: Go to https://github.com/settings/security → "Enable two-factor authentication." GitHub supports authenticator apps (recommended), security keys, and SMS. After enabling 2FA, you will need recovery codes - save them somewhere safe.

-

Security note: We strongly recommend enabling 2FA on your GitHub account. If you cannot enable 2FA, you may still participate by adding an SSH key or creating a Personal Access Token (PAT) with repo scope for Git operations. Contact the workshop organizers if you need help.

-

Q: My organization uses SSO (Single Sign-On). Does that affect anything?

-

A: Yes. After authenticating with SSO, you may need to authorize your SSH key or PAT for that organization. Go to https://github.com/settings/tokens → find your token → click "Configure SSO" → authorize for your org.

- -

Q: What are the main sections of a GitHub repository page?

-

A: Every repository has these tabs:

-
    -
  • Code - File tree, README, branch selector
    • -
  • Issues - Bug reports, feature requests, discussions
    • -
  • Pull Requests - Proposed changes waiting for review
    • -
  • Actions - Automated workflows (CI/CD)
    • -
  • Projects - Project boards for organizing work
    • -
  • Settings - Repository configuration (owner/admin only)
    • -
-

Navigate between tabs using the D key to find the "Repository navigation" landmark, then arrow through the tabs.

-

Q: How do I quickly find a file in a repository?

-

A: Press T on any repository page to open the file finder. Start typing the filename - results filter as you type. Press Enter to open the file. This works with your screen reader in Browse Mode.

-

Q: How do I read a file on GitHub?

-

A: Navigate to the file in the Code tab and click (or press Enter) on its name. The file opens in a rendered view (for Markdown) or a code view (for code files). Use H to navigate headings in Markdown files.

-

Q: How do I switch branches?

-

A: On the Code tab, find the branch selector button (it shows the current branch name, usually "main"). Press Enter to open it, type the branch name, and select from the filtered list. Screen reader tip: use B to find the button.

-

Q: What are GitHub keyboard shortcuts?

-

A: GitHub has built-in keyboard shortcuts. Press ? on any GitHub page to see the full list. Key shortcuts:

-
    -
  • G then I - Go to Issues
    • -
  • G then P - Go to Pull Requests
    • -
  • T - Open file finder
    • -
  • . - Open the repository in github.dev (VS Code in your browser)
    • -
  • / - Focus the search bar
    • -
-

Full reference: Appendix B (Screen Reader Cheat Sheet)

-

Q: Why does GitHub look different from what the guide describes?

-

A: GitHub regularly updates its interface. The core structure (tabs, headings, landmarks) remains consistent, but specific button labels or layout may change. If something does not match the guide, navigate by role (use B for buttons, H for headings) rather than relying on exact position.

-

Q: How do I use GitHub search effectively?

-

A: Use the search bar (/ to focus it) with qualifiers:

-
    -
  • is:issue is:open label:bug - Find open bug issues
    • -
  • is:pr is:open review-requested:@me - Find PRs awaiting your review
    • -
  • language:python stars:>100 - Find popular Python repositories
    • -
-

Full reference: Appendix J (Advanced Search)

-

Issues

-

Q: What is the difference between an issue and a pull request?

-

A:

-
    -
  • Issue = A problem or request (e.g., "Fix login bug" or "Add dark mode")
    • -
  • Pull request = Your solution - the actual changed code or documentation that fixes the issue
    • -
  • An issue describes what needs to happen. A PR makes it happen.
    • -
  • See Chapter 4 for issues and Chapter 6 for PRs.
    • -
-

Q: How do I know if I should open an issue or a PR?

-

A:

-
    -
  • Open an issue if: You found a bug, want to suggest a feature, have a question, or want to discuss something
    • -
  • Open a PR if: You already have the changes ready to fix or improve something
    • -
  • Both? Open the issue first, discuss with maintainers, then open a PR that references the issue
    • -
-

Q: How do I file a good issue?

-

A: A good issue includes:

-
    -
  1. Clear title - Describe the problem, not the solution ("Screen reader skips navigation landmark" not "Fix thing")
    2. -
  2. Steps to reproduce - What did you do? What happened? What did you expect?
    3. -
  3. Environment - Your operating system, browser, screen reader, and versions
    4. -
  4. Screenshots or recordings - If possible and relevant
    5. -
  5. Labels - Apply the most relevant label (bug, enhancement, accessibility, etc.)
    6. -
-

Q: What is a "good first issue"?

-

A: A label that maintainers add to issues that are suitable for first-time contributors. These issues are typically well-defined, small in scope, and have clear instructions. Filter for them: Issues tab → filter by label → good first issue.

-

Q: How do I reference a specific issue in a comment?

-

A: Type # followed by the issue number (e.g., #42). GitHub auto-links it. For issues in other repositories, use the full format: owner/repo#42.

-

Q: How do I close an issue automatically when a PR is merged?

-

A: Include one of these keywords followed by the issue number in your PR description:

-
    -
  • Closes #42
    • -
  • Fixes #42
    • -
  • Resolves #42
    • -
-

When the PR is merged, the issue closes automatically.

-

Q: Can I reopen a closed issue?

-

A: Yes. Navigate to the closed issue and click "Reopen issue." Only people with write access to the repository can reopen issues filed by others.

-

Q: How do I subscribe to or unsubscribe from an issue?

-

A: On the issue sidebar, find the "Notifications" section. Click "Subscribe" to get notified of all comments, or "Unsubscribe" to stop notifications. You are automatically subscribed to issues you create or comment on.

-

Pull Requests

-

Q: What is a pull request, and why is it called that?

-

A:

-
    -
  • A pull request (PR) asks the maintainer to "pull" your changes into their repository
    • -
  • Literally: "I have changes on my branch. Please pull them into the main branch."
    • -
  • GitLab calls the same concept a "merge request"
    • -
  • See Chapter 6 (Working with Pull Requests)
    • -
-

Q: What are the three tabs of a pull request?

-

A:

-
    -
  1. Conversation - Title, description, comments, timeline, status checks
    2. -
  2. Commits - Individual commits in the PR, with author and message
    3. -
  3. Files Changed - The diff showing every line added, modified, or removed
    4. -
-

Navigate between tabs using your screen reader's heading navigation or landmark navigation.

-

Q: How long does it take to get PR feedback?

-

A: Depends on the project:

-
    -
  • Your organization's repo: Hours to a few days
    • -
  • Active open-source projects: Days to a week
    • -
  • Smaller projects: Could be weeks
    • -
  • Check the project's CONTRIBUTING.md for estimated review times
    • -
-

Q: What does "merge" mean?

-

A: Combining two branches of code. After your PR is approved, it is "merged" into the main branch. Your changes become part of the official codebase.

-

Q: What are the different merge strategies?

-

A:

-
    -
  • Merge commit: Creates a merge commit that ties the two branches together. Preserves full history.
    • -
  • Squash and merge: Combines all your PR's commits into one commit on main. Cleaner history.
    • -
  • Rebase and merge: Replays your commits on top of main. Linear history, no merge commits.
    • -
  • Which to use: Follow the project's convention. When in doubt, "Squash and merge" is usually safe.
    • -
-

Q: My PR says "This branch has conflicts that must be resolved." What do I do?

-

A: See Chapter 7 (Merge Conflicts). In short:

-
    -
  1. Pull the latest main: git pull upstream main
    2. -
  2. Merge main into your branch: git merge main
    3. -
  3. Resolve the conflicts in your editor
    4. -
  4. Commit and push the resolution
    5. -
-

Q: How do I update my PR with new changes?

-

A: Just push more commits to the same branch. The PR updates automatically. No need to close and reopen.

-

Q: How do I request a review on my PR?

-

A: On the PR page, find the "Reviewers" section in the sidebar. Click the gear icon and select reviewers. They will be notified.

-

Q: What does "draft pull request" mean?

-

A: A draft PR signals that your work is not ready for review yet. Reviewers can still look at it, but it cannot be merged. When ready, click "Ready for review" to convert it. Use drafts for work-in-progress when you want early feedback.

-

Q: Can I edit someone else's PR?

-

A: Only if the PR author checked "Allow edits from maintainers" and you have write access to the target repository. Otherwise, you can suggest changes in a review comment using the suggestion feature.

-

Merge Conflicts

-

Q: What is a merge conflict?

-

A: A merge conflict happens when two people edit the same lines of the same file on different branches. Git cannot decide which version to keep, so it asks you to choose. It is not an error - it is a normal part of collaboration.

-

Q: How do I recognize a merge conflict?

-

A: Git marks the conflicting sections with these markers:

-
<<<<<<< HEAD
-Your changes
-=======
-Their changes
->>>>>>> branch-name
-

Your screen reader will read these markers as text. See Chapter 7 for how to interpret them.

-

Q: How do I resolve a merge conflict?

-

A: Three approaches:

-
    -
  1. Keep your changes: Delete their version and the markers
    2. -
  2. Keep their changes: Delete your version and the markers
    3. -
  3. Combine both: Edit the file to include the best of both, then delete the markers
    4. -
-

After resolving: git add [filename] → git commit -m "Resolved merge conflict"

-

Q: Can I abort a merge?

-

A: Yes. git merge --abort cancels the merge and returns your branch to its pre-merge state. Nothing is lost.

-

Q: How do I prevent merge conflicts?

-

A:

-
    -
  • Pull from main frequently: git pull upstream main
    • -
  • Keep PRs small and focused (one change per PR)
    • -
  • Communicate with your team about which files you are editing
    • -
  • Avoid editing the same lines as someone else
    • -
-

Branches and Forks

-

Q: What is the difference between a fork and a branch?

-

A:

-
    -
  • Fork = Your complete separate copy of a repository, on your GitHub account
    • -
  • Branch = A version of the code within a single repository
    • -
  • Use a fork to: Contribute to someone else's open-source project
    • -
  • Use a branch to: Work on features in your own repository or your org's repository
    • -
-

Q: Why do I need to fork before contributing to open source?

-

A: You do not have write access to most open-source repositories. Forking creates your own copy where you can make changes freely. Then you open a PR from your fork to the original repository.

-

Q: How do I keep my fork up to date with the original repository?

-

A:

-
    -
  1. Add the original as "upstream": git remote add upstream https://github.com/ORIGINAL-OWNER/REPO.git
    2. -
  2. Fetch upstream: git fetch upstream
    3. -
  3. Merge into your main: git checkout main → git merge upstream/main
    4. -
  4. Push to your fork: git push origin main
    5. -
-

Q: When should I create a new branch?

-

A: Always create a new branch before starting work on a change. Never commit directly to main. Name your branch descriptively: fix/broken-link, feature/dark-mode, docs/update-readme.

-

Q: How do I delete a branch after my PR is merged?

-

A:

-
    -
  • On GitHub: After merging, GitHub shows a "Delete branch" button on the PR page
    • -
  • Locally: git branch -d branch-name (safe delete - only works if merged) or git branch -D branch-name (force delete)
    • -
-

Markdown

-

Q: What is Markdown?

-

A: A lightweight text formatting language. You write plain text with symbols (# for headings, ** for bold, - for lists), and GitHub renders it as formatted HTML. Every issue, PR, comment, and documentation file on GitHub uses Markdown.

-

Q: What are the most important Markdown commands?

-

A:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SyntaxResult
# Heading 1Large heading
## Heading 2Medium heading
**bold**bold
*italic*italic
[text](url)A hyperlink
`code`Inline code
- itemBullet list
1. itemNumbered list
> quoteBlockquote
- [ ] taskCheckbox (task list)
-

Full reference: Appendix E (GitHub Flavored Markdown)

-

Q: How do I add a code block in Markdown?

-

A: Wrap code in triple backticks. Add a language name for syntax highlighting:

-
```python
-print("Hello, world!")
-```
-

Q: How do I add a table in Markdown?

-

A:

-
| Column 1 | Column 2 |
-|----------|----------|
-| Cell 1   | Cell 2   |
-| Cell 3   | Cell 4   |
-

The | characters create columns. The --- row separates the header from the body.

-

Q: What is GitHub Flavored Markdown (GFM)?

-

A: GitHub's extended version of Markdown that adds features like task lists (- [ ]), tables, strikethrough (~~text~~), autolinked URLs, emoji (:smile:), alert blocks, Mermaid diagrams, and math expressions. See Appendix E.

-

Q: How do I preview Markdown before submitting?

-

A: On GitHub, click the "Preview" tab above any text input area. In VS Code, press Ctrl+Shift+V to open Markdown preview in a new tab, or Ctrl+K V for a side-by-side preview.

-

Labels, Milestones, and Projects

-

Q: What are labels for?

-

A: Labels categorize issues and PRs. Common labels: bug, enhancement, documentation, good first issue, accessibility, help wanted. They help maintainers prioritize and contributors find work. See Chapter 9.

-

Q: How do I filter issues by label?

-

A: On the Issues tab, click "Labels" (or use the filter bar and type label:bug). You can combine labels: label:bug label:accessibility finds issues with both labels.

-

Q: What is a milestone?

-

A: A grouping of issues and PRs that represent a goal or deadline (e.g., "v2.0 Release" or "Hackathon Day 1"). Milestones show a progress bar indicating how many items are complete.

-

Q: What is a GitHub Project?

-

A: A flexible planning tool with boards (Kanban-style columns), tables, and roadmaps. You can add issues and PRs from multiple repositories. See Appendix I (GitHub Projects Deep Dive).

-

Notifications

-

Q: How do I manage GitHub notifications without being overwhelmed?

-

A:

-
    -
  1. Go to https://github.com/notifications
    2. -
  2. Use filters: Unread, Participating, @mentioned, Assigned
    3. -
  3. Mark threads as "Done" (E keyboard shortcut) to clear them
    4. -
  4. Set watch preferences per repository: "Participating and @mentions" is usually best
    5. -
  5. Configure email preferences at https://github.com/settings/notifications
    6. -
-

See Chapter 10 (Notifications).

-

Q: What is the difference between "Watching," "Participating," and "@mentioned"?

-

A:

-
    -
  • Watching: You receive notifications for all activity on the repository
    • -
  • Participating: You are notified about issues/PRs you have commented on or been assigned to
    • -
  • @mentioned: Someone tagged you specifically with @your-username
    • -
-

Q: How do I stop getting email notifications?

-

A: Go to https://github.com/settings/notifications → uncheck "Email" under the notification types you want to silence.

-

Q: How do I navigate notifications with a screen reader?

-

A: On the notifications page:

-
    -
  • H to jump between notification groups (by repository)
    • -
  • K to move between individual notifications
    • -
  • E to mark as Done from the list
    • -
  • Shift+I to mark as Read
    • -
  • Enter to open the linked issue or PR
    • -
-

VS Code

-

Q: Why do we use VS Code instead of another editor?

-

A: VS Code has the best built-in accessibility support of any mainstream code editor: dedicated screen reader mode, Accessible Help dialog, Accessible View, Accessible Diff Viewer, and audio cues for editor events. It also has first-party GitHub and Copilot integration.

-

Q: What is github.dev?

-

A: VS Code running in your browser - no installation needed. Press . on any GitHub repository to open it in github.dev. The keyboard shortcuts and screen reader mode are identical to desktop VS Code. github.dev cannot run a terminal, Copilot agents, or local extensions - that is what desktop VS Code adds.

-

Q: How do I enable screen reader mode in VS Code?

-

A: VS Code detects NVDA and JAWS automatically. If it does not, press Shift+Alt+F1 to manually enable screen reader mode. Verify: Ctrl+Shift+P → type "accessibility" → look for "Toggle Screen Reader Accessibility Mode" with a checkmark.

-

Q: What are the most important VS Code keyboard shortcuts?

-

A:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ShortcutAction
Ctrl+Shift+PCommand Palette - search for any command
Ctrl+PQuick Open - search for any file
Ctrl+Shift+EExplorer sidebar (file tree)
Ctrl+Shift+GSource Control panel
Ctrl+Shift+IOpen Copilot Chat
Ctrl+ (backtick)Toggle terminal
Ctrl+,Open Settings
F7Accessible Diff Viewer
Alt+F2Accessible View
Shift+Alt+F1Toggle screen reader mode
-

Full reference: Appendix M (VS Code Accessibility Reference)

-

Q: VS Code extensions are not loading or crashing. What do I do?

-

A: See TROUBLESHOOTING.md → "VS Code extensions not loading." Quick fix: Ctrl+Shift+P → "Developer: Reload Window." If that does not work, check the Output panel (View → Output → select the extension name from the dropdown) for error messages.

-

Q: How do I navigate the VS Code sidebar with a screen reader?

-

A: The sidebar has five main views, each with a keyboard shortcut:

-
    -
  • Ctrl+Shift+E - Explorer (files)
    • -
  • Ctrl+Shift+F - Search
    • -
  • Ctrl+Shift+G - Source Control
    • -
  • Ctrl+Shift+D - Debug
    • -
  • Ctrl+Shift+X - Extensions
    • -
-

Within each view, use Tab, Arrow keys, and Enter to navigate.

-

Q: What is the Accessible View and when should I use it?

-

A: Press Alt+F2 to open the Accessible View. It renders any VS Code content (Copilot Chat responses, hover tooltips, notifications) as a plain text document that your screen reader can read naturally. Use it whenever VS Code's default rendering is hard to navigate.

-

Q: What are audio cues (accessibility signals) in VS Code?

-

A: VS Code can play short sounds for events like errors, warnings, breakpoints, and diff changes. Configure them at Settings → search accessibility.signals. Each signal can be set to "on," "off," or "auto" (only when a screen reader is detected). See Appendix M.

-

Git and Source Control in VS Code

-

Q: How do I clone a repository in VS Code?

-

A: Ctrl+Shift+P → type "Git: Clone" → paste the repository URL → choose a local folder → VS Code opens the cloned repo.

-

Q: How do I commit changes in VS Code?

-

A:

-
    -
  1. Make your changes in the editor
    2. -
  2. Open Source Control: Ctrl+Shift+G
    3. -
  3. Review changed files (they appear in "Changes")
    4. -
  4. Stage files: select a file and press + (or right-click → "Stage Changes")
    5. -
  5. Type your commit message in the text box
    6. -
  6. Press Ctrl+Enter to commit
    7. -
-

Q: How do I push my commits to GitHub?

-

A: After committing, click "Sync Changes" in the Source Control panel (or run Ctrl+Shift+P → "Git: Push"). If your branch is not yet on GitHub, VS Code will ask to publish it.

-

Q: How do I create a new branch in VS Code?

-

A: Click the branch name in the bottom-left status bar (or Ctrl+Shift+P → "Git: Create Branch"). Type the new branch name and press Enter. VS Code switches to the new branch automatically.

-

Q: What is the Source Control panel telling me?

-

A: The Source Control panel (Ctrl+Shift+G) shows:

-
    -
  • Changes - Files you have modified but not staged
    • -
  • Staged Changes - Files ready to be committed
    • -
  • Merge Changes - Files with merge conflicts (if any)
    • -
  • The commit message input box
    • -
  • Buttons for Commit, Sync, and more
    • -
-

Q: How do I view a diff in VS Code?

-

A: In the Source Control panel, click any changed file. VS Code opens a side-by-side diff view. For accessible navigation, press F7 to open the Accessible Diff Viewer, which reads changes sequentially.

-

GitHub Copilot

-

Q: What is GitHub Copilot?

-

A: An AI-powered coding assistant that runs inside VS Code. It offers two main features:

-
    -
  1. Inline suggestions - Copilot predicts what you will type next and offers completions. Press Tab to accept.
    2. -
  2. Copilot Chat - A conversational interface (Ctrl+Shift+I) where you can ask questions, get explanations, and generate content.
    3. -
-

See Chapter 13 (GitHub Copilot).

-

Q: Do I need a paid subscription to use Copilot?

-

A: GitHub Copilot now offers a free tier with limited usage. For full access including chat and agents, you need:

-
    -
  • Copilot Individual: ~$10/month or $100/year
    • -
  • Copilot Business/Enterprise: Through your organization
    • -
  • Students/Educators: Free access at https://education.github.com/
    • -
-

Q: How do I open Copilot Chat?

-

A: Press Ctrl+Shift+I. The Chat panel opens as a sidebar. Type your question and press Enter. Use Alt+F2 (Accessible View) to read Copilot's response with your screen reader.

-

Q: How do I know what Copilot said? The response is hard to read with my screen reader.

-

A: Press Alt+F2 to open the Accessible View. This renders Copilot's response as plain text that your screen reader can read sequentially. This is the recommended workflow for screen reader users.

-

Q: Can Copilot write entire files for me?

-

A: Copilot can generate significant amounts of code or documentation, but you should always review and edit its output. Copilot is a writing partner, not a replacement for your judgment. Its output may contain errors, outdated information, or tone mismatches.

-

Q: What are chat participants?

-

A: Prefixes like @workspace, @vscode, @terminal that tell Copilot to focus on a specific context:

-
    -
  • @workspace - Ask about your entire project
    • -
  • @vscode - Ask about VS Code settings and commands
    • -
  • @terminal - Ask about terminal commands
    • -
  • Agent names like @daily-briefing - Use a specific Accessibility Agents agent
    • -
-

Q: What are slash commands in Copilot Chat?

-

A: Commands starting with / that trigger specific behaviors:

-
    -
  • /explain - Explain the selected code
    • -
  • /fix - Suggest a fix for the selected code
    • -
  • /tests - Generate tests
    • -
  • /doc - Generate documentation
    • -
  • Custom commands from Accessibility Agents (28 available)
    • -
-

Full reference: Appendix W (GitHub Copilot Reference)

-

Q: Copilot Chat is not responding or freezing. What do I do?

-

A: See TROUBLESHOOTING.md → "Copilot Chat freezes or stops responding." Quick fix: Close the chat panel, reopen with Ctrl+Shift+I. Check your internet connection and Copilot subscription status.

-

Q: Can I choose which AI model Copilot uses?

-

A: Yes. In Copilot Chat, click the model selector (announced by your screen reader near the input field) to choose from available models. Different models have different strengths. See Appendix X (Copilot AI Models).

-

Accessibility Agents

-

Q: What is Accessibility Agents?

-

A: An ecosystem of 55 AI-powered agents organized into three teams (Accessibility, GitHub Workflow, Developer Tools), running on five platforms. It includes 54+ slash commands and is an MIT-licensed open-source project at community-access/accessibility-agents that you will fork, use, and contribute to during the workshop. See Chapter 16 (Accessibility Agents).

-

Q: What agents are available?

-

A: The ecosystem spans three teams:

- - - - - - - - - - - - - - - - - - - - - - - -
TeamAgentsFocus
Accessibility26Web, document, mobile, ePub auditing and remediation
GitHub Workflow12Issue triage, PR review, analytics, templates, repo management
Developer Tools6Python, desktop, wxPython accessibility patterns
-

See Appendix V for the complete list of all 55 agents.

-

Q: Do I need to install anything to use agents?

-

A: No separate installation. Agents are defined as .agent.md files in your repository's .github/agents/ folder. When you fork accessibility-agents, the agents come with it. You need GitHub Copilot (paid subscription) for agents to function.

-

Q: Can I use agents without understanding GitHub first?

-

A: The agents automate skills you learn in the workshop. Using them without understanding what they do is like using a calculator without understanding math - you cannot tell when it is wrong. That is why Day 1 comes first.

-

Q: How do I personalize agents for my own repositories?

-

A: Copy .github/agents/preferences.example.md to .github/agents/preferences.md and edit it with your GitHub username, preferred repositories, and output format preferences.

-

Q: Can I create my own agents?

-

A: Yes. Create a new .agent.md file in .github/agents/ following the existing file format. The file is plain Markdown with YAML frontmatter. See Appendix V (Accessibility Agents Reference).

-

Issue Templates

-

Q: What is an issue template and why should I care?

-

A: Templates guide people to provide the right information when filing issues. Well-structured templates save time for maintainers and help screen reader users navigate the form. See Chapter 15 (Issue Templates).

-

Q: My template does not show up when I click "New Issue." What is wrong?

-

A: Check:

-
    -
  1. The file is in .github/ISSUE_TEMPLATE/your-template.yml (not .md, not in the wrong folder)
    2. -
  2. The YAML syntax is valid (check at https://www.yamllint.com/)
    3. -
  3. The file is committed to the main branch
    4. -
  4. Try a hard browser refresh: Ctrl+Shift+R
    5. -
-

See TROUBLESHOOTING.md → "Template not showing in GitHub" for full diagnostics.

-

Q: What is YAML and why is it used for templates?

-

A: YAML is a simple format for writing structured data - easier to read than JSON or XML. GitHub uses it for issue form templates because it is human-readable and supports validation. You do not need to be an expert - Chapter 15 teaches you everything you need.

-

Q: Can I use the @template-builder agent to create templates?

-

A: Yes. The @template-builder agent in Copilot Chat walks you through creating templates interactively. It asks questions and generates the YAML for you. See Chapter 16 (Accessibility Agents).

-

Code Review

-

Q: What makes code review "accessible"?

-

A: Accessible code review means:

-
    -
  • Using keyboard shortcuts instead of mouse
    • -
  • Testing that diffs are screen reader navigable
    • -
  • Writing descriptive review comments (not just "LGTM")
    • -
  • Using the Accessible Diff Viewer (F7) in VS Code
    • -
  • See Chapter 14 (Accessible Code Review)
    • -
-

Q: How do I read a diff with a screen reader?

-

A: Two approaches:

-
    -
  1. On GitHub: Navigate to the Files Changed tab. Use arrow keys to move through lines. Added lines start with +, removed lines start with -.
    2. -
  2. In VS Code: Open the changed file in the Source Control panel, then press F7 to open the Accessible Diff Viewer. It reads changes sequentially and announces whether each change is an addition, deletion, or modification.
    3. -
-

Q: What is a good review comment?

-

A: A useful comment includes:

-
    -
  1. What you noticed
    2. -
  2. Why it matters
    3. -
  3. A suggestion (optional but helpful)
    4. -
-

Example: "The alt attribute on this image is empty. Screen readers will skip it entirely, which means blind users miss the chart. A description like 'Bar chart showing monthly downloads' would help."

-

Q: What does "LGTM" mean?

-

A: "Looks Good To Me" - a common shorthand for approval. However, a more descriptive comment explaining what you checked is more helpful, especially for the PR author's learning.

-

Q: What is the difference between "Comment," "Approve," and "Request Changes"?

-

A:

-
    -
  • Comment: General feedback, no explicit approval or rejection
    • -
  • Approve: You are satisfied the changes are ready to merge
    • -
  • Request Changes: You have identified issues that must be fixed before merging
    • -
-

The Learning Room

-

Q: What is the Learning Room?

-

A: A shared practice repository (learning-room/) where participants make their first real contributions during the workshop. It contains intentionally incomplete documents and accessibility issues for you to find and fix. See Chapter 3 (The Learning Room).

-

Q: What are the challenges?

-

A: Two types:

-
    -
  • 12 individual challenges - Progressive tasks you complete on your own (find broken links, fix headings, add alt text, etc.)
    • -
  • 7 group challenges - Collaborative exercises requiring coordination with other participants
    • -
-

Details in learning-room/docs/CHALLENGES.md and learning-room/docs/GROUP_CHALLENGES.md.

-

Q: How does the bot feedback work?

-

A: When you open a PR in the Learning Room, an automated bot reviews your changes within about 30 seconds. It checks for broken links, heading hierarchy, image descriptions, link text quality, and formatting. Every issue includes an explanation of why it matters and how to fix it.

-

Q: Can I practice in the Learning Room on my own?

-

A: Yes. Fork the repository, and the individual challenges work in your fork. Group challenges are designed for a live session but you can still practice the technical steps solo.

-

Workshop Logistics

-

Q: What if I fall behind the group?

-

A: This is completely normal. Each chapter is self-contained - you can continue at your own pace. The facilitator will provide catch-up guidance during breaks. The GitHub Skills modules (Day 1) are yours permanently - Mona is always waiting for you.

-

Q: Can I take breaks?

-

A: Yes. Screen reader listening is cognitively demanding work. The schedule includes regular breaks. Take additional breaks whenever you need them.

-

Q: Do I need to attend both days?

-

A: Day 1 is self-contained - you can use GitHub confidently after completing it alone. Day 2 builds on Day 1 and requires its skills. You cannot meaningfully attend Day 2 without Day 1.

-

Q: Can I work ahead?

-

A: Yes. The chapters are designed to be read sequentially, but nothing stops you from reading ahead. Just be aware that some Day 2 exercises depend on having completed Day 1 activities.

-

Q: I missed a session. Can I catch up?

-

A: Yes. All materials are in the repository and can be read at any time. The GitHub Skills modules are available indefinitely. The only thing you miss is live interaction and facilitated group exercises.

-

Q: What if I have accessibility needs not covered by the workshop setup?

-

A: Contact the facilitator. This workshop is designed for flexibility - if you need a specific accommodation (higher contrast, different font size, alternative input method, longer break time), ask.

-

After the Workshop

-

Q: Can I contribute to this curriculum?

-

A: Yes. See CONTRIBUTING.md for how to submit improvements, suggest new topics, or fix issues.

-

Q: I want to share this guide with my team. Can I?

-

A: Yes. The curriculum is licensed under CC BY 4.0 - you are free to share and adapt with attribution required.

-

Q: Can I modify the guide for my organization?

-

A: Yes. Fork this repository and customize it for your needs. Attribution to the original is required under CC BY 4.0.

-

Q: How do I keep my fork up to date?

-

A:

-
git remote add upstream https://github.com/community-access/learning-room.git
-git fetch upstream
-git checkout main
-git merge upstream/main
-git push origin main
-

Then rebuild the HTML: npm run build:html

-

Q: Where can I continue learning after this workshop?

-

A:

- -

Q: How do I download all the workshop materials for offline reading?

-

A: See Appendix Y (Accessing Workshop Materials) for complete instructions - clone via Git, download as ZIP, or read individual files on GitHub.com.

-

Concepts and Terminology

-

Q: What is the difference between a fork and a branch?

-

A:

-
    -
  • Fork = Your complete separate copy of a repository (on GitHub)
    • -
  • Branch = A version of the code within a repository
    • -
  • Use fork to: Contribute to someone else's open-source project
    • -
  • Use branch to: Work on features in your own repository
    • -
-

See Chapter 1 for detailed explanation.

-

Q: What is Git? How is it different from GitHub?

-

A:

-
    -
  • Git = A version control system that runs on your computer. It tracks changes to files over time.
    • -
  • GitHub = A website and service that hosts Git repositories online and adds collaboration features (issues, PRs, Actions, etc.)
    • -
  • Git works without GitHub. GitHub requires Git.
    • -
-

Q: What is a repository?

-

A: A project folder tracked by Git. It contains your files plus the entire history of changes. On GitHub, a repository also includes issues, PRs, settings, and community features.

-

Q: What is a commit?

-

A: A snapshot of your changes at a point in time. Each commit has a message describing what changed and why. Think of it as a save point with a note.

-

Q: What is main (or master)?

-

A: The default branch of a repository - the official, current version of the project. New branches are created from main, and finished work is merged back into main. Older repositories may use master instead.

-

Q: What is a diff?

-

A: A comparison showing what changed between two versions of a file. Added lines are marked with + (green), removed lines with - (red), and unchanged lines provide context. Screen readers announce additions and deletions.

-

Q: What is CI/CD?

-

A: Continuous Integration / Continuous Deployment - automated systems that run tests, build code, and deploy software when you push changes. On GitHub, this is done through GitHub Actions. See Appendix Q (GitHub Actions).

-

Q: What is WCAG?

-

A: Web Content Accessibility Guidelines - the international standard for web accessibility. WCAG 2.2 defines criteria in three levels: A (minimum), AA (recommended), and AAA (highest). See Appendix C (Accessibility Standards Reference).

-

Q: What is ARIA?

-

A: Accessible Rich Internet Applications - A set of HTML attributes that add accessibility information to web elements. For example, aria-label provides a text description for screen readers, and role identifies the purpose of an element (button, navigation, main content, etc.).

-

Still Stuck?

-

This FAQ does not cover your question? Try these resources in order:

-
    -
  1. QUICK_REFERENCE.md - Commands, keyboard shortcuts, file locations
    2. -
  2. TROUBLESHOOTING.md - Common problems and step-by-step solutions
    3. -
  3. Appendix A (Glossary) - Term definitions
    4. -
  4. Appendix B (Screen Reader Cheat Sheet) - NVDA, JAWS, VoiceOver keyboard commands
    5. -
  5. Appendix U (Resources) - External documentation and links
    6. -
  6. GitHub Issues - Search existing issues or open a new one
    7. -
  7. FACILITATOR.md - If you are leading a workshop
    8. -
-

Last updated: February 2026
Have more questions? Open an issue or discussion on GitHub!

- -
- - - \ No newline at end of file diff --git a/html/GITHUB_PROPOSAL.html b/html/GITHUB_PROPOSAL.html deleted file mode 100644 index b8cafe2..0000000 --- a/html/GITHUB_PROPOSAL.html +++ /dev/null @@ -1,856 +0,0 @@ - - - - - - - GitHub Learning Curriculum - GIT Going with GitHub - - - - - - - - -
-

GitHub Learning Curriculum

-

Executive Summary & Proposal to GitHub

-

Project Overview

-

Title: Comprehensive, Accessible GitHub Workshop Curriculum with AI Agent Integration
Scope: 17-chapter structured learning path + interactive AI agents + accessibility-first design
Audience: Developers, open-source contributors, maintainers, and facilitators
Status: Complete curriculum ready for deployment
Note: 2 additional agenda files (Day 1 & Day 2) provided for workshop facilitators (not part of learner sequence)

-

Problem Statement

-

Current Gap

-

GitHub is powerful but intimidating for newcomers. Standard onboarding approaches:

-
    -
  • Assume prior Git/collaboration knowledge
    • -
  • Don't explicitly teach soft skills (communication, inclusive review)
    • -
  • Often lack accessibility guidance
    • -
  • Don't leverage AI to amplify human expertise
    • -
-

Many organizations need structured, repeatable, accessible training that:

-
    -
  1. Teaches Git and GitHub concepts sequentially
    2. -
  2. Emphasizes inclusive collaboration practices
    3. -
  3. Includes accessibility requirements from day one
    4. -
  4. Integrates modern AI tools (GitHub Copilot agents)
    5. -
  5. Provides hands-on, guided practice with clear success criteria
    6. -
-

Impact

-
    -
  • New developers struggle with PR review culture and GitHub workflows
    • -
  • Maintainers lack templates and automation to scale contributions
    • -
  • Accessibility advocates have no GitHub-specific guidance
    • -
  • Facilitators must recreate training materials from scratch
    • -
-

Solution: Complete Learning Curriculum

-

Architecture

-

Three-Part Modular Design:

-

Part 1: Foundation (Day 1 - 7.5 hours)

-

Chapters 0-10 teach GitHub essentials and collaborative workflows.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ChapterDurationFocusHands-On
030 minEnvironment setupInstall tools, verify Git
11 hrGitHub conceptsWeb structure, terminology
245 minNavigationExplore real repositories
330 minThe Learning RoomPractice repository orientation
41 hrIssuesCreate, comment, label (2 exercises)
545 minVS Code AccessibilityEditor setup, accessibility features
61 hrPull requestsSubmit, review, merge (2 exercises)
71 hrMerge conflictsResolve real conflicts
830 minCulture & etiquetteRespectful collaboration
945 minOrganization toolsLabels, milestones, projects
1030 minNotificationsManage subscriptions
-

Outcome: Users comfortable with GitHub fundamentals; ready for advanced topics and automation (Day 2).

-

Note: Day 1 and Day 2 agenda files provided separately for facilitators (not counted in learner time).

-

Part 2: VS Code & Development Environment (Day 2 Foundation - 2.5 hours)

-

Chapters 11-13 introduce Git integration, GitHub PR tooling, and GitHub Copilot.

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
ChapterDurationFocusNew Concepts
1145 minGit source controlVS Code Git integration
1230 minGitHub PR extensionReview PRs from VS Code
1345 minGitHub CopilotAI-powered code assistance
-

Outcome: Users comfortable with development environment; ready for advanced workflows.

-

Part 3: Accessibility & Advanced Workflows (Day 2 Advanced - 4 hours)

-

Chapters 14-16 teach accessible code review, issue templates, and AI agent automation.

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
ChapterDurationFocusNew Concepts
141 hr + 3 exercisesAccessible code reviewKeyboard-only, screen readers, diff navigation (NVDA/JAWS/VoiceOver)
151.5 hrs + 4 exercisesIssue templatesYAML, form fields, WCAG compliance, template design
161.5 hrs + 3 exercisesAccessibility Agents55 AI agents across 3 teams, 54+ slash commands, Template Builder wizard
-

AI Agent Integration:

-
    -
  • 55 Agents across 3 Teams: Accessibility (26), GitHub Workflow (12), Developer Tools (6) - automate auditing, issue triage, PR review, analytics, and more
    • -
  • 54+ Slash Commands: Targeted invocations for specific workflows
    • -
  • Template Builder: Interactive wizard for guided template creation
    • -
-

Outcome: Teams can design accessible workflows and automate GitHub processes with confidence.

-

Curriculum Highlights

-

1. Accessibility-First Design

-
    -
  • Screen reader integration: Every exercise tested with NVDA, JAWS, VoiceOver
    • -
  • Keyboard-only workflows: Users never require a mouse
    • -
  • Plain language: Glossary for all terminology
    • -
  • Appendix B: Screen Reader Cheatsheet (NVDA/JAWS/VoiceOver commands)
    • -
-

Why: ~15% of population has disabilities; GitHub should be usable by all.

-

2. Hands-On Exercises

-
    -
  • 10+ guided exercises across Chapters 4-6, 11-16 (all hands-on chapters)
    • -
  • Step-by-step walkthroughs: 300-900 lines per exercise
    • -
  • **"What you should see":" Checkpoint validation at each step
    • -
  • Troubleshooting: "If not, try this" guidance embedded in every exercise
    • -
-

Note on Chapters 5 and 11-13: These VS Code chapters teach through integrated practice rather than standalone exercises - users configure tools, explore features, and practice workflows as they learn. Formal numbered exercises resume at Chapter 14.

-

Example: Exercise A (Ch 15) walks users through:

-
    -
  1. Navigating to template selector
    2. -
  2. Reading template instructions
    3. -
  3. Filling form fields accessibly
    4. -
  4. Previewing submission
    5. -
  5. Submitting issue
    6. -
  6. Verifying success
    7. -
  7. Reflecting on accessibility
    8. -
-

Why: Users gain confidence; zero ambiguity on success criteria.

-

All 10 Exercises at a Glance

-

Comprehensive breakdown of every hands-on exercise across the curriculum:

-

Day 1 Exercises (Chapters 4-6):

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
#ChapterExerciseFocusStepsKey Skills
1Ch 4Create & Comment on IssuesIssue workflow7Issue creation, navigation, commenting
2Ch 4Label & TriageIssue organization6Applying labels, milestone assignment
3Ch 7Submit PRBranching & PR creation8Branch creation, commit, PR opening
4Ch 7Review & FeedbackCode review & response7Reading diffs, leaving comments, responding
-

Day 2 Foundation (Chapters 11-13): No formal exercises - integrated hands-on practice throughout (Git workflows, PR extension, Copilot basics)

-

Day 2 Advanced Exercises (Chapters 14-16):

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
#ChapterExerciseFocusStepsKey Skills
5Ch 14Accessible Code Review (Web)Screen reader + browser9NVDA/JAWS/VoiceOver commands, diff navigation
6Ch 14Accessible Code Review (VS Code)Keyboard-only diff viewing9F7 Accessible Diff Viewer, keyboard navigation
7Ch 14Accessible Code Review (Comments)Feedback cycle6Writing accessible comments, reflection
8Ch 15Design Template (Web UI)GitHub interface8Template selection, form filling, submission
9Ch 15Design Template (Local)Git + editor workflow10Clone, YAML editing, testing, merge
10Ch 15Create Template PRFull workflow7PR creation, feedback integration, merging
-

Advanced Option - Chapter 15, Exercise D:

-
    -
  • Custom Template Design (8 parts, 500+ lines)
    • -
  • Choose real project → Identify patterns → Design fields → Write descriptions → Test locally → Deploy → Reflect
    • -
  • Full-scope exercise for practitioners building organizational templates
    • -
-

Chapter 16 Exercises (Agent Integration - 3 additional exercises):

-
    -
  • Exercise 1: Generate Template with @template-builder (8 steps) - Interactive Ask Questions workflow
    • -
  • Exercise 2: Extend Agent Capabilities (6 steps) - Edit agent, add security workflow variant
    • -
  • Exercise 3: Iterative Refinement with Agent (4 steps) - Generate → Modify → Refine → Observe pattern
    • -
-

Exercise Structure (All 10+):

-
    -
  • 300-900 lines per exercise
    • -
  • "What you should see" checkpoints after each step
    • -
  • "If this happens, try..." troubleshooting sections
    • -
  • Screen reader commands embedded (NVDA/JAWS/VoiceOver specific)
    • -
  • Reflection questions at completion
    • -
  • Copy-paste code templates where applicable
    • -
-

Estimated Times:

-
    -
  • Basic exercises (Ch 4-5): 30-45 min each
    • -
  • Accessibility exercises (Ch 14): 1 hour each
    • -
  • Template exercises (Ch 15): 1-1.5 hours each
    • -
  • Agent exercises (Ch 16): 30-60 min each
    • -
-

3. AI Agent Integration

-

The Template Builder Agent (NEW!) exemplifies the curriculum's approach:

-
Name: @template-builder
-Feature: Interactive Ask Questions wizard
-Use Case: Guided template creation for non-technical users
-Workflow:
-  1. Ask user project type (Web app? Library? Documentation?)
-  2. Ask which fields are essential (5-field or 10-field template?)
-  3. Ask about accessibility needs (WCAG AA compliance? Screen reader tested?)
-  4. Generate YAML template with tested structure
-  5. User copy-pastes into GitHub repository
-Result: 5-minute template creation vs. 30 minutes manual YAML editing
-

Why: Amplifies user skill; automates the repetitive parts.

-

4. Supporting Documentation

-
    -
  • QUICK_REFERENCE.md (1-page cheat sheet for commands, shortcuts, file locations)
    • -
  • TROUBLESHOOTING.md (20+ common problems with solutions)
    • -
  • appendix-u-resources.md (links to WCAG, screen readers, documentation)
    • -
  • FAQ.md (50+ questions organized by role and topic)
    • -
  • PROGRESS_TRACKER.md (printable checklist for learners)
    • -
  • ACCESSIBILITY_TESTING.md (checklist for testing templates & workflows)
    • -
-

Why: Users have context-specific help at their fingertips; facilitators have reference guides.

-

Pedagogical Approach

-

Three Core Principles

-

1. Skill First, Agent Second

-

Agents amplify human expertise; they don't replace learning.

-

Example:

-
    -
  • Day 1: Learn to review PRs manually (read diffs, leave comments)
    • -
  • Day 2: Use @pr-review agent to speed up that process
    • -
-

Result: Users understand when agent output is correct or needs editing.

-

2. Manual → Automated → Mastered

-

Every exercise follows progression:

-
Manual Skill (User does 100% by hand)
-    ↓
-With Agent (User does 50%, agent does 50%)
-    ↓
-Mastered (User reviews agent work, makes final call)
-

Example (Ch 15 Progress):

-
    -
  1. Exercise A: Design template manually (GitHub web UI)
    2. -
  2. Exercise B: Clone, edit, test template locally (Git workflow)
    3. -
  3. Exercise D: Critique team's template (human judgment)
    4. -
  4. Ch 16 - Exercise 1: Use @template-builder to generate template in 5 min
    5. -
  5. Ch 16 - Exercise 2: Extend agent with new template variant
    6. -
  6. Ch 16 - Exercise 3: Guide agent iteratively (You: iterate; Agent: generates)
    7. -
-

3. Accessible by Default, Not Afterthought

-

Accessibility is woven into every chapter.

-
    -
  • Every issue template includes WCAG label suggestions
    • -
  • Every code review teaches keyboard-only navigation
    • -
  • Every agent prompt mentions "confirm with accessibility advocate"
    • -
  • Every exercise includes screen reader instructions
    • -
-

Why: Builds inclusive habits from day one; not a retrofit.

-

Implementation & Deployment

-

Current Assets

-
    -
  • 34 Markdown documents (16 core chapters + 1 setup guide + 16 appendices A-Q + Accessibility Agents)
    • -
  • 6 AI agents fully defined and integrated
    • -
  • 10 hands-on exercises with detailed walkthroughs
    • -
  • 4 supporting guides (Quick Reference, Troubleshooting, Resources, FAQ)
    • -
  • 1 Executive Proposal (this document)
    • -
-

File Structure

-
.github/
-├── agents/
-│   ├── daily-briefing.agent.md
-│   ├── issue-tracker.agent.md
-│   ├── pr-review.agent.md
-│   ├── analytics.agent.md
-│   ├── insiders-a11y-tracker.agent.md
-│   └── template-builder.agent.md [NEW]
-├── ISSUE_TEMPLATE/
-│   └── [Accessible templates for contributors]
-└── workflows/
-    └── [Learning automation workflows]
-
-docs/
-├── 00-pre-workshop-setup.md (prerequisite - not counted in 16 chapters)
-├── 01-16-core-curriculum.md
-├── appendix-a-glossary.md
-├── appendix-b-screen-reader-cheatsheet.md
-├── appendix-c-keyboard-shortcuts.md
-├── appendix-c-accessibility-standards.md
-├── appendix-d-git-authentication.md
-├── appendix-e-github-flavored-markdown.md
-├── appendix-f-github-gists.md
-├── appendix-g-github-discussions.md
-├── appendix-h-releases-tags-insights.md
-├── appendix-i-github-projects.md
-├── appendix-j-advanced-search.md
-├── appendix-k-branch-protection-rulesets.md
-├── appendix-l-github-security-features.md
-├── appendix-m-vscode-accessibility-reference.md
-├── appendix-n-github-codespaces.md
-├── appendix-o-github-mobile.md
-├── appendix-p-github-pages.md
-├── appendix-q-github-actions-workflows.md
-├── appendix-r-github-profile-sponsors-wikis.md
-├── appendix-s-github-organizations-templates.md
-├── appendix-t-contributing-to-open-source.md
-└── appendix-u-resources.md
-
-Root/
-├── README.md [Main entry point]
-├── QUICK_REFERENCE.md [1-page cheat sheet]
-├── TROUBLESHOOTING.md [20+ common issues]
-├── appendix-u-resources.md [External links & documentation]
-├── FAQ.md [50+ questions by role]
-├── PROGRESS_TRACKER.md [Printable checklist]
-├── ACCESSIBILITY_TESTING.md [Testing checklist]
-├── CODE_OF_CONDUCT.md
-├── CONTRIBUTING.md
-└── FACILITATOR.md
-

Time Estimates for Learners

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
PathDurationAudienceOutcome
Essentials3-4 hrsBusy professionalsGitHub basics (no depth)
Core (Day 1)7.5 hrsContributorsReady for advanced topics
Full (Day 1+2)14+ hrsMaintainers/facilitatorsCan use and teach all tools
-

Time Estimates for Facilitators

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PreparationDurationActivities
Read full curriculum4-5 hrsUnderstand all chapters
Practice exercises3-4 hrsDo every exercise by hand
Customize for organization2-3 hrsAdd template examples, GitHub team
Total9-12 hrsReady to lead 2-day workshop
-

Success Criteria & Metrics

-

Learner Outcomes (Measurable)

-
    -
  • 100% of learners complete setup chapter successfully
    • -
  • 90%+ of learners complete at least one hands-on exercise
    • -
  • 80%+ of learners understand PR review process after Chapter 6
    • -
  • 70%+ of learners use agents in their workflows within 30 days
    • -
  • Satisfaction: Post-workshop survey shows 4.5+/5.0 average
    • -
-

Organizational Outcomes

-
    -
  • Reduced onboarding time for new developers (5 hrs down from 20+ hrs of ad-hoc training)
    • -
  • More consistent issue templates across team repositories
    • -
  • Increased PR review quality (more complete feedback from reviewers)
    • -
  • Higher accessibility compliance (templates and workflows built-in accessibility checks)
    • -
-

Accessibility Metrics

-
    -
  • 100% of templates tested with screen readers (NVDA, JAWS, VoiceOver)
    • -
  • WCAG 2.1 AA compliance verified for all guided workflows
    • -
  • Keyboard-only functionality tested on all exercises
    • -
  • Color contrast verified (4.5:1 minimum for all text)
    • -
- -

Phase 1: Finalize & Polish (1 week)

-
    -
  • Convert all Markdown to HTML for web deployment
    • -
  • Create landing page with learning path selector
    • -
  • Set up GitHub Pages or web server for hosting
    • -
  • Gather feedback from 5-10 pilot users
    • -
-

Phase 2: Pilot Program (2-3 weeks)

-
    -
  • Run 1-2 beta workshops with external participants
    • -
  • Collect feedback: What worked? What needs clarification?
    • -
  • Iterate based on learner feedback
    • -
  • Update exercises with common questions
    • -
-

Phase 3: Public Release (1 month)

-
    -
  • Launch curriculum publicly (GitHub Pages, blog announcement)
    • -
  • Promote in GitHub education channels, open-source communities
    • -
  • Establish feedback/issue tracking for curriculum improvements
    • -
  • Plan first live workshop (in-person or virtual)
    • -
-

Phase 4: Long-Term Maintenance (Ongoing)

-
    -
  • Monitor GitHub API/UI changes; update curriculum as needed
    • -
  • Collect learner feedback quarterly
    • -
  • Rotate facilitators for fresh perspectives
    • -
  • Expand to additional topics (GitHub Security, GitHub Actions deep dive, etc.)
    • -
-

Why GitHub Should Support This

-

1. Education Mission

-

GitHub's mission is to build the all-inclusive home for developers. This curriculum:

-
    -
  • Makes GitHub accessible to beginners
    • -
  • Emphasizes inclusive collaboration practices
    • -
  • Teaches AI-human partnership (not AI replacement)
    • -
-

2. Reduces Support Load

-

Well-trained users need fewer support interactions. Clear documentation:

-
    -
  • Answers 80% of onboarding questions
    • -
  • Teaches troubleshooting self-sufficiency
    • -
  • Reduces "how do I...?" issues
    • -
-

3. Amplifies GitHub Copilot Adoption

-

Users learn agents, they adopt Copilot subscriptions. The curriculum:

-
    -
  • Shows real-world use cases (not just theory)
    • -
  • Builds confidence in AI tools
    • -
  • Drives feature adoption (Templates, Actions, Copilot agents)
    • -
-

4. Models Accessibility Best Practices

-

By releasing a fully-accessible learning resource, GitHub demonstrates:

-
    -
  • Commitment to inclusive design
    • -
  • Leadership in accessible software documentation
    • -
  • Real accessibility implementation (not just compliance)
    • -
-

5. Community-Driven Success

-

Open curriculum invites contributions:

-
    -
  • Organizations customize for their workflows
    • -
  • Community suggests improvements and translations
    • -
  • Becomes standard reference (like "Pro Git" book)
    • -
-

Risks & Mitigations

- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
RiskImpactMitigation
GitHub API/UI changes break exercisesCurriculum becomes outdatedAssign quarterly review cycle; add GitHub Copilot agent to auto-detect changes
Exercises too long for some learnersDropoff rate increasesOffer "Express" version (50% content); provide time estimates per chapter
Accessibility issues found in testingUndermines credibilityEstablish accessibility testing committee; fix issues before public release
Low engagement/adoptionLow ROIPartner with GitHub team to promote; integrate with GitHub Skills program
-

Budget & Resources

-

Current Assets (Complete)

-
    -
  • 34 Markdown chapters (~110,000 words total)
      -
    • 16 core chapters (01-16)
      • -
    • 1 pre-workshop setup guide (00)
      • -
    • 16 appendices A-Q (no M) with reference material
        -
      • A: Glossary, B: Screen Reader Cheatsheet, C: Git Authentication
        • -
      • D: Gists, E: Advanced Features, F: VS Code A11y Reference
        • -
      • G: GitHub Actions, H: GitHub Projects, I: GitHub Discussions
        • -
      • J: Advanced Search, K: Releases & Tags, L: Repository Insights
        • -
      • N: GitHub Flavored Markdown [NEW], O: GitHub Security [NEW]
        • -
      • P: Branch Protection [NEW], Q: Resources
        • -
      -
      • -
    • Accessibility Agents (Chapter 16 + 54+ slash commands)
      • -
    -
    • -
  • 55 AI agents across 3 teams (fully documented, ready to use)
      -
    • Integrated throughout curriculum
      • -
    • 54+ slash commands total
      • -
    -
    • -
  • 10+ detailed exercises (300-900 lines each, hand-holding walkthroughs)
      -
    • 2 exercises in Chapter 4 (Issues)
      • -
    • 2 exercises in Chapter 6 (Pull Requests)
      • -
    • 3 exercises in Chapter 14 (Accessible Code Review)
      • -
    • 4 exercises in Chapter 15 (Issue Templates)
      • -
    • 3 exercises in Chapter 16 (Accessibility Agents)
      • -
    • All include checkpoints, screen reader guidance, troubleshooting
      • -
    -
    • -
  • 7 supporting guides (HTML + Markdown formats)
      -
    • QUICK_REFERENCE.md - 1-page cheat sheet
      • -
    • TROUBLESHOOTING.md - 20+ solutions
      • -
    • appendix-u-resources.md - comprehensive manifest
      • -
    • FAQ.md - 50+ questions
      • -
    • PROGRESS_TRACKER.md - printable checklist
      • -
    • ACCESSIBILITY_TESTING.md - testing workflow
      • -
    • GITHUB_PROPOSAL.md - this document
      • -
    -
    • -
  • Complete HTML conversion (545KB web-ready files)
      -
    • All guides converted to HTML
      • -
    • All advanced chapters converted to HTML
      • -
    • Ready for GitHub Pages or web hosting
      • -
    -
    • -
  • Full accessibility compliance
      -
    • WCAG 2.1 AA design
      • -
    • Tested with NVDA, JAWS, VoiceOver
      • -
    • Keyboard-only workflows
      • -
    • Plain language glossary
      • -
    -
    • -
-

Time Commitment (GitHub Internal)

-
    -
  • Product Manager: 5 hrs/week for 4 weeks (strategy, GitHub Features integration)
    • -
  • Engineer: 2-3 hrs/week for ongoing agent updates
    • -
  • Accessibility Lead: 2-3 hrs/week for testing & validation
    • -
-

Ongoing (Long-term)

-
    -
  • Quarterly maintenance: 4 hrs/month (keep curriculum current)
    • -
  • Community support: 3 hrs/week (respond to feedback)
    • -
  • Annual curriculum review: 20 hrs (comprehensive update)
    • -
-

Alignment with GitHub Strategic Goals

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
GitHub GoalCurriculum SupportsHow
Grow developer communityOnboarding for millions of new usersClear, repeatable learning path
Increase Copilot adoptionShow real-world agent use cases55 agents + 54+ commands integrated throughout
Lead in accessibilityModel best practicesWCAG 2.1 AA+, screen reader tested, keyboard-absolute
Reduce support burdenEmpower self-service learningFAQ, Troubleshooting, Quick Reference guides
Build partnershipsEcosystem integrationWorks with VS Code, GitHub CLI, Copilot, Actions
-

Call to Action

-

This curriculum is ready for deployment. The required next step is:

-
    -
  1. Decide: Will GitHub officially support this curriculum? (Yes/No/Consider)
    2. -
  2. Assign: Who will own Phase 1 finalization & Phase 2 pilot?
    3. -
  3. Timeline: Target launch date (Recommend: Q2 2026)
    4. -
-

Success Metric

-

If this curriculum launches: We expect 10,000+ learners in year one, 50,000+ by year two.

-

Appendices

-

A. Curriculum Overview

-

See README.md for full chapter list and quick links.

-

B. Quick Stats

-
    -
  • Total content: ~110,000 words (chapters + appendices + guides + exercises)
    • -
  • Exercises: 10+ (300-900 lines each, hand-holding walkthroughs)
      -
    • Ch 4: 2 exercises (issues)
      • -
    • Ch 6: 2 exercises (pull requests)
      • -
    • Ch 14: 3 exercises (accessible code review)
      • -
    • Ch 15: 4 exercises (issue templates, including optional custom template)
      • -
    • Ch 16: 3 exercises (agent integration)
      • -
    -
    • -
  • Appendices: 16 (A-Q, no M) - security, GFM, branch protection, resources, and more added February 2026
    • -
  • Agents: 6 (ready to use)
      -
    • @daily-briefing, @issue-tracker, @pr-review, @analytics, @insiders-a11y-tracker, @template-builder
      • -
    -
    • -
  • Slash commands: 28 (documented & organized by use case)
    • -
  • Screen readers tested: NVDA, JAWS, VoiceOver
    • -
  • WCAG compliance: 2.1 AA with accessibility-first design
    • -
  • Exercise structure: Each includes checkpoints, troubleshooting, screen reader guidance, reflection questions
    • -
  • Target learner hours: 7.5 (Day 1) + 6.5 (Day 2) = ~14 hours minimum
    • -
  • Facilitator prep: 9-12 hours (practice all exercises, read all chapters)
    • -
  • HTML conversion: 11 new files, 545KB web-ready content
    • -
-

C. Contact & Questions

-
    -
  • Curriculum Owner: [Your Name/GitHub Team]
    • -
  • Accessibility Lead: [A11y Champion]
    • -
  • GitHub Contact: [Product Manager]
    • -
-

Signature & Approval

-

Prepared by: GitHub Learning Curriculum Team
Date: February 2026
Status: Ready for Phase 1 Finalization

-

This proposal demonstrates a complete, accessible, AI-integrated learning system designed to onboard users into GitHub, emphasize inclusive practices, and amplify human expertise with AI agents. We're ready to launch.

-

Questions? Comments? Open an issue on GitHub or contact the curriculum team.

- -
- - - \ No newline at end of file diff --git a/html/GO-LIVE-QA-GUIDE.html b/html/GO-LIVE-QA-GUIDE.html new file mode 100644 index 0000000..e9bc5c8 --- /dev/null +++ b/html/GO-LIVE-QA-GUIDE.html @@ -0,0 +1,458 @@ + + + + + + + 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.
    • +
  • 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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AreaSource document
Classroom deploymentclassroom/README.md
Classroom copy-paste setup packadmin/classroom/README.md
Human challenge walkthroughclassroom/HUMAN_TEST_MATRIX.md
Facilitator operationsadmin/FACILITATOR_OPERATIONS.md
Facilitator guideadmin/FACILITATOR_GUIDE.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/PODCASTS.html b/html/PODCASTS.html deleted file mode 100644 index 4580d2d..0000000 --- a/html/PODCASTS.html +++ /dev/null @@ -1,4578 +0,0 @@ - - - - - - - Podcasts - GIT Going with GitHub - - - - - - - - -
-

Podcasts

-

Git Going with GitHub - Audio Series

-

Listen to companion audio episodes for every chapter and appendix in this workshop. Each episode is a conversational overview between hosts Alex and Jamie that previews or reviews the key concepts - perfect for learning on the go or reducing screen reader fatigue. 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 preview the concepts. You will know what to expect before diving into the exercises.
    • -
  • After a chapter: Listen to reinforce what you learned 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

- - -

Download Episode 0 (MP3)

-
-Read Transcript - Episode 0: Welcome to Git Going with GitHub - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode zero, titled Welcome to Gitt Going with GitHub. I am your host, Alex, and I am thrilled to be starting this journey with you. Whether you are a seasoned programmer who is just now moving over to GitHub, or you are completely new to version control, this audio series is designed to be your companion. We are going to explore open source collaboration using GitHub, Visual Studio Code, and GitHub Copilot, all with a strict focus on screen reader and keyboard-only navigation.

-

Jamie: And I am Jamie! I am so excited to be here. I will be learning right alongside you, asking the questions, and probably sharing a few embarrassing stories from my own learning journey. Because let me tell you, I learned GitHub just two years ago, and I remember exactly how overwhelming it felt. When I first heard people throwing around words like clone, fork, and branch, I thought we were doing some weird mix of agriculture and science fiction.

-

Alex: That is a perfect description of how it sounds at first. And that is exactly why we are doing this. Before we dive into the deep end, we want to give you a map of the territory. This episode is an overview of the entire two-day workshop. We are going to talk about what open source actually means, how this course is structured, the philosophy behind how we teach, and we will preview some of the core vocabulary you will be using every single day.

-

Jamie: But before we get into all of that, a quick public service announcement. If you are listening to this and you have not yet completed Chapter 0, which is the Pre-Workshop Setup, you will want to navigate to that chapter and complete it before Day 1 officially begins. It takes about thirty minutes. It walks you through creating your GitHub account, installing Git, setting up VS Code, and configuring your screen reader specifically for GitHub.

-

Alex: Exactly. Getting your environment set up correctly is half the battle. Once your screen reader is optimized for the web interface, everything else flows much more smoothly. So, let us start with the big picture. The entire goal of this workshop is built around one single idea. By the end of these two days, you will make real contributions to a real open source project. Not a simulated sandbox. Not pretend. Real open source.

-

Jamie: Which brings up a great question. For someone entirely new to this space, what exactly does open source mean, and why does it matter so much?

-

Alex: Open source refers to software where the original source code is made freely available. Anyone can navigate to the code, read it, modify it, and distribute it. But more importantly, open source is a collaborative community. It is a way of building software where thousands of people from all over the world work together to solve problems, rather than one closed-off team in a single company.

-

Jamie: I always like to think of open source as a massive community potluck dinner. Someone brings the main dish, which is the core software. But then someone else says, hey, this needs salt, and they add a new feature. Someone else brings dessert, which might be a documentation update. And someone else fixes the wobbly table, which is a bug fix. Anyone is allowed to walk into the room, taste the food, and contribute their own recipe to make the whole meal better for everyone.

-

Alex: I love that analogy. And what makes GitHub so powerful is that it provides the kitchen, the tables, and the recipe cards for that potluck. GitHub is the platform where millions of these open source projects live. It matters because much of the modern internet, including the tools we use for accessibility, runs on open source software. When you learn how to contribute, you get a voice in how the software you use every day is built.

-

Jamie: Okay, so we are going to be cooking at the open source potluck. How exactly are we going to learn all of this in just two days?

-

Alex: We divide the workshop into two distinct phases. Day 1 is all about GitHub Foundations in the browser. You will learn the GitHub web interface using only your keyboard and your screen reader. We will not touch a command line. We will not open a desktop application. You will learn how to navigate projects, find issues, propose changes, and review other people's work, entirely through the GitHub website.

-

Jamie: And I really appreciate this approach. When I started two years ago, I tried to learn the command line, the website, and the code editor all on the same day. It was a disaster. I did not know which program was throwing an error, or what the error even meant.

-

Alex: That is incredibly common, and it is the reason for our core learning philosophy in this workshop. We believe you must learn the manual skill first, before you introduce automation. If you try to use advanced tools before you understand what they are doing behind the scenes, you will get lost the moment something goes wrong. By spending all of Day 1 in the browser, you build a mental model of how GitHub is structured. You learn the concepts deeply.

-

Jamie: So Day 1 is building the foundation. What happens on Day 2?

-

Alex: Day 2 is when we move to the desktop. We transition into Visual Studio Code, which we often just call VS Code. This is a powerful, accessible code editor. Once we are in VS Code, we introduce GitHub Copilot, which is an artificial intelligence coding assistant, and we activate the Accessibility Agents ecosystem.

-

Jamie: Okay, hold on. Accessibility Agents? That sounds like something out of a spy movie. What are they?

-

Alex: They do sound a bit like secret agents. On Day 2, you will be introduced to a system of fifty-five accessibility agents working across three different teams. These agents are AI assistants configured specifically to help with accessibility tasks. For example, one team of agents acts as your daily briefing and issue tracking squad. They can summarize what happened in a project overnight so your screen reader does not have to read through fifty individual comments. Another team focuses on pull request reviews, helping you spot missing alternative text or improper heading structures in code before you submit it.

-

Jamie: Oh, that is clever! It is like having a team of expert accessibility consultants sitting in the room with you, ready to review your work or summarize long threads.

-

Alex: Exactly. But again, tying back to our philosophy, these agents only make sense if you already know what an issue or a pull request is. If you do not know how to manually review code, the agent's advice will not mean anything to you. That is why Day 2 is all about taking the manual skills you mastered on Day 1 and amplifying them with these fifty-five agents. By the end of Day 2, you will use these tools to ship a real contribution, and your name will be permanently recorded in the commit history of an open source project.

-

Jamie: Alex, you just used a few terms that I want to make sure we define, because I remember being so confused by them. We have an entire glossary in Appendix A, but can we do a high-level preview of the core vocabulary right now? Let us start with Repository.

-

Alex: Absolutely. A repository, or repo for short, is the container for an entire project. It holds all the files, the folders, the documentation, and, most importantly, the complete history of every change ever made.

-

Jamie: I remember someone telling me a repository is just a folder. But it is more than that, right?

-

Alex: It is much more than that. Think of a repository as a project folder that has a time machine built into it. Because it tracks every single modification, you can ask the repository to show you exactly what the project looked like last Tuesday at noon, or who added a specific line of code three years ago. It never forgets.

-

Jamie: Okay, next term. What is an Issue?

-

Alex: An issue is essentially a discussion item within a repository. If you find a bug, you open an issue to report it. If you want to request a new feature, you open an issue.

-

Jamie: So it is like a digital to-do list combined with a discussion forum. When I want to fix something, I navigate to the Issues section, find one that sounds interesting, and announce that I am going to work on it.

-

Alex: That is exactly right. Issues are the starting point for almost all open source work. Now, once you have done the work and fixed the bug, you need a way to give that fix back to the project. That brings us to our third core term, the Pull Request.

-

Jamie: Ah, the famous PR. I used to hear people say, just submit a PR, and I would nod and pretend I knew what they meant.

-

Alex: A pull request, or PR, is a formal proposal to combine your changes into the main project. And I love that name, because you are literally requesting that the maintainer pull your changes into their repository. You are saying, here is the work I did to fix that issue, please review it.

-

Jamie: My favorite analogy for a pull request is publishing a book. Imagine the repository is the official, published book. You cannot just grab a pen and write your own paragraph directly onto the printed pages for everyone in the world to see. Instead, you write your changes on a separate piece of paper, which is your draft. A pull request is you handing that piece of paper to the editor and saying, I think this paragraph makes the book better. What do you think?

-

Alex: That is a brilliant comparison. And the editor, who in our world is called the project maintainer, will read your draft. They might leave comments asking you to change a sentence, or fix a typo. This is the code review process. You update your draft based on their feedback. And finally, when the editor is happy with it, they perform the fourth core concept, the Merge.

-

Jamie: And a merge is when the editor takes your piece of paper, types it into the official manuscript, and publishes it for real.

-

Alex: Exactly. Merging is the act of combining your approved pull request into the main repository. Once it is merged, your code is officially part of the project. So, to recap the lifecycle. You find a problem in a Repository. You discuss it in an Issue. You propose a solution with a Pull Request. And the maintainer accepts it with a Merge.

-

Jamie: Okay, that sounds like a lot of steps. And if I am being honest, thinking about doing all of this, plus moving over to VS Code on Day 2, feels a little intimidating. Especially for folks who might be totally new to the command line, or new to using version control.

-

Alex: It does sound like a lot! But here is the thing. You have already done most of this on Day 1 in the browser. You already know the workflow. When we move to VS Code, it is the exact same workflow, just with VS Code handling the heavy lifting. We are going to take it one step at a time.

-

Jamie: And there is actually a really cool bridge between Day 1 and Day 2, right? The period key trick. I wish I had known that when I started.

-

Alex: It is one of my favorite features on GitHub. When you are on any repository page in your browser, if you simply press the period key on your keyboard, GitHub will instantly open a web-based version of VS Code right there in your browser tab. It is called GitHub dot dev. You do not have to install anything. It uses the exact same screen reader mode and keyboard shortcuts as the desktop version. It is the perfect stepping stone. You get to feel what a code editor is like, but you are still in the safety of your web browser.

-

Jamie: That is amazing. You can literally just press period, and suddenly you are in an accessible editor.

-

Alex: Yes. And we deliberately designed this workshop so that you are never thrown into the deep end without a life vest. Every single chapter builds on the one right before it. If you look at the course guide, you will notice we have structured the materials very specifically. There are chapters, and there are appendices.

-

Jamie: How should we be using those? Should I read the appendices before I start the exercises?

-

Alex: No, please do not try to read the appendices straight through! The chapters, numbered one through sixteen, are your main journey. They are designed to be read and practiced in order. The appendices, labeled with letters like Appendix A for the Glossary, or Appendix B for the Screen Reader Cheat Sheet, are purely reference materials. You keep them open in a separate tab or window. When you encounter a term you do not know, or you forget a screen reader command, you navigate to the appendix, find what you need, and then jump right back into the chapter.

-

Jamie: That takes a lot of pressure off. I do not have to memorize every single command before I start. I can just look them up as I go.

-

Alex: Exactly. Memorization is not the goal. Navigation and confidence are the goals. And to build that confidence, we have included twenty-four structured exercises throughout the curriculum.

-

Jamie: I love the exercises in this course. They are so bite-sized. Can you explain the pattern we use for them?

-

Alex: Every single exercise follows the exact same three-part pattern. First is the Try It section, which gives you clear, step-by-step instructions on what to do. Second is the You Are Done When section. This tells you the specific outcome you are looking for, so there is no guessing about whether you finished it correctly. Finally, there is the What Success Feels Like section. This is incredibly important for screen reader users. We describe exactly what you should hear, or where your focus should land, when the task is completed successfully.

-

Jamie: That is so helpful. I remember reading tutorials that would just say, click the button and you are done. And I would press enter on a button, and my screen reader would say nothing, and I had no idea if it actually worked. Knowing what success feels like is a game changer.

-

Alex: It really is. Let me give you an example. In Chapter One, there is an exercise called the Sixty Second Orientation. The Try It section asks you to navigate to a repository page, and press a sequence of keyboard shortcuts. Press the number 1 key, then the letter D, then the number 2 key, then the letter H. The You Are Done When section says you have successfully navigated between the main content, the repository details, and the file list. And the What Success Feels Like section explains the specific auditory feedback you will get from your screen reader as you jump between those landmarks. Every exercise takes between one and five minutes, and they are designed to be impossible to fail. They are just stepping stones.

-

Jamie: I am feeling so much better about this. But what if I do get stuck? What if my screen reader starts reading a wall of text, or I press the wrong shortcut and suddenly I am in a completely different view?

-

Alex: First, take a breath. Getting lost is a normal part of learning a complex interface. If you get stuck, we have a whole section in the guide called Getting Help. You can reference the Troubleshooting guide, which has step-by-step solutions to common screen reader focus issues. You can check the Quick Reference guide for shortcuts. And if you are truly stuck, you can actually open an issue in the workshop repository itself! You will describe what you tried, what happened, and what you expected to happen. It is a safe environment to practice asking for help the open source way.

-

Jamie: I really appreciate that. It normalizes getting stuck. When I first started, I thought getting an error meant I was bad at programming. Now I know that getting errors just means I am programming.

-

Alex: That is a fantastic way to look at it. Professional developers get errors all day long. The difference is just that they have built up the muscle memory of how to recover from them. And that is exactly the muscle memory we are going to build over these two days.

-

Jamie: So, as we wrap up this introductory episode, what are the biggest takeaways we should keep in mind before we jump into Chapter One?

-

Alex: I would say there are four main takeaways. Number one, remember our philosophy. We learn the manual skill first, then we automate it. Do not rush to the fancy tools until you understand the basic concepts. Number two, lean heavily on your reference materials. Keep the Glossary and the Screen Reader Cheat Sheet open in another tab. Number three, trust the exercise pattern. Focus on what success feels like, and take it one small step at a time.

-

Jamie: And number four, be kind to yourself. You are learning a new language, a new platform, and a new way of collaborating all at once. If it feels like a lot, that is because it is a lot. But you are going to do great.

-

Alex: Well said, Jamie. Up next in episode one, we are going to dive into Chapter One, Understanding GitHub's Web Structure. We will explore how GitHub organizes its pages, how to orient yourself using headings and landmarks, and how to make your screen reader glide through the interface. We will see you there!

-
- - -

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

- - -

Download Episode 1 (MP3)

-
-Read Transcript - Episode 1: Pre-Workshop Setup - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode one, titled Pre-Workshop Setup. I am your host, Alex, and I am here with my co-host, Jamie. In this audio series, we are going to guide you through learning GitHub, version control, and open source collaboration, specifically designed for developers who use screen readers or magnification.

-

Jamie: Hi everyone. I am so excited to be here. I actually took this exact workshop about two years ago. I remember exactly what it feels like to hear all these new terms thrown around and feel completely overwhelmed. So I am here to ask Alex all the questions that are probably running through your head right now.

-

Alex: And those questions are exactly what we want. Today, our goal is to get your computer, your browser, and your screen reader completely set up and verified before day one of the workshop even begins. We will cover creating a GitHub account, understanding the difference between Git and GitHub, installing Visual Studio Code, turning on some essential accessibility settings, and verifying that everything works.

-

Jamie: Okay, that sounds like a lot of steps.

-

Alex: It does! But here is the thing, you have already done most of this on Day One of any new job or project. It is the exact same workflow, just with some new tools. Once we get the foundation set up today, the rest of the workshop is just learning how to use it.

-

Alex: Let us start with the biggest question people usually have. What is the difference between Git and GitHub? They sound like the same thing, but they serve two very completely different purposes.

-

Jamie: This confused me so much when I started. I thought GitHub was just the company that made Git.

-

Alex: That is a very common misconception. Let us break it down. Git is a version control system. Version control is basically a system that records changes to a file or set of files over time so that you can recall specific versions later. Think of Git as a time machine for your code. It runs locally on your computer. When you make a mistake, Git allows you to roll back your files to exactly how they were yesterday, or last week.

-

Jamie: So if Git is the time machine running on my local laptop, what is GitHub?

-

Alex: GitHub is a hosting platform for collaboration. If Git is your personal camera saving photos to your hard drive, GitHub is the social media platform where you upload those albums so your friends can see them, comment on them, and add their own photos. GitHub lives on the web. It takes the code you manage locally with Git and gives you a place to share it, review it, and collaborate with developers all over the world.

-

Jamie: That makes sense. Git is the local engine, and GitHub is the collaborative cloud platform. Which means to participate in the workshop, we need an account on that cloud platform.

-

Alex: Exactly. Step one is creating your GitHub account. You will navigate your browser to github dot com slash signup. The signup process is a single-page form. It will ask for your email address, a password, and a username.

-

Jamie: Let us talk about usernames for a second. Your GitHub username is public. It is going to appear on every piece of code you submit, every comment you make, and every project you contribute to.

-

Alex: Right. Keep it professional. It represents you in the open source community. You can only use lowercase letters, numbers, and hyphens.

-

Jamie: And we should warn people about the human verification step. When I signed up, I got completely stuck here because the default puzzle is highly visual.

-

Alex: I am really glad you brought that up. GitHub uses a visual capture puzzle to verify you are human, which is a known accessibility barrier. When your screen reader reaches that part of the form, you need to navigate to the button labeled Try an audio challenge. Activate that button. You will hear a short audio clip of spoken words or digits, and you will type what you hear into the text field. If that audio challenge does not load or fails, do not panic. Reach out to the workshop organizers and they can manually help verify your account.

-

Alex: Once your account is created, GitHub will send a launch code to your email. You copy that code, paste it into the browser, and you are in. But before we do anything else, we need to talk about security. Specifically, Two-Factor Authentication, or as you will often hear it called, two F A.

-

Jamie: I know a lot of people groan when they hear two F A, but it is actually required by most major open source projects now, right?

-

Alex: It is. Two-factor authentication means that to sign into your account, you need two things. First, something you know, which is your password. Second, something you have, like a code from an app on your phone. Think of it like withdrawing money from an ATM. You need your physical debit card, which is the thing you have, and your PIN, which is the thing you know. If a hacker steals your password, they still cannot get into your GitHub account without that second factor.

-

Jamie: So how do we set this up accessibly?

-

Alex: You will navigate to your account settings, move to the Password and authentication section, and activate the Enable two-factor authentication button. GitHub gives you a few options. The most common is an authenticator app, like Microsoft Authenticator or Google Authenticator.

-

Jamie: For screen reader users, scanning a visual QR code on the screen with a phone camera can be really frustrating.

-

Alex: Yes it can. And that is why you should navigate past the QR code graphic and activate the link that says enter this text code. That will reveal a long text string called a setup key. You just copy that text string and paste it into the manual entry field of your authenticator app.

-

Jamie: Okay, so I have two F A turned on. I am secure. But wait, if I am using Git on my laptop terminal to send code up to GitHub, how does my terminal know my second factor code?

-

Alex: That is a brilliant question. When you have two F A enabled, you can no longer use your standard GitHub password on the command line. Git will reject it. Instead, you need to use either a Personal Access Token, or an S S H key.

-

Jamie: Okay, define those for me.

-

Alex: Let us start with a Personal Access Token, often called a PAT. A PAT is a long, randomly generated string of characters that GitHub creates for you. You use it exactly like a password when Git asks for one. But unlike your main password, a PAT can be scoped.

-

Jamie: Scaped meaning limited?

-

Alex: Exactly. Think of your main GitHub password like the master key to your house. It opens every door. A Personal Access Token is like a valet key you give to a parking attendant. It only starts the ignition, but it will not unlock the glove box or the trunk. You can create a PAT that only has permission to read and write code repositories, but cannot delete your account or change your billing settings. And you can set it to automatically expire after thirty days.

-

Jamie: That is really smart. And what about the other option you mentioned, S S H keys?

-

Alex: S S H stands for Secure Shell. An S S H key is actually a pair of files generated on your computer. One is private, which stays securely on your hard drive, and one is public, which you upload to GitHub. Once they are linked, your computer and GitHub recognize each other automatically. No passwords or tokens to type ever again.

-

Jamie: I use S S H keys now and I love them, but I will say, generating them in the terminal was a bit intimidating on my first day.

-

Alex: Which is exactly why, for this workshop, we recommend starting with a Personal Access Token. It is entirely web-based, highly accessible to set up in the browser, and you just paste it into your credential manager once.

-

Alex: Now that we are authenticated, we need to adjust a few critical settings in the GitHub web interface. There is a dedicated Accessibility Settings page. You can reach it by opening the user navigation menu in the top right corner, selecting Settings, and then navigating to Accessibility in the left sidebar.

-

Jamie: If listeners only take one thing away from this episode, let it be this next setting. Please, for your own sanity, disable Hovercards.

-

Alex: I completely agree. A hovercard is a small pop-up window that appears when you move focus to a user's name or a repository link. It is meant to provide quick context. But for screen reader users, it is incredibly disruptive.

-

Jamie: It is the worst. When I had it turned on, every single time I tabbed past a link, my screen reader would start reading a massive paragraph of metadata, and then announce the keyboard shortcut to open the card. It was like having a tour guide who interrupts you every time you walk past a painting to read you the entire Wikipedia article about the artist, while you are just trying to find the restroom.

-

Alex: That is the perfect analogy. So, on the Accessibility Settings page, navigate to the checkbox labeled Hovercards or Link Previews, and uncheck it. It saves automatically. While you are on that page, we also recommend checking the box for Link underlines. This forces all links on GitHub to have a solid underline, which is incredibly helpful for low-vision users who might struggle to distinguish links by color alone.

-

Jamie: Are there any other settings we need to change?

-

Alex: Yes, we need to check your Feature Previews. GitHub is constantly improving its interface, and they let users opt into new designs before they become the default. Open the user menu again and activate Feature Preview. You are looking for two specific items. The New Issues Experience, and the New Files Changed Experience.

-

Jamie: What do those do?

-

Alex: The New Issues Experience completely rebuilds how issue lists are structured. It adds proper heading levels, accessible list structures, and live regions so your screen reader announces when you apply a filter. The New Files Changed Experience does the same thing for code reviews, adding a navigable file tree and turning visual code comparisons into structured tables.

-

Jamie: So basically, they make everything we are going to do in the workshop actually accessible.

-

Alex: Exactly. If you find them in the Feature Preview list, activate the Enable button for both. If you do not see them in the list at all, do not worry. That just means GitHub has already made them the default for everyone, and you are good to go.

-

Alex: Alright, our GitHub account is ready. Now we need to set up our local computer. That means installing Git, and installing our code editor.

-

Jamie: Let us start with Git. How do we get that time machine onto our laptop?

-

Alex: It depends on your operating system. If you are on Windows, you will navigate to git dash s c m dot com, download the Git for Windows installer, and run it. The default options are perfectly fine. If you are on a Mac, Git is often already there. You can open your Terminal application and type git space dash dash version. If it is not installed, the Mac will automatically pop up a dialog asking if you want to install the command line developer tools. Just agree to that. Linux users can install it using their standard package manager, like apt or dnf.

-

Jamie: Once it is installed, we have to introduce ourselves to Git, right? I remember this step. Configuring our Git identity.

-

Alex: That is right. Git embeds your name and your email address into every single snapshot, or commit, that you make. It needs to know who is making the changes. Think of it like signing the guestbook at an event. If you do not configure this, your commits might show up as authored by Unknown, which looks highly unprofessional, or Git might just refuse to save your changes entirely.

-

Jamie: How do we set that up?

-

Alex: You open your terminal and type two commands. The first is git space config space dash dash global space user dot name, followed by your full name in quotation marks. The second is git space config space dash dash global space user dot email, followed by the email address you used to sign up for GitHub.

-

Jamie: And a quick note here. The terminal is fully accessible. Whether you are using PowerShell on Windows with N V D A or JAWS, or the macOS Terminal with VoiceOver, you can read the output of your commands using your screen reader's review cursor or by simply arrowing up.

-

Alex: Now for the centerpiece of our local setup. Visual Studio Code, commonly called VS Code.

-

Jamie: This is the recommended editor for the workshop, right? Why do we use VS Code instead of something else?

-

Alex: VS Code is a free, open-source code editor built by Microsoft. We recommend it because its accessibility support is phenomenal. It has a dedicated team ensuring that screen readers can navigate complex codebases, interact with source control, and use artificial intelligence tools seamlessly. Think of VS Code as your digital workbench. It is where all your tools, your files, your terminal, and your version control live in one unified, accessible interface.

-

Jamie: You can download it at code dot visual studio dot com. The installer is standard. But once you open it, there is a very specific setting you have to turn on immediately.

-

Alex: Yes. Screen Reader Optimized Mode. This is absolutely critical. By default, VS Code renders text in a highly visual way that screen readers struggle to parse efficiently. When you turn on Screen Reader Optimized Mode, VS Code completely changes how it outputs information. It renders the editor as a plain text region so you can arrow through it linearly. It turns visual side-by-side code comparisons into readable text. And it enables audio cues, which are little sounds that play to indicate errors, folded code, or inline suggestions.

-

Jamie: How do we turn it on?

-

Alex: Often, VS Code will detect your screen reader on startup and present a dialog asking if you want to enable it. If it does, just press Enter to accept. If it does not, you can toggle it instantly by pressing Shift plus Alt plus F1.

-

Jamie: Or you can use the Command Palette, right? The Command Palette is my favorite feature. You press Control plus Shift plus P on Windows, or Command plus Shift plus P on Mac, and it opens a search box where you can type any command. Just type screen reader, and you will find the toggle.

-

Alex: Exactly. Once your screen reader mode is on, we need to install two extensions. Extensions are like adding new power tools to your workbench. They give VS Code new capabilities. You open the Extensions view by pressing Control plus Shift plus X, and search for the ones we need.

-

Jamie: The first one is the GitHub Pull Requests extension. What does that do?

-

Alex: A pull request is a request to merge your code changes into a main project. We will cover them deeply later. This extension allows you to review code, read comments, and manage pull requests entirely inside VS Code, without ever having to switch back to your web browser.

-

Jamie: And the second extension is GitHub Copilot Chat.

-

Alex: Yes. Copilot is an artificial intelligence pair programmer. The Copilot Chat extension gives you a conversational interface right in your editor. You can press Control plus Shift plus I to open the chat, and ask it questions like, how do I undo my last Git commit? Or, can you explain what this Python function does? It will read the code you currently have focused and give you plain text answers. It is fully accessible and incredibly helpful when you are learning.

-

Jamie: And Copilot has a free tier now, right?

-

Alex: It does. Copilot Free is available to all GitHub users. It gives you a limited number of chat messages and code completions per month, which is more than enough for this workshop. You just need to sign into your GitHub account inside VS Code to activate it.

-

Jamie: Alex, before we wrap up, I want to ask about something I heard some developers talking about. What if I am on a computer where I cannot install Git or VS Code? Like a library computer or a strict corporate laptop. Am I just locked out of contributing?

-

Alex: Not at all. This brings us to a fantastic feature called github dot dev. It is a completely browser-based alternative. If you are looking at any repository on GitHub dot com, you can simply press the period key on your keyboard.

-

Jamie: Wait, just the period key?

-

Alex: Just the period key. When you press it, the web page transforms into a lightweight version of VS Code, running entirely inside your browser. It looks and acts exactly like the VS Code you install on your desktop.

-

Jamie: That is amazing.

-

Alex: It really is. Think of it like a pop-up tent version of your digital workbench. You can take it anywhere, it requires absolutely zero installation, and because it is built on the same architecture as desktop VS Code, all the screen reader accessibility features still work. You can edit files, commit changes, and push them back to the repository without ever touching your local hard drive.

-

Jamie: I wish I had known about that trick when I started. Just press the period key. I love that.

-

Alex: It is incredibly handy for quick typo fixes or documentation updates. But for heavy development work, we still recommend the full desktop VS Code installation, because it gives you access to the local terminal and testing tools.

-

Alex: So, let us review our verification checklist before Day One. First, you have created your GitHub account, verified your email, and turned on Two-Factor Authentication.

-

Jamie: Second, you went into GitHub's Accessibility Settings, turned off the extremely noisy Hovercards, and turned on Link underlines.

-

Alex: Third, you installed Git, and configured your user dot name and user dot email in the terminal.

-

Jamie: Fourth, you installed Visual Studio Code, and immediately turned on Screen Reader Optimized Mode using Shift plus Alt plus F1.

-

Alex: And finally, you installed the GitHub Pull Requests and GitHub Copilot Chat extensions, and signed into your GitHub account inside the editor.

-

Jamie: If you can check all those boxes, you are completely ready for the workshop. But Alex, what if someone gets stuck on one of these steps? What if their terminal throws an error they do not understand, or their screen reader stops reading the editor?

-

Alex: Please do not suffer in silence. If you hit a roadblock, reach out to the workshop organizers immediately. You can file an issue on the Community Access repository, or send an email. We want to solve these setup quirks today. Every technical issue we fix before the workshop means more time for actual learning on Day One. You will not be left behind.

-

Jamie: This has been such a great overview. To summarize our key takeaways. Number one, Git is your local version control time machine, while GitHub is the web platform where you share and collaborate. Number two, disable Hovercards in your GitHub settings to keep your screen reader quiet and focused. Number three, always enable Screen Reader Optimized Mode in VS Code so your diffs and editor windows output clean, readable text.

-

Alex: Perfectly summarized. That brings us to the end of Episode One. Now that your tools are installed and configured, you are ready to start navigating. In Episode Two, we are going to dive into Understanding GitHub's Web Structure. We will explore how repository pages are laid out, which heading levels to jump to, and how to find exactly what you need without getting lost in the interface.

-

Jamie: I cannot wait. See you all in the next episode!

-

Alex: Thanks for listening to Gitt Going with GitHub. Keep practicing, and we will see you next time.

-
- - -

Episode 2: Understanding GitHub on the Web

-

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

-

Based on: Chapter 1: Understanding GitHub on the Web

- - -

Download Episode 2 (MP3)

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

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is Episode 2: Understanding GitHub on the Web. I am your host, Alex, and I am here to guide you through learning GitHub and open source collaboration, specifically designed for screen reader users and developers with low vision.

-

Jamie: And I am Jamie! I am so excited to be here. I learned GitHub about two years ago, and I still remember exactly how overwhelming it felt the first time I landed on a repository page. There is just so much information coming at you all at once.

-

Alex: It is incredibly overwhelming at first. In Episode 1, we made sure you had your GitHub account created and Git installed on your machine. Those were our prerequisites. Today, we are going entirely web-based. We are going to build a mental map of how GitHub organizes its web interface. Once you understand the underlying structure, the HTML headings, the ARIA landmarks, and the URL patterns, you will never feel lost on a GitHub page again.

-

Jamie: I love the idea of a mental map. When I first started, I used to just press the Tab key about fifty times to find what I wanted. I had no map. I just had hope and a lot of patience.

-

Alex: We are definitely going to save your Tab key today. To start, let us talk about the big picture. GitHub is not just one type of page. It is a nested structure. Think of GitHub like a massive office building.

-

Jamie: Okay, an office building. I can picture that.

-

Alex: Right. When you first log in, you land on your dashboard. That is the lobby of the building. It shows you a feed of recent activity from projects you follow. Also in this lobby level, you have your profile page, which is like your employee badge showing your recent work, and your settings page, which is like the administrative office.

-

Jamie: So the dashboard, profile, and settings are all Level 1. The lobby. Where does the actual coding happen?

-

Alex: That happens in a repository. If the dashboard is the lobby, a repository is a dedicated project room on an upper floor. A repository is simply a central place where all the files, code, and history for a specific project live. When developers say, navigate to the repo, they mean navigate to that specific project room.

-

Jamie: And once you are inside that repository room, you have different stations, right? Like issues and pull requests.

-

Alex: Exactly. Let us define those, because they are the most important page types you will interact with. An issue is basically a to-do ticket or a discussion thread. If you find a bug in the code, or you want to suggest a new feature, you open an issue. It has a title, a description, and a comment thread where people can discuss it.

-

Jamie: And what about a pull request?

-

Alex: So a pull request - and I love that name because you are literally requesting that someone pull your changes into their project - is what happens when you have actually written some code to fix that bug. You submit a pull request, often just called a PR, to propose your changes. The PR page is a bit more complex. It has the conversation thread, just like an issue, but it also has tabs to review the specific lines of code that were changed.

-

Jamie: Okay, so to recap our building analogy. The dashboard is the lobby. The repository is the project room. An issue is a to-do ticket sitting on a desk in that room. And a pull request is a formal proposal to change something in that room.

-

Alex: That is a perfect summary. And no matter which of these rooms you are in, there are certain structural elements that are always present. Let us talk about how to navigate them without spamming the Tab key.

-

Jamie: So, if I am not supposed to just Tab through the page, what is the first thing I should do when I land on a GitHub page?

-

Alex: The very first thing you will encounter on every single GitHub page, if you are navigating from the top of the document, is the jump-to-content skip link.

-

Jamie: Oh, the skip link! I actually know this one. It is a hidden link right at the top of the page. If you press Tab exactly once when the page loads, your screen reader will announce, Skip to content. If you press Enter on it, it skips over all the global navigation links and drops your focus directly into the main, unique content of that specific page.

-

Alex: Exactly. It is a massive time saver. But sometimes, you actually do want to access that global navigation. The global navigation bar is present at the top of every single page on GitHub. It contains the GitHub logo, which takes you back to your dashboard lobby. It contains a global search bar. It has links to all your pull requests and issues across all your repositories, your notifications inbox, and your profile menu.

-

Jamie: How do I jump straight to that global navigation if I am deep in the middle of reading an issue?

-

Alex: This is where ARIA landmarks come in. ARIA landmarks are invisible structural signposts in the HTML that screen readers can recognize and jump between. Every screen reader has a shortcut to cycle through landmarks. If you are using NVDA or JAWS on Windows, you press the letter D. If you are using VoiceOver on a Mac, you press Control plus Option plus U to open the rotor, then use the arrow keys to select Landmarks.

-

Jamie: So if I press D, what will I hear?

-

Alex: The global navigation bar is wrapped in a landmark called Navigation Menu. So if you press D, your screen reader will say, Navigation Menu landmark. Once you hear that, you can press the letter K to move through the individual links inside it.

-

Jamie: That is so much faster. And what happens when I navigate into a repository? Do the landmarks change?

-

Alex: The Navigation Menu landmark stays exactly the same, because it is global. But a new landmark appears just below it, called the Repository navigation landmark. This contains the tabs specific to that project room: the Code tab, the Issues tab, the Pull requests tab, and so on.

-

Jamie: Okay, so D for Navigation Menu gets me the global stuff. D again gets me the Repository navigation for the project tabs. What is below that?

-

Alex: Below that is the Main landmark. This is where the actual content of the page lives. If you are on an issue, the Main landmark holds the issue description and comments. If you are on the repository home page, the Main landmark holds the file tree and the project Read Me.

-

Jamie: I remember struggling so much to find the reply box when I wanted to leave a comment on an issue. I would just scroll and scroll. Is there a landmark for that?

-

Alex: There is! This is one of my favorite GitHub accessibility features. On any page where you can leave a comment, like an issue or a pull request, there is a specific landmark called Add a comment. You just press D until you hear Add a comment landmark, and you are right at the text box, ready to type.

-

Jamie: Okay, so landmarks are like the major zones of the page. Global nav, repo nav, main content, and the comment box. What about the actual content itself? If I am in the Main landmark, how do I know what I am looking at?

-

Alex: For that, we use the HTML heading structure. GitHub is very disciplined about how they use headings, and learning their pattern is the key to orienting yourself.

-

Jamie: I use the letter H to jump between headings all the time. But how do you use it for orientation?

-

Alex: Think of the Heading Level 1, or H1, as your You Are Here marker on a shopping mall directory map. It tells you exactly what page you are on. Every time you land on a new GitHub page, I recommend pressing the number 1 on your keyboard to jump straight to the first H1.

-

Jamie: What will I hear when I press 1?

-

Alex: It depends on the page type. If you navigate to a repository home page and press 1, you will hear the owner name slash the repository name. For example, community-access slash accessibility-agents. That confirms you are in the right project room. If you navigate to the issues list and press 1, you will just hear Issues.

-

Jamie: And if I open a specific issue?

-

Alex: If you open an issue and press 1, the H1 is the title of the issue itself. Like, Fix contrast on submit button. Same for a pull request. The H1 is always the title of the PR.

-

Jamie: That is so consistent. I love that. So H1 tells me where I am. What about the rest of the content?

-

Alex: Below the H1, GitHub uses H2s for major sections, and H3s for individual items. For example, on an issue detail page, the H1 is the issue title. Below that, there is an H2 called Description, which is the original bug report. Below that is an H2 called Activity, which contains all the comments.

-

Jamie: Oh, and let me guess, the individual comments are H3s?

-

Alex: You guessed exactly right. Every single comment on an issue or a pull request starts with an H3 heading that contains the author's username and the timestamp. So, if you open an issue with forty comments, you do not have to read them line by line. You just press the number 3 on your keyboard to jump from comment to comment, hearing who wrote it and when.

-

Jamie: That is brilliant. I wish I had known that when I started. I used to read the entire page from top to bottom. Okay, that sounds like a lot of steps to remember, though. Press D for landmarks, press 1 for the title, press 3 for comments.

-

Alex: It does sound like a lot! But here is the thing - you have already done most of this on Day 1 when you were browsing the web. It is the exact same workflow, just applied to a highly structured application. I recommend a ten-second orientation sequence every time you open a GitHub link.

-

Jamie: Walk me through the ten-second sequence.

-

Alex: Step one: press the number 1. Listen to the H1 to confirm what page you are on. Step two: press D a few times to cycle through the landmarks, so you know what regions are available on this page. Step three: pull up your screen reader's Elements List. In NVDA, that is NVDA plus F7. In JAWS, it is Insert plus F6 for the headings list.

-

Jamie: Ah, the Elements List! That brings up a dialog box with a clean list of every heading on the page, right? Like a table of contents.

-

Alex: Exactly. By doing those three things, which takes about ten seconds, you know exactly what page you are on, where the major zones are, and you have scanned the table of contents. You are completely oriented without needing to see the visual layout at all.

-

Jamie: One quick warning for folks - I remember getting really confused once because the landmarks disappeared. It turned out I had my browser window snapped to half the screen. GitHub is responsive, so when the window got narrow, it collapsed the sidebar and hid some of the navigation into a mobile-style menu.

-

Alex: That is a fantastic point, Jamie. To get the most consistent heading and landmark experience, always keep your browser window maximized when working on GitHub.

-

Jamie: So, navigating by headings and landmarks is great. But earlier you mentioned there are ways to jump around without even doing that. You mentioned built-in keyboard shortcuts.

-

Alex: Yes. GitHub has its own complex system of keyboard shortcuts built directly into the web application. They are powered by JavaScript, and they let you do things like jump straight to the pull requests tab, or filter issues by assignee, all with single keystrokes.

-

Jamie: But wait. If I press the letter H to use a GitHub shortcut, my screen reader is just going to intercept it and jump to the next heading, right?

-

Alex: Exactly. And this is the single biggest point of friction for screen reader users learning GitHub. You have to understand the difference between your screen reader's Browse Mode and Focus Mode.

-

Jamie: Can you break that down for us?

-

Alex: Absolutely. Browse Mode, which JAWS calls the Virtual Cursor, is what you use to read pages. In this mode, your screen reader intercepts your keystrokes. Pressing H goes to a heading. Pressing B goes to a button. The web page never hears you press those keys.

-

Jamie: Right, because if the web page heard it, you would just be typing the letter H over and over.

-

Alex: Exactly. Focus Mode, on the other hand, is what you use to type into text boxes. When you enter Focus Mode, the screen reader stops intercepting keys and passes them directly through to the web page. Usually, your screen reader switches to Focus Mode automatically when you land on a text box.

-

Jamie: But to use GitHub's custom keyboard shortcuts, we need to manually switch to Focus Mode even when we are not in a text box, right? So the page can hear the keystroke.

-

Alex: You nailed it. If you want to use a GitHub shortcut, you must manually enter Focus Mode first. In NVDA, you press NVDA plus Space. In JAWS, you press Insert plus Z. You will hear a little click or chime. Now, your keystrokes are going straight to GitHub.

-

Jamie: Okay, so once I am in Focus Mode, what are these magical GitHub shortcuts? How do I learn them?

-

Alex: You do not have to memorize them from a manual. GitHub has a built-in cheat sheet. If you press the Question Mark key - which is Shift plus Slash - GitHub opens a dialog box that lists every single shortcut available for the exact page you are currently on.

-

Jamie: Oh, that is clever! So the list changes depending on whether I am in the lobby dashboard or the project repository?

-

Alex: Yes, it is context-aware. Let us say you are in a repository. You press NVDA plus Space to enter Focus Mode. Then you press Shift plus Slash to open the shortcut menu. You will see shortcuts like pressing the letter G followed by the letter I to jump straight to the Issues tab. Or G followed by P to jump to the Pull Requests tab. Think of them as the secret elevator buttons in our office building.

-

Jamie: So G stands for Go. Go to Issues, Go to Pull Requests. That makes total sense. And once I am done using the shortcut, I need to remember to press NVDA plus Space again to turn Browse Mode back on, so I can read the new page with my normal heading keys.

-

Alex: Exactly. It takes a little practice to toggle between Focus Mode and Browse Mode, but it unlocks incredible speed. And there is one shortcut that is so powerful, you do not even need to toggle modes to use it, because it automatically throws your focus into a text field.

-

Jamie: Ooh, I know this one. The Command Palette!

-

Alex: Yes, the Command Palette. You can reach it from any page on GitHub by pressing the Forward Slash key, or by pressing Control plus K.

-

Jamie: Control plus K is my absolute favorite. What does it actually do?

-

Alex: When you press Control plus K, a search box pops up in the middle of your screen. But it is not just for searching text. It is a command center. You can type the name of a repository, and press Enter to jump straight to it. You can type the name of a file, or type the word settings to jump to your settings page.

-

Jamie: To use our building analogy, the Command Palette is like a magical concierge desk. You just walk up, press Control plus K, tell them where you want to go, and they instantly teleport you there. You do not even need to know which floor it is on.

-

Alex: That is a perfect analogy. The Command Palette is incredibly powerful for accessibility because it completely bypasses the need to navigate through complex menus or nested tabs. You just declare your intent, and GitHub takes you there.

-

Jamie: Alex, there is one more shortcut I have heard people talk about, and it sounds almost like magic. Something about pressing the period key?

-

Alex: Ah, yes. The period key shortcut. This is one of the most remarkable features GitHub has introduced in recent years. It is the bridge between reading code on the web and actually editing it.

-

Jamie: How does it work?

-

Alex: If you are on any repository page or viewing any file on GitHub, and you switch to Focus Mode and press the period key, the entire web page transforms. You leave github dot com, and you are redirected to a URL that says github dot dev.

-

Jamie: Github dot dev. What is the difference?

-

Alex: Github dot com is the standard web interface we have been talking about—the issues, the pull requests, the project rooms. Github dot dev is a fully functioning version of Visual Studio Code, the code editor, running entirely inside your web browser.

-

Jamie: Wait, so I do not have to install anything? I just press the period key, and suddenly I am in a professional code editor with the entire project loaded up?

-

Alex: Exactly. No installation, no cloning the repository to your local computer, no terminal commands. It just opens the project in a web-based editor. And because it is VS Code, it has excellent screen reader support built right in.

-

Jamie: That is wild. Why would I use that instead of just downloading the code to my laptop?

-

Alex: It is perfect for quick changes. Let us say you are reading the project Read Me, and you notice a typo. Instead of opening your terminal, downloading the project, opening your local editor, fixing the typo, and pushing the code back up... you just press the period key. The editor opens in your browser, you fix the typo, you commit the change from the web interface, and you are done.

-

Jamie: I love that. It lowers the barrier to entry so much. If someone finds an accessibility bug in documentation, they can fix it in literally two minutes right from the browser.

-

Alex: Exactly. Now, there is one pro-tip for screen reader users regarding the period key. If you just press period, it transforms your current browser tab into the editor. When you are done, you have to hit the back button to get back to GitHub. A better way is to press Shift plus Period, which types the greater-than symbol.

-

Jamie: What does Shift plus Period do?

-

Alex: It opens github dot dev in a brand new browser tab. That way, you keep your original GitHub page open in your first tab, and you have your code editor in the second tab. It is much easier to keep your mental map intact that way.

-

Jamie: Shift plus Period for a new tab. I am definitely writing that one down.

-

Alex: We have covered a massive amount of ground today, Jamie. Let us wrap up with some concrete takeaways for our listeners to practice.

-

Jamie: I will take the first one! Takeaway number one: Think of GitHub like a building. The dashboard is the lobby, the repository is the project room, issues are to-do tickets, and pull requests are formal proposals to change the code.

-

Alex: Perfect. Takeaway number two: Use the ten-second orientation sequence on every new page. Press the number 1 to hear the H1 heading and know where you are. Press D to scan the ARIA landmarks like Navigation Menu and Main. And use your screen reader's Elements List to read the table of contents.

-

Jamie: Takeaway number three: Comments are always H3 headings. If you want to read a discussion thread quickly, just press the number 3 to jump from author to author without reading every single line in between.

-

Alex: Takeaway number four: Learn to toggle Browse Mode and Focus Mode. Use NVDA plus Space, or Insert plus Z, to enter Focus Mode so you can use GitHub's built-in shortcuts. Press Shift plus Slash to open the cheat sheet for whatever page you are on.

-

Jamie: And takeaway number five: When in doubt, teleport. Press Control plus K to open the Command Palette, type where you want to go, and press Enter. Or press Shift plus Period to instantly open the code in a web-based editor.

-

Alex: Those are excellent takeaways. Now that you have a mental map of the building, and you know how to navigate the hallways, you are ready to start looking at the code itself. In Episode 3, we are going to dive deep into Navigating Repositories. We will cover how to read the file tree, how to switch between different branches of code, and how to read the project documentation.

-

Jamie: I cannot wait. I am ready to get out of the lobby and into the project rooms.

-

Alex: Until then, open up your browser, head to GitHub, and practice your ten-second orientation. Thank you for listening to Gitt Going with GitHub. We will see you in the next episode.

-
- - -

Episode 3: Navigating Repositories

-

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

-

Based on: Chapter 2: Navigating Repositories

- - -

Download Episode 3 (MP3)

-
-Read Transcript - Episode 3: Navigating Repositories - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode three, Navigating Repositories. I am Alex, and I am so glad you are joining us today.

-

Jamie: Hello everyone! I am Jamie, and I am incredibly ready for this one.

-

Alex: Today we are diving into the absolute core of GitHub. We are going to explore what a repository actually is, how to read its history, and how to navigate its structure using your screen reader. We will cover branches, cloning, forking, and all those different sections you encounter when you first open a project.

-

Jamie: And just a quick reminder, if you have not listened to episode two, you might want to jump back and check it out. In that episode, we covered the basic structure of a GitHub page. We talked about navigating by headings, using landmarks to find your way around, and using the built in keyboard shortcuts. We will be building directly on those skills today.

-

Alex: Exactly. If you are comfortable moving through landmarks and jumping to headings, everything we talk about today is going to feel very approachable.

-

Alex: Let us start at the very beginning. What is a repository? At its most basic level, a repository is essentially a project folder that is tracked by Git. It holds all the files, all the folders, and the complete documentation for a specific project.

-

Jamie: When I was learning this a couple of years ago, I realized a repository is not just a folder. It is like a magical filing cabinet with a built in time machine. It does not just hold the files as they are right now. It holds every single version of every single file, going all the way back to the very first day the project was created.

-

Alex: That is a perfect way to describe it. It is the entire history of the project. And when you navigate to a repository address, like github dot com slash owner slash repo name, you land on the repository home page.

-

Jamie: Right, and as soon as the page loads, your screen reader will announce the page title, which tells you the owner and the repository name. If you press the number one key, you will jump straight to the main heading one, which is also the repository name.

-

Alex: Once you are on that page, the first major landmark you want to find is the repository navigation landmark. You can reach this by pressing the D key to cycle through your landmarks. This navigation area contains the tab bar, which is how you move between the different sections of the repository.

-

Jamie: I like to think of these tabs as different rooms in an office building. They all belong to the same company, but different types of work happen in each room.

-

Alex: Let us walk through those rooms. The default tab, the one you land on first, is the Code tab. We will spend a lot of time here. Next to it, you will find the Issues tab.

-

Jamie: Issues are your discussion board. This is the room where people report bugs, request new features, or ask questions. If you find a problem with the software, you go to the Issues tab to tell the team about it.

-

Alex: Next is the Pull Requests tab. So a pull request, and I love that name because you are literally requesting that someone pull your changes into their project, is a proposal to merge your code. When you write new code and want to share it with the project, you open a pull request.

-

Jamie: Then we have the Actions tab. Actions are automated scripts. This is the robot room of the office. It is where automated tests run every time someone submits new code, to make sure nothing is broken.

-

Alex: And finally, depending on your permissions, you might find the Settings tab. This is the manager's office. It is usually only visible to the maintainers of the project, and it is where they control permissions and repository features.

-

Alex: Let us focus on that first tab, the Code tab. When you are on the Code tab, the main piece of content is the files table. This table shows every file and folder currently in the project.

-

Jamie: To get to the files table quickly, I press the T key to jump to the next table on the page. My screen reader will announce something like, table with twenty rows and three columns.

-

Alex: Those three columns are very important. The first column is the Name of the file or folder. The second column is the Message, which tells you the most recent change made to that specific file. And the third column is the Age, which tells you how long ago that change happened.

-

Jamie: Navigating this table is a great time to use your screen reader table commands. If I am using N V D A or Jaws, I hold down Control and Alt, and use my arrow keys. Pressing Control plus Alt plus Down Arrow moves me to the next row, which is the next file. Pressing Control plus Alt plus Right Arrow moves me across the columns, from the file name, to the message, and then to the age.

-

Alex: And if you are using VoiceOver on a Mac, you will hold down the V O keys, plus Shift, and use your arrow keys to move through the table cells.

-

Jamie: One thing that confused me at first was telling the difference between a file and a folder in that table. But I learned that if it is a folder, the screen reader will announce a slash at the end of the name. If you press Enter on a folder, the page reloads and shows you the contents of that specific folder.

-

Alex: Exactly. Now, immediately following the files table in the reading order is the read me section. The read me dot m d file is a markdown file that acts as the welcome mat for the project. GitHub automatically renders this file and displays it right below the files table.

-

Jamie: The read me is its own landmark region, so you can press D to jump to it. Because it is rendered markdown, it has a full heading structure. I always press the H key to read through the headings in the read me so I can quickly understand what the project does and how to install it.

-

Alex: Before you reach the files table, there is a very important control called the branch selector. To understand this, we need to define what a branch is, and why repositories have them.

-

Jamie: A branch is a separate line of development inside a repository. If we all edited the exact same files at the exact same time, it would be complete chaos. Branches give us parallel timelines to work in safely.

-

Alex: That is exactly right. A branch lets you isolate your work.

-

Jamie: My favorite analogy for a branch is baking. Imagine you are baking a cake from a cherished family recipe. You want to try adding lemon zest to the batter, but you absolutely do not want to ruin the original recipe card in case your experiment tastes terrible. So, you copy the entire recipe onto a brand new card, write Lemon Experiment at the top, and make your changes there. That new card is a branch. If the cake turns out delicious, you can permanently update the original recipe later.

-

Alex: And that original recipe card has a name. It is called the default branch. On modern GitHub projects, the default branch is almost always named main. The main branch holds the stable, official version of the project. Whenever you navigate to a repository, you are viewing the main branch by default.

-

Jamie: To switch to a different branch, you use the branch selector. You can press the B key to jump to buttons until you hear the current branch name, which usually sounds like main branch button. When you press Enter, it opens a dropdown panel.

-

Alex: This dropdown is a live region. As soon as it opens, your focus is placed in a search field. You can simply start typing the name of the branch you are looking for.

-

Jamie: Then, you press the Tab key to move into the filtered results list, and use your Up and Down arrows to find the exact branch. Once you press Enter, the entire page reloads, and the files table will now show the code exactly as it exists on that specific branch.

-

Alex: Let us talk about the history of those changes. When you are exploring the files table, you hear the message column. Those messages come from commits. A commit is a saved snapshot of your changes at a moment in time.

-

Jamie: I like to think of the commit history as the ultimate project guestbook. If the repository is a magical filing cabinet, the commit history is the unalterable ledger sitting right on top of it. Every single time someone puts a file in or takes one out, they have to sign the ledger, write the exact date and time, and write a little note explaining exactly what they did and why.

-

Alex: That is a great comparison. A commit is not just the code that changed. It is the who, the what, and the when. And you can read this entire ledger. On the Code tab, you can navigate to a link that says something like, one thousand commits.

-

Jamie: When you activate that link, you are taken to the commit history page. The commits are grouped by date, and you can use your heading navigation, pressing the H key or the number three key, to jump through the dates. Then you use the I key to move through the individual list items, which are the commits themselves. It is fascinating to read through the history and see how a project evolved day by day.

-

Alex: So far, we have been browsing code on the GitHub website. But eventually, you will want to work on the code yourself. This brings us to two fundamental concepts, cloning and forking. Let us define cloning first. What does cloning mean?

-

Jamie: Cloning means copying a remote repository from GitHub down to your local computer. You are making a full, working clone of the project on your own hard drive, including its entire history.

-

Alex: Right. If the repository is a massive encyclopedia in the library, cloning is like checking that encyclopedia out and bringing it to your own desk at home. You can flip through all the pages, read the history, and work with the material entirely offline.

-

Jamie: But what if I want to make changes and give them back to the project? I do not have permission to just change their official encyclopedia. This is where forking comes in. A fork is a personal copy of someone else's repository, but it lives in your own GitHub account in the cloud.

-

Alex: Exactly. You fork a project on GitHub to create your own copy where you have full control.

-

Jamie: My analogy for forking is business. Forking is like buying a franchise of a popular restaurant. You are given the exact blueprints, the menu, and the operations manual of the original restaurant. But this new building belongs to you. You can try out new recipes in your kitchen without affecting the original restaurant. But, if you invent a brilliant new dish, you can send a proposal back to headquarters, asking them to add it to the official menu. That proposal is your pull request.

-

Alex: That is brilliant. So, to recap the workflow, you fork the original project to your GitHub account, and then you clone your personal fork down to your computer.

-

Jamie: OK that sounds like a lot of steps. I navigate to the repository, I fork it on the website, then I open my terminal, then I find the web address, and then I clone my fork to my computer?

-

Alex: It does! But here is the thing, you have already done most of this on Day One. Same workflow, just with V S Code handling the heavy lifting. Once you understand the concepts, the actual execution becomes second nature.

-

Alex: Let us talk about the actual mechanics of cloning. When you are on the Code tab, there is a very prominent button labeled simply, Code.

-

Jamie: I usually navigate to the main repository heading by pressing the number one key, and then press the B key to move to the next button, which is the Code button. When you press Enter or Space to activate it, it opens a flyout panel.

-

Alex: This panel has a few different tabs for how you can get the code, specifically H T T P S, S S H, and GitHub C L I.

-

Jamie: If you are using standard Git in your terminal, you would make sure the H T T P S tab is selected, press the Tab key to find the copy url to clipboard button, and press Enter. Then you go to your terminal and type git clone, followed by a space, and paste that long web address.

-

Alex: But there is a faster way if you have the GitHub Command Line Interface installed. We call it the g h tool.

-

Jamie: Oh I love the g h tool. In that same flyout panel, you can choose the GitHub C L I tab. The command it gives you is so much simpler. Instead of a long web address, you just type g h repo clone, followed by a space, and then the owner name, a slash, and the repository name. So to clone the learning room, you just type g h repo clone community dash access slash learning dash room. It is so clean.

-

Alex: It really is. Now, what if someone just wants the files to read, and they do not care about the Git history or making contributions?

-

Jamie: If you keep pressing the Tab key inside that Code flyout panel, you will eventually reach a button called Download zip. This gives you a compressed zip folder of the code exactly as it is right this second.

-

Alex: Right. But remember, a downloaded zip folder is not tracked by Git. It is like printing out a physical photograph of the code instead of downloading the digital file. You can look at it, but you cannot push any changes back to GitHub from a downloaded zip file. You only use Download zip if you are just exploring.

-

Alex: Before we wrap up, we need to talk about one more important region on the repository page. The sidebar.

-

Jamie: Yes! After the read me section in the reading order, you will find the sidebar content. To get there quickly, I press the D key until I reach the Main landmark, and then I press the number two key or the H key to jump to the heading called About.

-

Alex: The About section is critical because it contains the project description, a link to the project website if they have one, and the repository topics.

-

Jamie: Topics are essentially tags. They tell you what the project is built with or what it is for. You might hear topics like python, accessibility, screen reader, or machine learning. It is a great way to quickly understand the context of the code.

-

Alex: And right next to the About section, you will find the license. The license is fundamentally what makes open source work. It is a legal document that tells you exactly what you are allowed to do with this code. If a repository does not have a license, you technically do not have permission to use, modify, or distribute it, even if it is completely public on GitHub. Always check the license.

-

Alex: We have covered a massive amount of ground today. Let us review our main takeaways.

-

Jamie: Takeaway number one. A repository is your main project container. You can navigate its different areas, like Code, Issues, and Pull Requests, by finding the Repository Navigation landmark.

-

Alex: Takeaway number two. The Code tab contains the files table. You can use your screen reader table commands to read across the rows, checking file names, commit messages, and how long ago the file was changed.

-

Jamie: Takeaway number three. Branches let you work on parallel versions of the code safely, just like testing a recipe on a new card. The official, stable version is almost always kept on the default branch, which is called main.

-

Alex: Takeaway number four. Forking creates your own personal copy of a project in the GitHub cloud, like buying a franchise. Cloning downloads a working copy to your local computer, like checking a book out of the library.

-

Jamie: And takeaway number five. The commit history is the unalterable guestbook of the project. It tells you exactly who changed what, and when they did it.

-

Alex: Perfect summary. In our next episode, we are going to put all of this theory into practice. We will be entering The Learning Room, where you will navigate these tabs yourself and make your very first open source contribution.

-

Jamie: I cannot wait for that one. Thank you all for listening, and we will see you in the next episode!

-
- - -

Episode 4: The Learning Room

-

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

-

Based on: Chapter 3: The Learning Room

- - -

Download Episode 4 (MP3)

-
-Read Transcript - Episode 4: The Learning Room - -

Transcript

-

Alex: Welcome back to Gitt Going with GitHub. This is episode four, titled The Learning Room. I am Alex, and I am here to guide you through the wonderful, sometimes chaotic, but always rewarding world of open source collaboration.

-

Jamie: And I am Jamie. I am relatively new to GitHub, having learned it just about two years ago. I am here to ask all the questions that you might be thinking, and hopefully help us all avoid the mistakes I made when I was first starting out.

-

Alex: We are so glad to have you here. In this episode, we are talking about the Learning Room. This is a very special part of the GitHub workshop experience. But before we dive into that, let us do a quick recap. In episode three, we talked about navigating repositories.

-

Jamie: Right, we talked about how a repository is essentially the master project folder. It holds all the files, the history of changes, and the branches. And we talked about how a branch is like a parallel universe where you can safely make changes without breaking the main project.

-

Alex: Exactly. If you are feeling a little fuzzy on how to move through a repository using your screen reader, or how to explore a file tree, you might want to pause this and go back to episode three. But if you are ready to keep going, let us talk about the Learning Room.

-

Alex: During your first day of learning GitHub, you are actually working on two parallel tracks. Track one is your individual skills track. This happens on your personal GitHub account. You work through modules at your own pace, and a friendly automated bot named Mona guides you step by step.

-

Jamie: I like Mona. Mona is very patient when I forget to commit my changes.

-

Alex: Mona is great. But track one is private. It is just you and the bot. Track two is the Learning Room contribution sprint. And this is completely different. The Learning Room is a single, shared GitHub repository where all the workshop participants collaborate together at the exact same time.

-

Jamie: Wait, all of us? In one repository? At the same time? That sounds like a recipe for overriding each other's work.

-

Alex: It sounds like it, but that is the magic of GitHub. Think of the Learning Room like a large community kitchen. Track one, with Mona, is like practicing chopping vegetables in your own private kitchen at home. You can take your time, and nobody is watching. But the Learning Room is the community kitchen. You are at one prep station, someone else is at the stove, someone else is baking bread. You can all hear and interact with each other, you are all contributing to the same massive meal, but because everyone has their own specific task and their own branch, you do not bump elbows.

-

Jamie: Okay, I love that analogy. But why do we do it this way? Why not just keep practicing in our private kitchens?

-

Alex: Because open source is a community kitchen. Real open source projects are shared spaces. By putting everyone in one repository, we create a realistic environment. You get to see other people's work, you learn from the person sitting next to you, and we can practice peer review.

-

Jamie: That makes sense. It bridges the gap between learning the buttons to press, and actually working with other human beings.

-

Alex: Exactly. Now, to understand how we collaborate in this space, we need to talk about the workflow. Specifically, the fork, edit, and pull request workflow.

-

Jamie: Oh, good. I hear the word fork all the time. I know what a branch is, but what is a fork? Is it just another utensil in our community kitchen?

-

Alex: Great question. Let us define it. A fork is a complete, personal copy of someone else's repository, placed into your own GitHub account. Let us say you find an amazing open source project, but you do not have permission to change their files directly. You would create a fork. That makes a copy in your account where you have full control. You make your edits there.

-

Jamie: Okay, so I fork the project, I make my changes in my copy. But how does the original project get those changes?

-

Alex: That is where the Pull Request comes in. And I love that name because you are literally requesting that the original project owners pull your changes from your fork into their project. In standard open source, this fork, edit, and pull request workflow is how almost everything gets done.

-

Jamie: So in the Learning Room, are we all forking the repository?

-

Alex: In the Learning Room, we actually simplify it just a bit to keep us all in one space. Instead of everyone making their own separate fork, we give everyone permission to create branches directly inside the shared Learning Room repository. You will still create a branch, make your edit, and open a Pull Request. It is the exact same workflow you use with a fork, just contained within one big shared house so we can all see each other's pull requests easily.

-

Jamie: Okay, so we are in this shared community kitchen. What are we actually cooking? What are the tasks?

-

Alex: We call them challenges. Inside the Learning Room repository, there is a folder called docs. Inside that folder, there is a file called CHALLENGES dot M D. M D stands for Markdown. This file is your menu. It lists twelve different challenges organized by skill level, from beginner to expert.

-

Jamie: How do I find my challenge and know what to do?

-

Alex: You will navigate to that challenges file and read through the options. Each challenge tells you exactly which file you need to edit, what skills you will practice, and what the success criteria are. And here is the fun part. The practice files you will be editing have intentional mistakes built into them.

-

Jamie: Intentional mistakes? Like a scavenger hunt?

-

Alex: Exactly like a scavenger hunt. Let me give you an example. There is a file called welcome dot M D. It is supposed to be an introduction to open source for newcomers. But it has three sections marked with the word TODO in capital letters, where the content is just missing.

-

Jamie: Oh, I have seen those in real projects. Someone writes a document, gets tired, types TODO, and leaves it for someone else.

-

Alex: Precisely. One of the beginner challenges is to find those TODO markers, delete them, and write the missing paragraphs. Another file is called keyboard dash shortcuts dot M D. This is a reference guide for screen reader shortcuts. It has tables for N V D A, JAWS, and VoiceOver. But we purposely put incorrect shortcuts in those tables.

-

Jamie: Oh, that is devious. I love it. So we have to find the wrong shortcut and fix it?

-

Alex: Yes, and you have to do it without breaking the structure of the Markdown table. It is fantastic practice. There is also a setup guide file with broken links that point to nowhere. Your job might be to track down the broken links and update them to the correct web address.

-

Jamie: Okay, that sounds like a lot of fun, actually. But how do I know when I am done? Do I just save the file and yell across the room that I finished?

-

Alex: Not quite. You know you are done when your Pull Request is merged into the main project. Merging means your changes are officially accepted and combined with the original file. When that happens, an automated bot will actually post a celebration comment on your pull request and award you a digital badge.

-

Jamie: Alright, let us talk about opening that Pull Request. I remember the first time I had to open a Pull Request. I was terrified. I felt like I was standing on a stage and everyone was about to judge my code.

-

Alex: That is a very common feeling. It can feel incredibly intimidating. You are putting your work out there for public review.

-

Jamie: It really is intimidating! OK, that sounds like a lot of steps. Creating branches, making edits, opening this request for everyone to see.

-

Alex: It does! But here is the thing. You have already done most of this on Day 1 in your private track. It is the exact same workflow. And remember, the Learning Room is a safe environment. Every single person in that repository is learning, just like you. And we have built safety nets into the process.

-

Jamie: Safety nets? Like what?

-

Alex: The first safety net is our automated bot. We call it the Learning Room PR Bot. The moment you open your Pull Request, within about thirty seconds, this bot springs into action.

-

Jamie: What does the bot do? Does it grade my work?

-

Alex: I prefer to think of it as a friendly automated building inspector who walks through the house before the open house begins. The bot checks to make sure you edited the correct file. It checks your Markdown formatting to ensure you used headings correctly. If you added an image, it checks to make sure you included alternative text for screen readers. It even checks to ensure you did not leave any broken links behind.

-

Jamie: Wow, that is really thorough. What happens if I messed something up? Does it reject my Pull Request?

-

Alex: Never. The bot never fails your Pull Request or closes it. Instead, it posts a very detailed, educational comment on your Pull Request. It tells you exactly what it found, explains why it matters for accessibility or formatting, and gives you links to documentation so you can learn how to fix it.

-

Jamie: Oh, I wish I had known that when I started. An automated proofreader that explains things nicely instead of just yelling error messages at me.

-

Alex: Exactly. It gives you instant feedback. And you can push a new commit to your branch to fix the issues, and the bot will run again and update its report. It is a completely low-stakes way to practice getting technical feedback.

-

Alex: But the bot is only the first step. The second step is human peer review. And this is where the real magic of the Learning Room happens.

-

Jamie: Peer review. So, reading and commenting on classmate work. How does that work? Do I just pick someone at random?

-

Alex: We have another automation called the pairing bot. When you open your Pull Request, the pairing bot looks at the roster of students and automatically assigns one of your classmates to be your reviewer. It tries to balance the workload so nobody gets overwhelmed.

-

Jamie: So someone else in the workshop gets a notification saying, Jamie needs you to review their work?

-

Alex: Yes. And the bot even posts a comment giving the reviewer instructions on what to look for. It might say, please check that Jamie completed all three TODO sections, and that the new paragraphs read well.

-

Jamie: Okay, so let us walk through this from the perspective of the reviewer. Let us say I get that notification. I have been assigned to review your Pull Request, Alex. How do I navigate that with my screen reader? Where do I go?

-

Alex: This is a great practical question. First, you will navigate to the Learning Room repository in your browser. From the main repository page, you need to navigate to the Pull Requests tab.

-

Jamie: How do I find that tab efficiently?

-

Alex: If you are using N V D A or JAWS on Windows, you can use GitHub's built-in keyboard shortcuts. Press the letter G, followed by the letter P. That stands for Go to Pull requests.

-

Jamie: Oh, that is clever! G then P. Does that work for VoiceOver on Mac too?

-

Alex: Yes, those are GitHub specific shortcuts, so they work across platforms as long as your screen reader is passing the keystrokes through. Once you are on the Pull Requests page, you will be in a list of all open pull requests. If it is a busy workshop, there might be thirty pull requests in that list.

-

Jamie: That sounds overwhelming. How do I find the one I am supposed to review?

-

Alex: You use the filter. Navigate to the filter text box. By default, it says something like, is open is PR. You can clear that and type a specific filter query. You will type, review dash requested, then a colon, then the at symbol, and the word me. So, review requested colon at me. Press Enter.

-

Jamie: And that filters the list to only show the ones where I am the assigned reviewer?

-

Alex: Exactly. Now you can use your screen reader's heading navigation. Press the letter H to jump from one pull request title to the next. When you hear the title of the one you want, press Enter to open it.

-

Jamie: Okay, I am on the Pull Request page. What am I looking at? Or rather, what am I listening to?

-

Alex: A Pull Request page has a few different tabs, but the two most important ones are the Conversation tab, and the Files Changed tab. You land on the Conversation tab by default.

-

Jamie: The Conversation tab. Is that where the bot leaves its report and where people leave comments?

-

Alex: Yes. You can use heading navigation here as well. Every comment is a heading. You will find the original description of the Pull Request, the automated bot's report, and any discussion that has happened so far. You will also find a section called Reviewers, usually marked as a heading level three, which confirms that you are assigned.

-

Jamie: So I read the conversation to get context. But how do I actually see the changes you made to the code or the text?

-

Alex: For that, you navigate to the Files Changed tab. Once you activate that tab, you are looking at the diff.

-

Jamie: The diff. Let us define that. A diff is short for difference. It is a special view that shows exactly what was added and what was removed from a file.

-

Alex: Right. Navigating a diff with a screen reader takes a little practice. GitHub presents the diff as a table or a structured list of lines. As you arrow down through the content, your screen reader will announce the state of each line.

-

Jamie: What does that sound like?

-

Alex: If a line was added, your screen reader will usually say plus, or inserted, before reading the text. If a line was removed, it will say minus, or deleted. Unchanged lines, which are just there to give you context, are read normally without a prefix.

-

Jamie: So if you were fixing a typo in the word GitHub, I would hear a minus line with the misspelled word, immediately followed by a plus line with the correctly spelled word?

-

Alex: Exactly. You can read through the entire file this way, line by line, to see exactly what the author changed.

-

Jamie: Okay, so I have read your changes. I think they look great, but I want to suggest one small addition. How do I leave my review?

-

Alex: On the Conversation tab, there is a large text area for adding a comment. If you are using N V D A, you might press N V D A plus Space to enter Focus Mode, or Forms Mode for JAWS, so you can type freely. If you are using VoiceOver on a Mac, you would navigate to the text area and press V O plus Shift plus Down Arrow to interact with it.

-

Jamie: I type my feedback. Do I just say, looks good?

-

Alex: You could, but helpful peer review is specific. You might say, I love the paragraph you added about assistive technology. One suggestion, maybe we could add a link to the official documentation here.

-

Jamie: That is a great way to phrase it. It is encouraging but offers a clear improvement. So I type that out. Then what?

-

Alex: Then you navigate to the button called Review Changes. When you activate it, you get to choose the type of review. You can choose Comment, which is just leaving feedback without passing judgment. You can choose Approve, which means you think it is perfect and ready to be merged. Or you can choose Request Changes, which means there is something specific that must be fixed before it can be merged.

-

Jamie: So if you missed one of the TODO markers, I would choose Request Changes and politely let you know.

-

Alex: Exactly. Once you select your option, you navigate to the Submit Review button and press Enter. The author gets a notification, and they can push a new commit to address your feedback.

-

Jamie: I really like this process. But I have to ask, what if I am assigned to review someone's work, and I do not know if their code is right? I am a beginner too. I might approve something that is actually broken.

-

Alex: That is the beauty of the Learning Room. It is completely low stakes. Remember the flight simulator analogy?

-

Jamie: A flight simulator. Where you can crash the plane without actually hurting anyone.

-

Alex: Exactly. We want you to make mistakes here. If you approve a Pull Request that has a formatting error, the automated bot will probably catch it anyway. And even if the bot misses it, and it gets merged into the repository, that is fine! It just becomes a new challenge for the next student to fix.

-

Jamie: Oh, I never thought of it that way. A mistake just creates more open source work for the community.

-

Alex: Right. The goal here is not perfect code. The goal is building confidence. When you practice this fork, edit, and pull request workflow in a safe environment, you are building muscle memory.

-

Jamie: So when I go to contribute to a huge project like N V D A or React, my hands will already know the keyboard shortcuts. I will already know how to filter for my reviews.

-

Alex: Precisely. Because the steps you take in the Learning Room are the exact same steps you take on the biggest open source projects in the world. And I want to emphasize this. When you merge a Pull Request in the Learning Room, it is a real contribution.

-

Jamie: It is not a simulation?

-

Alex: The environment is designed for learning, but the technology is real. You found an issue, you made a meaningful change, you received technical feedback from a bot, you received human feedback from a peer, you incorporated their suggestions, and you merged your work. That is open source contribution in its purest form. You will have a merged commit in your GitHub history to prove it.

-

Jamie: That is incredibly motivating. It takes the fear out of the process and replaces it with a sense of community.

-

Alex: Let us wrap up with a few key takeaways from our discussion today. First, the Learning Room is a shared repository where everyone collaborates together. It is designed to simulate the bustling, collaborative nature of a real open source project.

-

Jamie: Second, the practice challenges are real files with intentional mistakes. You find your challenge in the docs folder, make your fixes on a branch, and open a Pull Request.

-

Alex: Third, you are supported by two types of feedback. The automated bot gives you instant, low-stakes technical feedback on accessibility and formatting. And your peers give you human feedback on your content.

-

Jamie: And finally, leaving a peer review is just as important as writing the code. You use the filter review requested colon at me to find your assignments, read the diff to see what changed, and leave constructive, encouraging comments.

-

Alex: Beautifully summarized. In our next episode, we are going to dive deeper into how projects organize all of this work. We will be talking about Working with Issues. Issues are how we track bugs, plan features, and figure out what to work on next.

-

Jamie: I cannot wait. Tracking tasks is my favorite kind of organizing.

-

Alex: Thank you all for listening to Gitt Going with GitHub. Take a deep breath, go open that first Pull Request in the Learning Room, and we will see you in the next episode.

-
- - -

Episode 5: Working with Issues

-

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

-

Based on: Chapter 4: Working with Issues

- - -

Download Episode 5 (MP3)

-
-Read Transcript - Episode 5: Working with Issues - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode 5, Working with Issues. I am Alex, and I am here to guide you through the accessibility and workflow concepts that will help you thrive in open source.

-

Jamie: And I am Jamie. I am a blind developer who started learning GitHub about two years ago, and I am here to ask all the questions that you are probably thinking right now.

-

Alex: It is great to have you here, Jamie. In episode 3, we covered repository navigation and how to move between the different tabs of a project. Today, we are diving deep into one of those specific tabs, the Issues tab. We will cover what issues are, how to read them, how to file them, and how to manage them.

-

Jamie: I remember when I first heard the word issue in the context of programming. In everyday life, having an issue sounds like a bad thing. Like a problem. I thought it meant I broke something.

-

Alex: That is such a common reaction! But in GitHub, an issue is not necessarily a bad thing at all. Think of an issue simply as a unit of work. It is a dedicated discussion thread attached to a repository. Yes, it can be a bug report, but it can also be a feature request, a question, a task, or an accessibility report.

-

Jamie: So it is basically a digital manila folder for a specific topic.

-

Alex: Exactly. That is a perfect analogy. If you want to add a new button to your application, you open a manila folder, write Add New Button on the tab, and put all your notes, questions, and checklists inside that folder. On GitHub, that folder is an issue. It keeps the conversation focused and gives everyone a place to collaborate before any code is actually written.

-

Jamie: Okay, so how do I actually find these manila folders? Say I am on a repository page right now.

-

Alex: If you are using a screen reader, you can navigate by landmarks to the Repository navigation region, then press your Tab key until you reach the Issues tab. Your screen reader will usually announce the word Issues followed by the number of open issues, like, Issues, 14 open. Then you just press Enter.

-

Jamie: Is there a faster way? You know I love keyboard shortcuts.

-

Alex: There is! If you are in Focus Mode, you can press the letter G, release it, and then press the letter I. G stands for Go, and I stands for Issues. That will jump you straight to the Issues tab from anywhere in the repository.

-

Jamie: Oh, that is clever. Go to Issues. G then I. I will definitely use that. So once I am on the Issues page, what does the structure look like?

-

Alex: The page is built around a search and filter bar at the top, followed by some buttons to switch between Open and Closed issues, and then the main event, which is the issues list itself.

-

Jamie: How should I navigate that list with my screen reader?

-

Alex: The best way is to use your heading navigation. Every issue title in the list is a heading level 3 link. So if you press the number 3 on your keyboard, you will jump from issue to issue. Your screen reader will announce the title, the issue number, any labels attached to it, who opened it, and how many comments it has.

-

Jamie: That sounds like a lot of information. Does it read it all at once?

-

Alex: It usually reads it as a single block of text when you land on the heading. If you want to explore a specific issue in more detail before opening it, you can use your down arrow to read the individual elements like the author and the timestamp.

-

Jamie: Let us talk about that search and filter bar you mentioned. If a project has hundreds of open issues, pressing the number 3 to read all of them is going to take all day.

-

Alex: You are absolutely right. That is where filtering comes in. It is like having an assistant who can instantly pull only the manila folders you care about from a massive filing cabinet. To reach the search bar, you can navigate to it using your form field shortcut, which is usually the letter E or F depending on your screen reader.

-

Jamie: And when I get there, I need to switch to Focus Mode to type, right?

-

Alex: Yes, exactly. Switch to Focus Mode, which is Insert plus Space for NVDA, or Insert plus Z for JAWS. Once you are in the text field, you can type qualifiers to filter the list. For example, if you want to find bugs, you type the word is, followed by a colon, followed by the word open, then a space, then the word label, a colon, and the word bug.

-

Jamie: So, is colon open space label colon bug.

-

Alex: Correct. When you press Enter, the page updates instantly to show only open issues that have the bug label.

-

Jamie: What if I want to find issues that are assigned to me?

-

Alex: You would type assignee colon at me. The at symbol followed by the word me is a special shortcut in GitHub that always refers to your own username. You can also type author colon at me to find issues you originally filed.

-

Jamie: That is really powerful. Are there other ways to filter besides typing these queries out? Sometimes I forget the exact syntax.

-

Alex: Absolutely. Right near the search bar, there is an actions toolbar with dropdown buttons for Labels, Milestones, and Assignees. You can Tab to the Label button, press Enter to open the dropdown, use your up and down arrows to find the label you want, and press Enter to select it. When you press Escape to close the dropdown, the list filters automatically.

-

Jamie: You mentioned milestones. What is a milestone?

-

Alex: A milestone is just a way to group issues together by a target date or a specific release. For example, a project might have a milestone called Version 2 point 0. Filtering by that milestone shows you all the issues that need to be finished before Version 2 point 0 can launch.

-

Jamie: Okay, so I have filtered the list, I found an issue that sounds interesting, and I pressed Enter on the heading to open it. What does the actual issue page look like?

-

Alex: The page has a very specific anatomy. At the very top, you have the issue title as a heading level 1. Right below that, your screen reader will announce a status badge, telling you if the issue is Open or Closed.

-

Jamie: And then comes the description?

-

Alex: Yes. The original post, which we call the issue body or description, comes next. But before you read it, it helps to know about the sidebar. On the right side of the screen visually, there is a sidebar containing metadata. It has sections for Labels, Assignees, and the Milestone. These are marked as heading level 3s.

-

Jamie: So if I want to quickly check who is assigned to an issue, I can just press the number 3 until I hear Assignees?

-

Alex: Exactly. It is a great way to orient yourself. But for reading the main description, you want to stay in Browse Mode. The description is usually formatted using Markdown, which means GitHub turns it into proper HTML. Headings are real headings, bullet points are real lists, and code blocks will actually announce as code.

-

Jamie: I love that. There is nothing worse than reading a wall of unformatted text. So I can just use my normal screen reader commands to read the description line by line.

-

Alex: Yes. And below the description is the timeline. This is the activity stream of the issue. Every comment left by another person is a heading level 3. So to read a conversation, you just press the number 3 to jump from comment to comment.

-

Jamie: Does the timeline only show comments?

-

Alex: Good question. No, it shows events too. If someone adds a label, or assigns someone, or references a pull request, those events appear in the timeline chronologically between the comments. They usually read as simple text paragraphs, like, Jamie added the bug label 2 days ago.

-

Jamie: Let us flip the script. Instead of reading an issue, I want to file a new one. I found a bug where my screen reader is not announcing a button state, and I want to report it.

-

Alex: That is a perfect use case. From the issues list page, you will want to navigate to the New Issue button. You can use the letter K to move through links until you find it, or use your buttons shortcut. Press Enter to activate it.

-

Jamie: Does it just give me a blank text box?

-

Alex: Sometimes. But many open source projects use Issue Templates. If they do, you will land on a page asking you to pick a template. You might hear options like Bug Report, Feature Request, or Accessibility Issue. You just find the one you want and press Enter on its Get Started button.

-

Jamie: Okay, I picked the Bug Report template. Now I am on a form with a title and a body. I remember when I filed my first issue, I just made the title, Screen reader bug. Was that a bad title?

-

Alex: It is not terrible, but it is not very helpful to the maintainers. Think of the title like a news headline. It needs to be specific. A much better title would be, Screen reader does not announce expanded state on the main navigation menu.

-

Jamie: That makes sense. It tells them exactly what is wrong and where. So I type that into the title field using Focus Mode. Then I Tab to the description field.

-

Alex: Right. And this is where you write the body of your issue. If you selected a template, the text area might already have some headings in it, like What Happened, What I Expected, and Steps to Reproduce. You just fill in the details under each heading.

-

Jamie: Can I use formatting here? Like making the steps an actual numbered list?

-

Alex: Absolutely. The text area supports Markdown. Because you are in Focus Mode while typing, you can use keyboard shortcuts. Control plus B makes text bold. Control plus E formats text as a code block. And Control plus Shift plus the number 7 creates a numbered list.

-

Jamie: Oh, I did not know about Control plus Shift plus 7. That is way faster than typing out the numbers manually. What about task lists? I have seen issues that have actual checkboxes in them.

-

Alex: Task lists are incredibly useful! You can create them by typing a hyphen, a space, a left bracket, a space, a right bracket, and another space. It looks a bit like a little text drawing of an empty box. When you submit the issue, GitHub renders that as a real, interactive checkbox.

-

Jamie: That sounds like a lot of steps. Hyphen, space, bracket, space, bracket.

-

Alex: It does! But here is the thing, you have already done most of this on Day 1 of your programming journey. It is just typing characters. And if you use VS Code to write your issue drafts, you can use extensions that handle the heavy lifting for you.

-

Jamie: That is a relief. So I have written my steps to reproduce. Is there anything specific I should include because it is an accessibility bug?

-

Alex: Yes, always include your environment details. Tell them exactly which screen reader and version you are using, like NVDA 2025 point 3. Tell them your browser and your operating system. A bug might happen on Firefox but not on Chrome, so that context is crucial for the maintainer trying to fix it.

-

Jamie: Okay, the issue is filed. What happens when someone replies? How do I comment back?

-

Alex: When you open the issue, you can jump straight to the comment box by navigating to the landmark called Add a comment. Or, if you prefer shortcuts, you can just press the letter R while reading a previous comment to reply and automatically quote their text.

-

Jamie: I love the R shortcut. Once I am in the text area, it is just like writing the issue body, right? Focus mode, type my reply, use markdown if I want to.

-

Alex: Exactly. And when you are ready to post it, you do not even need to Tab to the submit button. You can just press Control plus Enter from right inside the text area to submit your comment.

-

Jamie: What if someone leaves a comment that just says, I will look into this today. I want to acknowledge it, but leaving a comment that just says Thanks feels like it might clutter the timeline.

-

Alex: That is a brilliant observation. Open source maintainers get a lot of notifications, so adding a comment just to say thanks or I agree can sometimes be overwhelming. Instead, you should use Reactions.

-

Jamie: Reactions? Like emojis?

-

Alex: Yes. Reactions are a form of lightweight feedback. Every comment has a button to add a reaction. You can add a thumbs up, a heart, a smile, or even a rocket ship. It communicates your acknowledgement without sending an email notification or cluttering the thread.

-

Jamie: Analogy time! It is like nodding your head in a meeting. You are showing you understand and agree, without actually interrupting the speaker to say the word yes.

-

Alex: That is perfectly stated. Nodding in a meeting. Use reactions to nod.

-

Jamie: Let us talk about connecting things together. I have noticed people typing the number sign, or the hash symbol, followed by a number in their comments. What does that do?

-

Alex: That is how you cross-reference issues. Every issue and pull request has a unique number. If you are typing a comment and you type the number sign followed by 42, GitHub automatically turns that into a link pointing to issue number 42.

-

Jamie: Does it do anything besides make a link?

-

Alex: It does! It creates a two-way connection. If you mention issue 42 in your new issue, a timeline event automatically appears over on issue 42 saying that you referenced it. It is like a digital string tying the two documents together, so anyone reading either issue can find the other.

-

Jamie: That is so helpful for keeping track of related bugs. I also read something about magic closing keywords. What are those?

-

Alex: This is one of the best automations in GitHub. Let us say you open a pull request with code that fixes issue number 42. In the description of your pull request, you type the word Closes, followed by the number sign, and the number 42.

-

Jamie: Closes number 42.

-

Alex: Right. When your pull request is approved and merged into the project, GitHub sees that keyword and automatically closes issue 42 for you. You do not have to go back and do it manually. You can also use words like Fixes or Resolves.

-

Jamie: You mentioned closing an issue. As a beginner, closing an issue sounds scary. Like I am deleting it forever.

-

Alex: I completely understand that fear. But closing an issue does not delete anything. It just changes its state from Open to Closed. It is like crossing a task off your paper to-do list. You did not shred the paper, you just drew a line through the text. The history, the comments, and the decisions are all preserved permanently.

-

Jamie: So if I realize a bug is actually not fixed, can I un-cross it off the list?

-

Alex: Yes, you can. At the bottom of any closed issue, the Close Issue button changes into a Reopen Issue button. You just navigate to it, press Enter, and the issue is back in the Open state.

-

Jamie: Who normally closes issues? Can I close someone else's issue?

-

Alex: Usually, only the repository maintainers, or the person who originally opened the issue, have the permission to close it. This brings us to issue management. If you are a maintainer, or if you have write access to a repository, you can manage issues by assigning them and labeling them.

-

Jamie: How do I assign an issue to myself so people know I am working on it?

-

Alex: You go to the issue sidebar. Remember those heading level 3s? You navigate to the Assignees heading. Right next to it is a button to manage assignees. Press Enter to open it, type your username, and select yourself from the dropdown.

-

Jamie: And applying labels works the same way?

-

Alex: Exactly the same. Navigate to the Labels heading, open the menu, select the labels you want, and press Escape to close. Labels are crucial for organizing work. In fact, there is one specific label every beginner should know about. It is called good first issue.

-

Jamie: Oh, I have seen that one!

-

Alex: Maintainers use the good first issue label to mark bugs or tasks that are perfect for people who are new to the project. The scope is usually small, and the maintainer is willing to mentor whoever picks it up. If you are looking to make your first open source contribution, searching for is colon open label colon quote good first issue unquote is the best way to start.

-

Jamie: Everything we have talked about so far has been in the browser. But in earlier episodes, you showed me how to do things from my computer's terminal. Can I manage issues from the command line too?

-

Alex: You absolutely can, using the GitHub CLI. The command is g h space issue.

-

Jamie: What kind of things can I do with it?

-

Alex: Almost everything. If you open your terminal and type g h space issue space list, it prints out a list of all open issues right in your console. You can even filter it by typing g h issue list dash dash label bug.

-

Jamie: That is so fast. What if I want to read one?

-

Alex: You type g h issue view followed by the issue number. It will print the title, the description, and all the comments into your terminal. Because it is just plain text in your console, your screen reader will read it flawlessly without needing to navigate complex web page structures.

-

Jamie: Can I create an issue from the terminal too?

-

Alex: Yes, by typing g h issue create. It will launch an interactive prompt that asks you for the title, and then opens your default text editor so you can write the body. It is a fantastic alternative if you find web forms tedious.

-

Jamie: This has been incredibly helpful, Alex. I feel like I understand the flow of conversation on GitHub so much better now.

-

Alex: I am glad to hear that, Jamie. Let us recap the key takeaways for today. First, an issue is a dedicated discussion thread for a unit of work, like a bug report or a feature request.

-

Jamie: Second, use the search bar and filters to find what you need. Typing is colon open label colon bug will save you from reading through hundreds of irrelevant headings.

-

Alex: Third, when reading an issue, use your heading navigation. The title is a level 1, sidebar sections and comments are level 3s. Stay in Browse mode to read, and switch to Focus mode when typing your comments.

-

Jamie: Fourth, when filing an issue, be specific! Write a headline, not just a vague category. And remember to use Markdown to format your steps to reproduce clearly.

-

Alex: And finally, use the magic keywords like Closes number 42 in your pull requests to automatically close issues when your work is done. Connecting your work creates a clear history for everyone.

-

Jamie: Speaking of pull requests, I hear that is what we are covering next.

-

Alex: We certainly are. In our next episode, Working with Pull Requests, we will take the code you have written and learn how to propose it to a project. We will cover the review process, leaving inline comments, and finally getting that code merged. You will not want to miss it.

-

Jamie: I am looking forward to it. Thanks for listening, everyone!

-

Alex: See you next time on Gitt Going with GitHub.

-
- - -

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 6: Working with Pull Requests - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode six, Working with Pull Requests. I am Alex, and I am here to guide you through the accessibility of open source collaboration.

-

Jamie: And I am Jamie! I am here to ask the questions, share my own learning curve, and hopefully prevent you from making the same mistakes I did when I first started using GitHub a couple of years ago.

-

Alex: In our previous episodes, we covered a lot of foundational ground. In episode three, we talked about branches, which are safe parallel universes where you can experiment with code. And in episode five, we talked about issues, which are where we track bugs, feature requests, and discussions.

-

Jamie: Right. Issues are the conversation about the work that needs to be done, and branches are where you actually do the work. But that leaves a pretty big gap. How do we get the work from our experimental branch back into the main project?

-

Alex: That is exactly what a pull request is. A pull request, often just called a P R, is a formal proposal to merge the changes from your branch into another branch. I love the name because it is literal. You are requesting that the project maintainers pull your changes into their code.

-

Jamie: When I first started, I was constantly confusing issues and pull requests. They felt like the same thing because they both have titles, descriptions, and comment threads.

-

Alex: That is a very common point of confusion. Think of it like a restaurant. An issue is the order ticket. It says, we need a vegetarian pizza at table four. It describes the problem or the requirement. The pull request is the chef putting the finished pizza on the counter and saying, here is the food, can the manager verify it is vegetarian before we serve it?

-

Jamie: Oh, I like that. The issue is the work order. The pull request is the finished product waiting for inspection.

-

Alex: Exactly. An issue is just text and ideas. A pull request contains actual, modified code.

-

Alex: Before we talk about creating one, let us understand the anatomy of a pull request page on GitHub. When you navigate to a pull request, the page is divided into three main tabs.

-

Jamie: I use the landmarks for this. I press the D key to move through my ARIA landmarks until I hear Pull request navigation tabs.

-

Alex: Perfect. Inside that landmark, you will find three tabs. The first is the Conversation tab. This is where you will find the pull request description, the timeline of all comments, any automated status checks, and the merge button. It is the history of the proposal.

-

Jamie: The second tab is Commits. This is just a chronological list of the individual commits that make up your pull request. It is handy if you want to step through the author's thought process commit by commit.

-

Alex: And the third tab is Files changed. This is the heart of the pull request. It is where you go to read the diff. A diff is the before and after comparison of every single file that was modified. We are going to spend a lot of time talking about how to read a diff with a screen reader later in this episode.

-

Jamie: So, Conversation, Commits, and Files changed. That is the anatomy. How do we actually create one of these?

-

Alex: There are two main scenarios for creating a pull request. You are either creating it from a branch within the same repository, or you are creating it from a fork.

-

Jamie: Let us define those. A branch in the same repository is what we do at my company. We all have write access to the main repository, so I just create a branch called jamie dash new dash feature, do my work, and open a pull request.

-

Alex: Right. The analogy there is that you and your team all live in the same house. You are building a new cabinet in the garage, which is your branch. When it is done, you ask your roommates to help you move it into the living room, which is the main branch.

-

Jamie: But open source does not work like that, right? I cannot just go create a branch on the official Microsoft accessibility repository. They do not know me. They are not going to give me write access to their house.

-

Alex: Exactly. That is where forks come in. A fork is a complete, personal copy of someone else's repository that lives on your own GitHub account. You have full control over your fork. You can create branches there, commit code there, and break things there.

-

Jamie: So if the same repository branch is building a cabinet in the garage, a fork is building the cabinet at my own house across town.

-

Alex: Yes. And when the cabinet is finished, you load it into a truck, drive it over to the open source project's house, and submit a pull request asking if they want it. That is a cross-repository pull request. The beauty of GitHub is that the creation process is almost identical for both.

-

Jamie: When you push a new branch to GitHub, whether it is to your fork or the main repository, GitHub is pretty smart. If you navigate to the repository homepage shortly after pushing, you will usually find a banner with a button that says Compare and pull request. I just press Enter on that button.

-

Alex: That button is a fantastic shortcut. If you do not catch the banner in time, you can always navigate to the Pull requests tab and activate the New pull request button. When you do that, you have to select two things from a set of dropdown menus. The base branch, and the compare branch.

-

Jamie: I always used to mix those up. Base and compare.

-

Alex: It helps to read it as a sentence. You want to merge your compare branch into the base branch. The base is the foundation. It is the destination. Usually, this is the main branch of the project. The compare branch is your new work. You are asking GitHub to compare your work against the base.

-

Jamie: Once you select those, you land on the pull request form, which looks exactly like the form for creating a new issue. You have a title field and a description text area.

-

Alex: Writing a good pull request description is an art form. This is your chance to explain what changed, why it changed, and how the reviewer can test it.

-

Jamie: Please, please do not just name your pull request Fix bugs, and leave the description blank. I have been asked to review pull requests like that, and it is infuriating. I have no idea what I am supposed to be looking at.

-

Alex: A good title should be descriptive. Something like, Add keyboard navigation for the carousel component. For the description, many repositories provide a pull request template. If you tab into the description field and switch to Focus mode, you might find a checklist already waiting for you.

-

Jamie: If there is no template, I always try to include three things. First, a summary of what I did. Second, instructions on how to test my changes. And third, a link to the original issue.

-

Alex: Linking the issue is critical. If your pull request solves issue number forty two, you should type the word Closes, followed by a space, followed by the number sign, and the number forty two. Closes number forty two.

-

Jamie: GitHub has a magic feature where if you use that exact phrasing, the moment your pull request is merged, GitHub will automatically close issue forty two for you. It keeps the project so tidy.

-

Jamie: Okay, so what if I am working on that carousel keyboard navigation, and I have made some good progress, but I am stuck. The escape key is not closing the modal. I want to push my code and get your opinion, but I do not want you or the project maintainers to accidentally merge it, because it is broken.

-

Alex: This is the perfect time to use a draft pull request. A draft pull request is a way of putting a big, virtual Work In Progress sign on your code. It signals to the team that you are actively working on it, it allows you to ask for feedback, but the merge button is completely disabled. No one can merge it, not even the repository owner.

-

Jamie: How do I create a draft?

-

Alex: When you are on the form to create a new pull request, do not just activate the default Create pull request button. Next to it, there is a dropdown arrow button. If you activate that, you can select Create draft pull request instead.

-

Jamie: And when I finally figure out that escape key bug and I am ready for a real review, how do I remove the draft status? Do I have to open a new pull request?

-

Alex: Not at all. You just open your existing draft pull request, navigate to the Conversation tab, and scroll toward the bottom. You will find a button called Ready for review. Activating that button removes the draft status, turns on the merge button, and notifies everyone that you are ready for formal feedback.

-

Jamie: That is a relief. Okay, so my pull request is out of draft mode. It is open. But no one is looking at it. How do I get someone's attention?

-

Alex: You need to request a review. On the pull request page, there is a sidebar region. You can navigate to the Reviewers heading, which is a level three heading. Right below that, there is a button to request reviewers. Activating it opens a search field where you can type a teammate's username and select them.

-

Jamie: Sometimes I will open a pull request and I will notice that two people have already been requested as reviewers, and I did not even do it. It just happened automatically.

-

Alex: That is usually because of a file called CODEOWNERS. Many large repositories use this file to map specific folders to specific people. If you modify a file in the accessibility folder, GitHub automatically requests a review from the accessibility team. You cannot remove them; their approval is required.

-

Alex: So far, we have been the author. Now, let us flip the script. Jamie, I just requested your review on my pull request. You get an email notification, you follow the link, and you are on my pull request page. What is your workflow?

-

Jamie: The first thing I do is read your description on the Conversation tab so I know what you are trying to achieve. But then, I immediately move to the Files changed tab. That is where the truth is. The description is what you think you did. The Files changed tab is what you actually did.

-

Alex: And this is where we need to talk about screen reader navigation, because reading a code diff can be intimidating at first. When you activate the Files changed tab, GitHub presents a file tree on the left, and the actual diffs on the right.

-

Jamie: I love the file tree. I press D to navigate to the File tree region. It is a list of every file you modified. I can use my up and down arrows to hear the file names. It gives me a high level map of the damage you did to the codebase.

-

Alex: Once you are ready to read the code, you can use heading navigation. Every changed file is a level three heading. So you can press the number 3 to jump from file to file.

-

Jamie: When I land on a file heading, how do I actually read the changes?

-

Alex: Each file's diff is structured as an HTML table. So, from the file heading, press T to jump into the diff table. Then, switch your screen reader to Focus mode, or Forms mode. If you are using NVDA, that is Insert plus Space. For JAWS, it is Insert plus Z. For VoiceOver, you interact with the table.

-

Jamie: Once I am in the table in Focus mode, I just use my down arrow to read line by line.

-

Alex: Exactly. And the screen reader will announce the changes. Because we cannot rely on the visual layout, we listen for specific prefixes. If a line was added, your screen reader will announce a plus sign, or the word inserted, followed by the code. If a line was removed, it will announce a minus sign, or the word deleted.

-

Jamie: And if a line has no plus or minus, it is just context. It is unchanged code that GitHub shows you so you know where you are in the file.

-

Alex: So you are arrowing down through the table, and you hear a minus sign followed by an old heading level, and then a plus sign followed by a new heading level. You realize I made a mistake. How do you tell me?

-

Jamie: I leave an inline comment. This is so much better than just leaving a generic comment at the bottom of the page saying, hey Alex, on line forty two of that one file, you messed up. Instead, while my focus is on the specific line in the diff table, I press the Tab key.

-

Alex: When you press Tab from a focused line in the diff table, you will land on a button called Add a comment to this line.

-

Jamie: I press Enter on that button, and a text area opens right there in the middle of the code. I switch back to Focus mode, and type my comment. I will say, Alex, this heading level skips from a level two to a level four. We need a level three here for screen reader users.

-

Alex: Now, this next part is crucial. Once you type your comment, you will see two buttons. One says Add single comment. The other says Start a review. Always, always choose Start a review.

-

Jamie: I learned this the hard way! When I first started, I was using Add single comment for everything. I reviewed a massive pull request and left twenty inline comments.

-

Alex: And because you used Add single comment, GitHub sent the author twenty separate email notifications, one after another. Ding, ding, ding.

-

Jamie: They were not happy with me. When you choose Start a review, GitHub saves your comment as pending. It batches them all together. You can go through the rest of the files, leave five more comments, and the author hears nothing.

-

Alex: Once you have finished reading all the files and leaving your pending comments, you need to submit the review. You navigate to the Review changes button. It is usually at the top of the Files changed tab, or at the bottom of the Conversation tab.

-

Jamie: When you activate the Review changes button, a dialog opens. You can type an overall summary, like, Great work, just a few heading issues to fix. And then you have to choose a verdict using a set of radio buttons.

-

Alex: The three radio buttons are Comment, Approve, and Request changes. Comment means you are just leaving general feedback, but you are not blocking the merge. Approve means the code looks great and you are giving it a green light. Request changes means you found a blocking issue, and the pull request cannot be merged until the author fixes it.

-

Jamie: I select Request changes, tab to the Submit review button, and press Enter. At that exact moment, GitHub bundles all my inline comments and my summary into one single email notification and sends it to you.

-

Alex: It is a much kinder workflow. Now, I want to take a brief detour, because there is an alternative way to review code that is incredibly popular among screen reader users.

-

Jamie: Yes! VS Code!

-

Alex: Right. Reading diffs in a web browser table works, but it can be tedious. If you use Visual Studio Code and install the GitHub Pull Requests extension, you can check out the pull request locally.

-

Jamie: And the best part of doing it in VS Code is the Accessible Diff Viewer. When you have a diff open in VS Code, you just press F 7.

-

Alex: F 7 opens a dedicated panel designed specifically for screen readers. Instead of making you navigate a complex table, it extracts every change into a linear list. You just press F 7 to jump from change to change.

-

Jamie: It is so clean. It literally announces, Change one of three. Removed, heading level two. Added, heading level three. It takes all the mental gymnastics out of reading a diff. You can still leave inline comments right from VS Code, and they sync perfectly back to GitHub.

-

Alex: It is a phenomenal feature. Another alternative, if you are a terminal power user, is the GitHub CLI. You can type g h space p r space list to see all open pull requests. You can type g h space p r space diff to output the code changes straight to your terminal, which is very easy for a screen reader to read sequentially. You can even approve a pull request by typing g h space p r space review dash dash approve.

-

Jamie: I love having options. Browser, VS Code, or Terminal. You use whatever fits your brain best.

-

Alex: Okay, so let us look at the timeline. I opened the pull request. You reviewed it and requested changes. I fixed the heading levels and pushed a new commit. You reviewed it again, and this time, you selected Approve. Are we ready to merge?

-

Jamie: Almost. We have to check the bots first.

-

Alex: Ah yes, the Status Checks. On the Conversation tab, right below the description, there is a section for status checks. These are automated scripts that run every time you push code. They might run accessibility linters, unit tests, or security scanners.

-

Jamie: You can navigate to the Status checks heading to read the results. You want to hear All checks have passed. If you hear Some checks failed, the merge button might be blocked. You have to navigate to the specific failing check, open its logs, and figure out what broke.

-

Alex: Assuming your review is approved and all status checks have passed, it is time to merge. If you are a project maintainer, you will navigate to the bottom of the Conversation tab to the merge controls. But you have a choice to make. There are three different merge strategies.

-

Jamie: This used to terrify me. The dropdown gives you three options: Create a merge commit, Squash and merge, or Rebase and merge. What is the difference?

-

Alex: Let us use an analogy. Imagine your pull request is a business trip, and your commits are the receipts. You have a commit for your flight, a commit for your hotel, a commit for a coffee, and a commit where you bought a pen.

-

Jamie: Okay, I have four commits. Four receipts.

-

Alex: If you choose Create a merge commit, you are taking all four individual receipts, putting them in an envelope, writing Business Trip on the envelope, and handing it to accounting. The main branch keeps every single commit exactly as you wrote it, plus one extra commit, the envelope, that ties them together.

-

Jamie: So the history shows all the messy details. The coffee, the pen, everything.

-

Alex: Right. The second option is Squash and merge. If you choose squash, you take all four receipts, add up the total, throw the individual receipts in the trash, and hand accounting a single piece of paper that says Business Trip Total: eight hundred dollars.

-

Jamie: Oh, I see. It squashes all my messy, incremental commits into one single, polished commit on the main branch. I use this all the time because my commit history is usually terrible. I will have commits named oops, and fixed typo again. Squashing hides my shame.

-

Alex: Exactly. Squash and merge keeps the main project history incredibly clean. One pull request equals one commit.

-

Jamie: What about Rebase and merge?

-

Alex: Rebase is like a time machine. Imagine you started your business trip a month ago, but accounting only wants receipts from this week. Rebase takes your four individual receipts, erases the dates, and stamps today's date on all of them. It replays your commits one by one onto the tip of the main branch, as if you had just written them today.

-

Jamie: No envelope, no squashing. Just taking my work and sticking it perfectly at the end of the line.

-

Alex: Exactly. Which strategy you use depends on the repository. Many open source projects enforce Squash and merge to keep their history readable. Just check the dropdown, select the strategy the project prefers, and activate the button.

-

Jamie: And just like that, the pull request status changes to Merged. The code is officially part of the project.

-

Alex: We have covered the entire lifecycle of a pull request today. Let us recap the key takeaways. First, a pull request is a proposal to merge code, while an issue is a discussion about work to be done.

-

Jamie: Second, use Draft pull requests when your work is not ready for review. It tells the team you are experimenting, and prevents accidental merges.

-

Alex: Third, when reviewing code in the browser, use the T key to jump to the diff table, and use Focus mode to read the changes line by line. Listen for the plus and minus announcements. And remember, always use Start a review to batch your inline comments, rather than sending a notification for each one.

-

Jamie: And finally, do not forget about the F 7 Accessible Diff Viewer in VS Code. If navigating browser tables is giving you a headache, the VS Code extension is an absolute game changer for screen reader users.

-

Alex: In our next episode, we are going to tackle the one topic that strikes fear into the heart of every developer, blind or sighted. We are going to talk about Merge Conflicts. What they are, why they happen, and how to resolve them accessibly without panicking.

-

Jamie: I have panicked many times. I am looking forward to learning how not to.

-

Alex: Until then, keep exploring, keep committing, and we will see you next time on Gitt Going with GitHub.

-
- - -

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 7: Merge Conflicts Are Not Scary - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub, the audio series for blind and low-vision developers learning the ins and outs of open source collaboration. I am Alex, and I am here with Jamie.

-

Jamie: Hi everyone! I am so ready for this one.

-

Alex: Today we are on episode seven, and the title of this episode is Merge Conflicts Are Not Scary.

-

Jamie: I am going to hold you to that title, Alex. Because when I was learning GitHub two years ago, the phrase merge conflict literally made my stomach drop. It sounds like an error. It sounds like I broke the project and now the developers are fighting.

-

Alex: That is exactly why we named the episode this way. A merge conflict is not an error, it is not a failure, and it definitely does not mean anyone is fighting. It is just a normal, everyday part of writing code with other people. Before we dive into what they are, let us quickly recap where we are in the workflow. In episode three, we talked about branches and commits, which is how you save your own independent line of work. Then in episode six, we talked about pull requests and merging, which is how you ask to bring your work into the main project.

-

Jamie: Right. A pull request is you saying, here are my changes, please pull them into the main branch. And usually, you hit the merge button, and GitHub just combines everything perfectly.

-

Alex: Exactly. Git is incredibly smart. If you edit a file at the top, and I edit the same file at the bottom, Git just quietly combines them. No problem. But a merge conflict happens when two people change the exact same lines of the exact same file in different ways. Git is smart, but it is not going to guess which version is the correct one. So it stops and asks a human to decide.

-

Jamie: I always think of it like two people editing the same paragraph of a shared document. Let us say we have a workshop welcome document. I go in and change the opening sentence to say, Welcome to the GitHub Workshop. But before I save and share my version, you go in and change that exact same sentence to say, Welcome Developers. If we try to combine our documents, the system throws its hands up. It cannot keep both sentences without it sounding like nonsense, and it does not want to automatically delete someone's work.

-

Alex: That is a perfect analogy. Git is doing the exact same thing. It is pausing the merge and saying, hey, I have two different versions of line twelve. Which one do you want? Or do you want to combine them yourself? That pause, that request for human intervention, is all a merge conflict is.

-

Jamie: Okay, so it is not an error. It is just Git asking a question. But how does it actually ask? When I am working on a pull request, how do I even know a conflict happened?

-

Alex: If you are on the GitHub website, navigating through your pull request, you will move to the Conversation tab. Usually, at the bottom of that tab, you find the button to merge your pull request. But if there is a conflict, that merge button will be disabled. Instead, your screen reader will announce a section that says, this branch has conflicts that must be resolved.

-

Jamie: I remember hearing that for the first time. It feels like a roadblock. But right next to that message, there is a button called Resolve conflicts.

-

Alex: Yes. And activating that Resolve conflicts button takes you into the GitHub web editor. This is a built in tool that lets you fix the conflict right there in your browser, without needing any terminal commands or local software.

-

Jamie: So what actually happens when I activate that button? I know it opens an editor, but what does the text inside look like? How does Git show me the two different versions?

-

Alex: This is where we need to talk about conflict markers. When Git finds a conflict, it actually edits the file for you to inject both versions of the code, separated by very specific markers. These markers are just plain text characters.

-

Jamie: And they can sound really weird the first time a screen reader reads them out to you.

-

Alex: They really can. There are three markers you need to know. The first marker indicates the start of your version of the code. It is seven less than signs, followed by a space, and the word HEAD. H E A D.

-

Jamie: So your screen reader might literally say, less than less than less than less than less than less than less than HEAD. Or if your punctuation level is set lower, it might just say HEAD. That is why it is good to navigate line by line and examine the characters if something seems strange.

-

Alex: Exactly. The word HEAD in Git just means your current location, the branch you are currently working on. So right below that less than HEAD marker, you will find your code. The code you wrote.

-

Jamie: Okay, so that is my version. What comes next?

-

Alex: Next is the dividing line. It is seven equals signs. Just a row of equals signs. This separates your version from the other person's version.

-

Jamie: Equals equals equals equals equals equals equals. Got it. And below the equals signs?

-

Alex: Below the equals signs is the incoming version. The code coming from the main branch, or from whoever else edited the file. And finally, to mark the end of the conflict area, there is a third marker. It is seven greater than signs, followed by a space, and the name of the branch that the incoming code is coming from.

-

Jamie: So greater than greater than greater than, and then maybe the word main, or the name of my teammate's feature branch.

-

Alex: Exactly. So the structure is always the same. Less than signs for the start of your code. Your code. Equals signs for the divider. Their code. Greater than signs for the end of the conflict.

-

Jamie: So let us make this concrete. Imagine we are editing an HTML file. I am working on a button. Originally, the button just said Submit. On my branch, I changed the button text to say Send message. But someone else on the team added an accessibility label to the original button. They added an aria label that says Submit form.

-

Alex: That is a very realistic scenario. Since you both changed the exact same line of HTML, you get a conflict. When you open the web editor and navigate line by line, here is what you will read. First, the less than signs and the word HEAD. Next line, your code, which is the button with the text Send message. Next line, the seven equals signs. Next line, the incoming code, which is the button with the aria label Submit form. And finally, the greater than signs and the branch name.

-

Jamie: So my job is to just edit this text file, right?

-

Alex: That is the entire job. You are just in a text editor. You need to look at both versions and decide what the final code should be. In this case, you probably want both improvements. You want the new text, and you want the aria label.

-

Jamie: So I would just type out a new line of code that combines them. A button with the aria label Submit form, and the text Send message.

-

Alex: Perfect. And then, this is the most important part, you must delete the conflict markers. You have to delete the line with the less than signs, the line with the equals signs, and the line with the greater than signs. You also delete the old versions of the code that you no longer need. When you are done, the file should just look like normal, working code.

-

Jamie: That is a huge aha moment for a lot of people. The markers are not special protected code. They are literally just text that Git temporarily typed into your document so you could find the conflict. You just delete them when you are done.

-

Alex: Exactly. Once you have deleted the markers and the code looks correct, you navigate to the top of the file in the GitHub web editor and activate the Mark as resolved button. If you have multiple files with conflicts, there is a file navigation panel you can reach with your screen reader commands, like N V D A plus F seven, or VoiceOver plus U, to move to the next file. Once all files are marked as resolved, you activate the Commit merge button. And you are done. The conflict is gone.

-

Jamie: Okay, that is the web editor. But what if I am working locally on my own computer, using the command line? I know a lot of developers prefer to handle things in their terminal.

-

Alex: The concept is exactly the same, but the steps are a bit different. Let us say you are in your terminal and you type git space merge space main, to bring the main branch into your feature branch. Git will try to merge, but then it will output a message that says, Automatic merge failed. Fix conflicts and then commit the result.

-

Jamie: Hearing automatic merge failed definitely sounds scary the first time.

-

Alex: It does! But again, it is just Git saying it needs a human. If you type git space status, it will list your files and tell you which ones are in conflict. It will say, both modified, and then the file name.

-

Jamie: So if I see both modified, I just open that file in my normal code editor, like VS Code or Notepad?

-

Alex: Exactly. You open the file, and you will find those exact same conflict markers. The less than signs, the equals signs, and the greater than signs. You edit the text, combine the changes, and delete the markers, just like we discussed.

-

Jamie: And since I am doing this on the command line, how do I tell Git that I finished fixing it? There is no Mark as resolved button in my terminal.

-

Alex: Great question. On the command line, marking a file as resolved is done by staging it. You just type git space add space, and then the file name. That tells Git, hey, I fixed this file, it is ready to go. Once you have used git add on all the conflicted files, you just type git space commit. Git will automatically create a message saying it is a merge commit, and you just save and close it.

-

Jamie: So the workflow is git merge, which triggers the conflict. Then git status to find the files. Open the files and delete the markers. Then git add to mark them as resolved. And finally git commit to seal the deal.

-

Alex: You got it. And for those of you who will be using VS Code on day two of the workshop, it gets even easier. VS Code has built in tools for this. When you open a conflicted file, it adds invisible action links right above the conflict, which you can reach by pressing Tab. These links are called CodeLens actions.

-

Jamie: Oh, I love CodeLens. It is so much faster.

-

Alex: It really is. Your screen reader will read options like Accept Current Change, which keeps your code. Accept Incoming Change, which keeps their code. Or Accept Both Changes. You just press Enter on the one you want, and VS Code automatically deletes the markers and formats the code for you. You just save with Control plus S, stage the file with Control plus Shift plus G, and commit.

-

Jamie: And if you are using GitHub Copilot, you can press Control plus Shift plus I to open Copilot Chat and ask it to explain the conflict to you. You can say, explain what these two changes are trying to do. But a quick warning here, you should always understand how to read the markers yourself before relying on AI. You need to verify that the final code actually makes sense.

-

Alex: Absolutely. Now, before we move on, I want to mention a couple of really handy commands if you are using the GitHub Command Line Interface, or the G H tool. Sometimes you want to check if a pull request has conflicts before you even try to merge it.

-

Jamie: Right, because maybe I am reviewing someone else's pull request from my terminal.

-

Alex: Exactly. You can type the command G H space P R space checks, followed by the pull request number. This will tell you the status of the pull request. You can also type G H space P R space view, which will output a summary, and it will clearly state if the branch has conflicts that must be resolved. If you want to see the actual changes, G H space P R space diff will show you line by line what was added and removed.

-

Jamie: That is super helpful for staying in the terminal and not having to bounce back and forth to the browser just to check the status.

-

Alex: So we have talked about how to resolve conflicts. But there is a famous saying in software development. Prevention is easier than resolution.

-

Jamie: Yes! Let us talk about how to avoid these in the first place. Because while they are not scary, they do take time to fix. What is the best way to prevent merge conflicts?

-

Alex: The number one rule is to keep your branches short lived. If you create a branch and work on it for three weeks without merging it, the main branch is going to change dramatically in that time. When you finally try to merge, you are going to have a massive conflict.

-

Jamie: So target one to three days. Keep your changes small and focused. If you are building a huge feature, break it down into smaller pull requests. A pull request that changes five files merges easily. A pull request that changes fifty files is almost guaranteed to conflict with something.

-

Alex: Rule number two is to sync with the main branch frequently. If you are working on a branch for a few days, start your morning by pulling the latest changes from main into your branch. You can do this with git space pull space origin space main. This brings in everyone else's approved work. If there is a small conflict, you catch it early and fix it locally, rather than waiting until the very end.

-

Jamie: I also want to add communication to this list. Especially in our workshop environment. If you know you are going to be editing the workshop welcome document, leave a comment on your issue saying, heads up, I am working on the welcome document today. That way, if another student is also assigned a challenge that touches that file, they can coordinate with you.

-

Alex: Communication is huge. Another common trap is mass reformatting. Let us say you open a file and notice the indentation is a bit messy, so you run a tool that reformats all five hundred lines of the file.

-

Jamie: Oh no. I have done this.

-

Alex: We all have! The problem is, Git sees that as you changing all five hundred lines. If anyone else on your team changed even one line of logic in that file, you will create a conflict. If you need to reformat a file, do it in a separate, dedicated pull request, announce it to your team, and get it merged immediately before anyone else does work in that file.

-

Jamie: That makes so much sense. What about fast forward merges? I have heard that term thrown around.

-

Alex: A fast forward merge is the ideal scenario. It happens when your branch is perfectly up to date with main, and you just added new commits on top. Because there are absolutely no diverging changes, Git does not even need to create a merge commit. It just fast forwards the main branch to point to your latest commit. Zero chance of conflicts. You can achieve this by rebasing your branch on main right before you merge, but rebasing is an advanced topic that rewrites history, so we will save the deep dive on that for another time.

-

Jamie: Okay, Alex. I have tried to keep my branches small. I tried to communicate. But I still got a massive conflict, and I am sitting here looking at a file with ten different conflict markers, and I honestly do not understand what the incoming code is trying to do. I am stuck. What do I do?

-

Alex: The first thing you do is take a breath. The second thing you do is ask for help. It is completely normal and expected to ask for help with a merge conflict. You can go to your pull request on GitHub, leave a comment, and tag the author of the incoming changes. You can say, hey, I have a merge conflict in the index file, and I am not sure which version to keep. Could you help me understand the intent of your changes?

-

Jamie: People love when you ask that, by the way. It shows you care about not breaking their code.

-

Alex: Exactly. And if the conflict is just completely overwhelming, maybe your branch is weeks old and everything has changed, there is always the nuclear option.

-

Jamie: The nuclear option?

-

Alex: Abandon the branch and start fresh.

-

Jamie: Oh, wow. Is that allowed?

-

Alex: It is absolutely allowed, and sometimes it is the smartest move. You just close your pull request without merging it. You switch back to the main branch, make sure it is up to date, and create a brand new branch. Then, you just manually apply your specific changes to the new branch. Sometimes copying your logic over to a fresh, up to date branch takes ten minutes, whereas untangling a massive merge conflict could take hours. Starting over is not a failure. It is a legitimate strategy.

-

Jamie: I love that. It takes so much pressure off. If I mess up resolving a conflict, or if it is too confusing, I can just close it and start over. I have not ruined the project.

-

Alex: You definitely have not. Your first conflict resolution is always the hardest. It feels abstract and dangerous. But once you resolve one, once you delete those less than and greater than signs and see your code merge successfully, you will realize it is just a text editing puzzle.

-

Jamie: This has been incredibly helpful. Let us wrap up with some concrete takeaways for everyone listening.

-

Alex: Takeaway number one. A merge conflict simply means two people changed the same lines of the same file, and Git needs a human to pick the correct version. It is normal, healthy collaboration.

-

Jamie: Takeaway number two. Conflict markers are just text injected into your file. Less than signs for your code, equals signs for the divider, and greater than signs for the incoming code. Your only job is to edit the text to look how you want, and delete the marker lines.

-

Alex: Takeaway number three. You can resolve conflicts right in the browser using the GitHub web editor, or locally using git status, git add, and git commit. If you use VS Code, take advantage of the CodeLens features to accept changes with a single keystroke.

-

Jamie: And takeaway number four. Prevention is the best medicine. Keep your pull requests small, sync with the main branch frequently, and communicate with your team about what files you are touching. And if you get stuck, it is always okay to ask for help or just start a fresh branch.

-

Alex: Perfectly summarized. That is all for episode seven. In our next episode, we are shifting gears to talk about Culture and Etiquette. We will cover how to write a great issue, how to review someone else's code kindly, and the unwritten rules of open source communication.

-

Jamie: I cannot wait for that one. See you all next time!

-

Alex: Thanks for listening to Gitt Going with GitHub. Happy coding.

-
- - -

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 8: Open Source Culture and Etiquette - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is Episode 8: Open Source Culture and Etiquette. I am Alex, and today we are shifting gears. Over the past few episodes, we have covered the mechanical side of GitHub. We talked about branches, commits, pull requests, and resolving merge conflicts. But today, we are focusing on the human side of open source software.

-

Jamie: Hi everyone, Jamie here. And I have to admit, this is the topic that intimidated me the most when I was learning GitHub two years ago. The terminal commands were tricky, sure, but the idea of talking to strangers on the internet, asking them to accept my code, and worrying I might say the wrong thing or break some unwritten rule? That was terrifying.

-

Alex: That is such a common feeling, Jamie. And it makes perfect sense. Technical skills get your code into a project, but communication skills are what keep you welcomed in the community. When you are contributing to open source, you are stepping into a pre-existing community. It is like walking into a crowded room where everyone already knows each other. You want to be polite, clear, and respectful. So today, we are going to demystify the unwritten rules of open source communication.

-

Jamie: I love that. Where do we start?

-

Alex: Let us start with the nature of the communication itself. Open source collaboration happens primarily in writing, asynchronously, and in public. Understanding those three characteristics shapes everything we do. Because we communicate entirely in writing, we have to think very carefully about how tone comes across in text without vocal cues.

-

Jamie: Right. There is no tone of voice, no body language, no immediate way to see if someone is confused or offended. It is like when you get a text message from a friend that just says, "Fine." with a period at the end. In person, they might say it with a smile, meaning "sounds good." But in text, that period makes it feel incredibly aggressive.

-

Alex: Exactly. A message that sounds perfectly neutral or just a bit brief in your head can read as hostile to the person on the other end. Sarcasm and irony are nearly impossible to convey safely, so it is best to avoid them entirely. The unwritten rule here is to be relentlessly explicit and assume good intent. Instead of saying, "This is problematic," you might write, "I think this approach might cause an issue with keyboard navigation because of the following reasons."

-

Jamie: And because it is asynchronous, you are not having a real-time chat. When I first started, I would leave a comment and just sit there waiting for a reply, getting anxious. But the maintainer might live on the other side of the world and be asleep.

-

Alex: Precisely. Comments are not instant messages. You might be in a rush, but the reader is not receiving that urgency from your message. This means you need to provide all necessary context in every single message. Do not assume continuity. If you solved a problem, do not just write "Fixed it." Explain what you fixed and how, because the person reading it tomorrow will not have the context of what you were doing today. And finally, remember that everything is in public. Write as if your most supportive mentor and your most critical reviewer are both reading your comments, because anyone on the internet can find them.

-

Alex: Now that we understand the environment, let us talk about the two main ways you will communicate: issues and pull requests. Let us start with writing a good issue description. Jamie, how would you define an issue?

-

Jamie: An issue is basically a ticket. It is how you report a bug, request a new feature, or ask a question about the project.

-

Alex: Perfect. And writing a good issue description comes down to three things: context, steps to reproduce, and expected versus actual behavior. Think of it like taking your car to a mechanic. If you just drop the car off and say, "It makes a noise," the mechanic has no idea where to start. But if you say, "When I am driving over forty miles per hour and I press the brake pedal, the front left tire makes a grinding noise," the mechanic can replicate the exact conditions to find the problem.

-

Jamie: That makes so much sense. So for a software bug, context means explaining your environment. Like, "I am using Windows Eleven, with the NVDA screen reader, on the latest version of Firefox."

-

Alex: Exactly. Then you list the exact steps to reproduce the problem. For example, "Step one: Navigate to the login page. Step two: Enter a valid username but leave the password field blank. Step three: Press the Submit button."

-

Jamie: And then the expected versus actual behavior. So I would say, "Expected behavior: The screen reader announces 'Password is required'. Actual behavior: The screen reader announces nothing, and focus is lost."

-

Alex: You nailed it. That level of detail saves the project maintainer hours of debugging time. Even if you do not know how to fix the bug yourself, writing an issue description that clear is a massive contribution to the project.

-

Jamie: Okay, so that is issues. What about writing a good PR description? Remind me, PR stands for pull request, right?

-

Alex: Yes. A pull request, and I love that name because you are literally requesting that someone pull your changes into their project. When you open a PR, you need to provide a description. A good PR description needs to answer three questions: what did you change, why did you change it, and how can the reviewer test it.

-

Jamie: I remember my very first PR. I fixed a typo in a documentation file. My description just said, "Fixed typo." I thought I was being efficient!

-

Alex: It is a common mistake! But remember, the maintainer might be reviewing twenty pull requests that day. A better description would be: "What: Fixed a spelling error in the installation guide. Why: The command to install the package was missing a letter, which caused an error when users copied and pasted it. How to test: Read the installation section and verify the command is now correct."

-

Jamie: That is so much better. It is like handing over your shift at a job. You do not just hand the next person the keys and walk away. You tell them what happened during your shift, why you made certain decisions, and what they need to check on next.

-

Alex: That is a brilliant analogy. And here is a quick tip for our listeners using screen readers. When you are writing these descriptions on GitHub, you are often typing the same phrases over and over. GitHub has a feature called Saved Replies. You can save text snippets and insert them into any comment box. You just navigate to the comment text area, activate the Saved Replies button in the toolbar, or press Control plus period, and you can filter through your saved templates. It is a huge accessibility win to avoid retyping standard issue formats.

-

Jamie: Okay, so we know how to write issues and pull requests. Let us talk about the rules of the community itself. When I look at an open source project, I almost always see a file called Code of Conduct. What exactly is that, and why does it exist?

-

Alex: The Code of Conduct is essentially the social contract of the project. It is the house rules for a community center. It outlines what behavior is expected and what behavior is unacceptable. It exists to protect contributors, especially those from marginalized groups, from harassment, discrimination, or abuse. When you see that file, it signals that the maintainers take community health seriously and that there is a formal process for reporting violations.

-

Jamie: It is reassuring to know it is there. And I imagine a big part of following the Code of Conduct is using inclusive language. Why does inclusive language matter so much in open source?

-

Alex: Open source is global. You are collaborating with people from different cultures, people who speak different languages, and people with different life experiences. Inclusive language ensures we do not accidentally alienate or demean anyone. For example, using words like "crazy" or "insane" to describe a piece of code can be stigmatizing. Instead, we can use precise words like "complex", "unpredictable", or "difficult to maintain."

-

Jamie: Oh, I have another example! When I was starting out, I hated reading documentation that said, "Obviously, you just run this command," or "Simply do this." When it did not work for me, or I did not understand it, the word "obviously" made me feel like I was stupid.

-

Alex: Yes! Words like "obviously", "simply", or "just" are alienating. What is obvious to a senior developer is not obvious to a beginner. The easiest fix is to just omit those words entirely. Instead of "Obviously, this function returns a string," you write, "This function returns a string." It is cleaner and kinder.

-

Jamie: Another thing I learned is to focus on the code, not the person. Instead of saying, "You made a mistake here," you say, "There is an error on line forty." It takes the ego out of it.

-

Alex: Exactly. Preferring the word "we" is also a great strategy. "We need to update this logic," rather than "You need to update this logic." It frames the project as a collaborative effort. And when it comes to inclusive commenting specifically for accessibility issues, precision is key. Do not generalize and say, "This website is completely unusable for blind people." That might not be accurate, and it can sound dismissive. Instead, represent the specific gap. Frame it as, "Because the submit button lacks an accessible name, users relying on screen readers cannot determine its purpose." Quote your exact screen reader output, and specify whether you are using JAWS, NVDA, or VoiceOver, because the experiences can differ.

-

Jamie: Let us move on to the part of open source that used to make me sweat: Code Review. This is when you submit your pull request, and other developers examine your code before it gets merged. How do we handle giving and receiving code review feedback gracefully?

-

Alex: Let us start with giving code review feedback. The golden rule is to be specific, be kind, and focus on the code. Think of yourself as a peer editor in a writing class, not a teacher grading a test. We teach a five-step anatomy for helpful feedback.

-

Jamie: I have my notes ready. What are the five steps?

-

Alex: Step one: Acknowledge what is working. Before identifying problems, name what is good. This is not empty flattery; most contributions have real strengths. Step two: Identify the specific concern. Vague feedback like "This is inaccessible" is useless. Be precise. Step three: Explain why it matters. Context turns a complaint into a lesson.

-

Jamie: Okay, so if I say, "This button has no accessible name," that is step two. Step three would be adding, "Without an accessible name, a screen reader will just announce 'button,' which gives the user no context."

-

Alex: Exactly. Step four is: Suggest a path forward. Offer an idea, like, "Something like an aria-label would work well here." And finally, step five: Signal the weight of the concern. Help the contributor understand if this is a hard blocker that must be fixed before merging, or just a minor preference.

-

Jamie: I see the word "nit" used a lot in reviews. Like N I T. What does that mean?

-

Alex: "Nit" is short for nitpick. It is a way of saying, "This is a very minor, optional suggestion. Feel free to ignore it." Like pointing out a trailing space or a slight formatting preference.

-

Jamie: Let us try an exercise. I am going to give you a harsh comment, and you rewrite it using those steps. Here is the comment: "This alt text is bad. Fix it."

-

Alex: Oh, that is a rough one. Okay, here is how I would rewrite it. First, acknowledge something good. "Nice catch adding this image, it really helps illustrate the step." Then, the concern and the why. "I noticed the alt text just says 'image one dot PNG'. Screen reader users will hear the filename instead of what is actually in the picture." Finally, the suggestion. "Could you describe what the screenshot shows, like 'Settings page with the Accessibility section expanded'? That way everyone gets the same information."

-

Jamie: Wow. If I received the first comment, I would want to quit the project. If I received your rewritten comment, I would feel encouraged and immediately know how to fix it.

-

Alex: That is the power of good communication. Now, let us talk about receiving code review feedback. The most important rule: do not take it personally.

-

Jamie: This was so hard for me! When I got my first PR reviewed, the maintainer left six comments requesting changes. I felt like I had failed. I thought, "Well, they hate my code, I am a terrible developer."

-

Alex: That is imposter syndrome talking. Code review is a normal, healthy part of the software development lifecycle. Even the most senior developers in the world get change requests on their pull requests. It is about making the code robust, not about judging your worth as a developer. When you receive feedback, take a breath. Look for the valid concern underneath the words. And always say thank you. When someone takes the time to review your work, acknowledge it.

-

Jamie: What if I disagree with the feedback? What if they tell me to change something, but I know my way is actually better for accessibility?

-

Alex: That is a great question. You need to know how to disagree respectfully. First, make your case once, clearly, and provide evidence. You might say, "I considered using an 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." You explain your choice.

-

Jamie: And if they still say no?

-

Alex: Then you have to accept that the maintainer has the final say in their project. It is their house. If you strongly disagree, the beauty of open source is that you can always fork the project and take it in a different direction. But fighting endlessly in a comment thread is not productive.

-

Jamie: Speaking of maintainers, I think it is important to talk about who these people actually are. When I started, I pictured a team of paid professionals sitting in a corporate office, waiting to review my code.

-

Alex: That is a very common misconception. The reality is that the vast majority of open source maintainers are volunteers. They have day jobs, families, and lives outside of GitHub. They are maintaining these projects in their spare time, out of passion or a sense of community. Understanding that maintainers are volunteers with limited time completely changes how you should interact with them.

-

Jamie: Right. It means practicing patience with response times. If you open a pull request on a Friday night, do not leave a comment on Saturday morning asking why no one has reviewed it yet.

-

Alex: Exactly. Think of it like a community garden. The people managing it are doing it because they love gardening, not because it is their full-time job. If you plant some seeds and ask the manager a question, you might have to wait until they come by on the weekend. If you have been waiting a week or two for a review on your PR, it is perfectly fine to leave a polite follow-up. You can simply say, "Hi, just checking in on this PR when you have a moment."

-

Jamie: What about asking questions? If I am trying to fix a bug and I get stuck, when is the right time to ask for help, and how should I frame it clearly?

-

Alex: You should always feel empowered to ask questions. The key is to show what you have already tried. Do not just say, "How do I fix this?" Instead, frame it clearly: "I am trying to fix the broken link on line twenty-four. I searched the repository for the correct URL, but I could not find a file at that path. Can you point me in the right direction?" This shows respect for the maintainer's time because you proved you tried to solve it yourself first.

-

Jamie: I like that. And I want to mention something called the "Good first issue" social contract. Many projects label certain issues as "good first issue" to welcome new contributors.

-

Alex: Yes, and those labels are fantastic. When a maintainer uses that label, they are signaling that they are willing to invest time in mentoring a beginner. But there is a contract there. If you want to work on it, you need to leave a comment claiming it, like, "Hi, I would like to work on this. Can I be assigned?"

-

Jamie: And then you wait for assignment! Do not just start coding. If two people work on it in parallel, someone's time gets wasted. And if you get stuck, or life gets busy and you cannot finish it, just tell them. Say, "Life got busy, you should reassign this." Do not just disappear.

-

Alex: That is professional etiquette at its finest. One final note before we wrap up today. Many of you might be using AI assistive tools, like GitHub Copilot or other agentic workflows, to help draft code or even draft review comments. Remember this: Accessibility Agents' outputs are your responsibility. If an AI drafts a triage reply or a code review for you, your name appears on it in the repository's public history. The agent writes it, but you publish it. Always review an agent-generated comment against the anatomy of helpful feedback we discussed today. Ensure the tone is kind, the language is inclusive, and it does not sound like a cold, automated robot. You are responsible for the culture you help shape.

-

Jamie: This has been such a great conversation, Alex. I feel like we have covered a lot of ground. What are the main takeaways our listeners should walk away with today?

-

Alex: I would boil it down to four concrete takeaways. First, open source communication is public, text-based, and asynchronous. Provide full context in your issue and PR descriptions, and do not rely on tone to convey your meaning. Be explicit. Second, when reviewing code, be kind and focus on the code, not the person. Use the five-step feedback anatomy: acknowledge, identify, explain, suggest, and signal.

-

Jamie: Third, do not take feedback personally. Everyone gets change requests on their pull requests. It is a collaborative process to make the software better. And fourth, remember that maintainers are usually volunteers. Be patient with response times, assume good intent, and respect the project's Code of Conduct.

-

Alex: Beautifully summarized, Jamie. Taking the time to master these communication skills will make you a highly valued contributor in any open source community. That is all for Episode 8. In our next episode, we will dive into project management on GitHub, specifically focusing on Labels, Milestones, and Projects. We will learn how repositories organize thousands of issues so nothing gets lost.

-

Jamie: I am looking forward to it. Until next time, happy collaborating!

-

Alex: Keep building, and we will catch you in the next episode of Gitt Going with GitHub.

-
- - -

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 9: Labels, Milestones, and Projects - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode nine, Labels, Milestones, and Projects. I am Alex, and I am here with Jamie.

-

Jamie: Hello everyone. If you have been following along, you know we have covered a lot of ground. Back in episode five, we talked about how to create and participate in issues. But today, we are tackling the big question. What happens when a repository has hundreds, or even thousands, of open issues? How do you keep track of it all?

-

Alex: That is exactly what we are focusing on today. Labels, milestones, and projects are the organizational layer of GitHub. They take a chaotic list of issues and pull requests and turn them into a structured, prioritized body of work. By the end of this episode, you will understand how to categorize work, group it into goals, and track it across your entire team.

-

Jamie: I remember the first time I landed on a popular open source repository. I opened the issues tab, and there were literally two thousand open issues. It was completely overwhelming. I had no idea what was being worked on, what was abandoned, or where I could even begin to help.

-

Alex: It is a very common experience. And that is why the first tool we are going to discuss is so important. Let us talk about labels. If we need a real world analogy, think of labels like the metadata tags on a blog, or the category tags you might use in your email inbox. They communicate at a glance what category, priority, or status an item belongs to.

-

Jamie: And just to be clear, GitHub provides a standard set of labels by default when you create a repository, right?

-

Alex: Yes, they do. When you start a new project, GitHub gives you a handful of universal labels. You will almost always see a label called bug, which means something is not working as expected. You will see enhancement, which means a new feature request. There is documentation, for changes that only affect the read me or help files.

-

Jamie: My personal favorite when I was starting out was the good first issue label. If you are learning a new codebase, filtering by good first issue is the best way to find a bug that the maintainers have specifically flagged as being suitable for a beginner.

-

Alex: Absolutely. There is also help wanted, which means the maintainers are actively seeking community help to solve a problem. And you will see labels for things that are not going to be fixed, like duplicate, invalid, or wont fix.

-

Jamie: So how does a screen reader actually handle these? Because if you ask a sighted developer, they will tell you that labels are color coded tags. The bug label is usually red, enhancement is blue, and so on. As a screen reader user, do I need to care about the colors?

-

Alex: Not at all. The color is strictly supplementary visual information. When you scan the issue list with your screen reader, the labels are announced right alongside the issue title. You will hear something like, Issue forty two, Add keyboard navigation to carousel, Labels: accessibility, good first issue. The text name of the label is what matters.

-

Jamie: That is a relief. So, if I want to see every label that exists in a repository, where do I go?

-

Alex: You will want to navigate to the Labels page. From the main page of a repository, you first navigate to the Issues tab. Once you are there, the Labels link is located in the filter toolbar, right above the main list of issues. For screen reader users, the quickest way is to press the letter K to navigate through the links on the page until you hear Labels. It is usually right next to the Milestones link. When you activate that link, you land on a page that lists every single label in the project, along with a text description of what it means.

-

Jamie: And if you prefer the command line, you can do this without ever opening your browser. You can open your terminal and type g h space label space list. It will print out every label and its description right there in your console. I use that all the time to quickly check if a repository has an accessibility label before I file a bug.

-

Alex: That is a great tip. Now, let us talk about how you actually apply a label to an issue or a pull request. Let us say you just created an issue about a broken button, and you want to label it as a bug.

-

Jamie: This was tricky for me at first because the label controls are not in the main content area with the issue text. They are tucked away in the right sidebar.

-

Alex: Exactly. When you have an issue open, you need to navigate to the sidebar. The easiest way to do this with a screen reader is to press the letter H, or the number 3, to jump by heading until you hear the heading called Labels. Right after that heading, there is a gear button, which might be announced as an edit button.

-

Jamie: And when you activate that gear button, a dropdown menu opens with a list of all the available labels. You can use your up and down arrow keys to move through them, and press Enter to select or deselect a label.

-

Alex: You can also just start typing when that dropdown opens. If you type the word bug, it filters the list instantly. You press Enter to apply it, and then press Escape to close the dropdown. The label is applied immediately. There is no separate save button you have to hunt for.

-

Jamie: And again, for my fellow terminal fans, the GitHub C L I makes this incredibly fast. If you want to label issue number forty two, you just type g h space issue space edit space forty two space dash dash add dash label, followed by the name of the label in quotes. You can even add multiple labels at once by separating them with a comma.

-

Alex: So now that we have labels on our issues, the real power comes from filtering. Let us go back to Jamie's earlier example of looking at a repository with two thousand open issues. You do not want to read all of them. You only want to read the ones labeled good first issue.

-

Jamie: Right. To do that, you navigate to the filter bar on the Issues page. You can usually jump straight to it by pressing the letter F. The filter bar is just a text input field. By default, it will probably say is colon open, which means it is only showing open issues. All you have to do is add a space, and then type label colon, followed by the label name. So, label colon quote good first issue quote. Press Enter, and suddenly those two thousand issues become a list of maybe ten highly relevant issues.

-

Alex: You can combine these too. You could type label colon accessibility, space, label colon bug. That will show you only the issues that have both of those exact labels applied.

-

Jamie: What if the default labels are not enough? In the hackathon we are running, we want to track issues that are blocked by external dependencies. There is no default label for that. Can we create our own?

-

Alex: Yes, as long as you have write access to the repository, you can create custom labels. You navigate back to that Labels page we discussed earlier. You tab to the New Label button and activate it. This opens a form with three fields. First is the label name, where you would type blocked. Second is the description, where you might type, waiting on external dependency.

-

Jamie: And the third field is the color, right? How does that work for us?

-

Alex: The color field will usually auto populate with a random hex code. You can completely ignore it if you want to, or you can type in a specific hex code if your team has a visual design system. But again, the color is purely visual. The name and the description are what make the label accessible and useful to everyone. Once you fill those out, you tab to the Create label button, press Enter, and your new label is ready to be used by anyone on the project.

-

Jamie: Okay, so labels help us categorize what an issue is. It is a bug, it is documentation, it is blocked. But what if we need to organize things by when they need to be finished? That brings us to our second topic, milestones.

-

Alex: Exactly. If labels answer the question of what, milestones answer the question of when. Milestones group issues and pull requests toward a shared goal or a deadline.

-

Jamie: I like to think of a milestone as a shipping container. You have a bunch of separate boxes, which are your issues. You load them all into the shipping container, which is the milestone. The ship cannot leave the dock until every box inside that container is packed and sealed. In software development, this usually represents a version release, like Version 2 point 0, or a time boxed sprint.

-

Alex: That is a perfect analogy. A milestone has a title, an optional description, an optional due date, and a progress bar. The progress bar tracks the percentage of closed issues versus the total number of issues assigned to that milestone.

-

Jamie: When you are on the issues page, you can press the letter K to find the Milestones link, right next to the Labels link we used earlier. If you activate it, you get a list of all the active milestones. And I love how screen readers announce this. You will hear something like, Hackathon Day 1 Deliverables, 3 of 8 issues closed, due April 20. It gives you the entire context in one sentence.

-

Alex: It is very efficient. If you press Enter on a milestone title, you open its detail page, which simply lists all the issues and pull requests assigned to it. You navigate that list just like any other issue list, pressing the number 3 to jump from issue title to issue title.

-

Jamie: So how do we actually put an issue into that shipping container? How do we assign it to a milestone?

-

Alex: The workflow is almost identical to applying a label. When you are looking at an issue, you navigate to the right sidebar. You press the number 3 or the letter H to jump to the Milestone heading. Right after that heading is the Milestone gear button. You activate it, use your arrow keys to select the correct milestone from the dropdown, and press Escape.

-

Jamie: I am guessing there is a command line equivalent for this too?

-

Alex: There is. You can use g h space issue space edit space forty two space dash dash milestone, followed by the milestone name in quotes. But there is a small catch with milestones and the C L I. While you can easily assign issues to a milestone using the C L I, there is no native command to create a brand new milestone from scratch. For that, you either need to use the web interface, or use the g h api command to make a direct web request, which is a bit more advanced.

-

Jamie: Good to know. So let us talk about creating a new milestone through the web interface. I know this has a specific accessibility quirk we need to discuss.

-

Alex: Yes, it does. To create a milestone, you navigate to the Milestones page, tab to the New Milestone button, and activate it. You fill in the title and the description just like a label. But then you reach the Due Date field.

-

Jamie: And date pickers on the web are notoriously frustrating with screen readers. Half the time, the calendar pop up traps your keyboard focus, or it does not announce the days of the week correctly.

-

Alex: Exactly. GitHub provides a calendar widget, but my strong recommendation is to ignore it completely. The due date field is a standard text input field. The most reliable, accessible way to set the date is to simply type it out in the standard format. Type the four digit year, a dash, the two digit month, a dash, and the two digit day. So, 2024 dash 10 dash 31. It works perfectly every time, and you never have to fight with the calendar widget. Tab to the Create milestone button, press Enter, and you are done.

-

Jamie: Alright, we have covered labels for categorization, and milestones for grouping things by a deadline. But both of those tools still just leave you with lists of issues. What if I want a bird's eye view of everything happening in my organization? What if I want to see who is working on what, what is in progress, and what is finished, all on one screen?

-

Alex: For that, you need GitHub Projects. GitHub Projects is a fully featured, built in project management tool. If you have ever used tools like Jira, or Trello, or Asana, GitHub Projects is built to do exactly that, but it lives right next to your code.

-

Jamie: And it is important to note that we are talking about Projects version 2 here. If you are reading older documentation, you might see references to classic projects. But the current version of Projects is incredibly powerful because a single project board can pull in issues and pull requests from multiple different repositories at the same time.

-

Alex: That cross repository tracking is huge. Imagine you maintain five different open source repositories. Instead of checking five different issue tabs every morning, you can create one organization level Project. You can set it up so that any issue created in any of those five repositories, if it has the bug label, automatically gets added to your central Project. It acts like a giant control tower for your whole ecosystem.

-

Jamie: That sounds amazing. But how do we actually read a project board with a screen reader? Because when I hear the word board, I think of a highly visual layout with cards scattered everywhere.

-

Alex: That is a very valid concern. GitHub Projects supports three different layouts, and you can switch between them depending on what works best for you. The layouts are Table, Board, and Roadmap. Let us break them down one by one, starting with the Table view.

-

Jamie: Table view is my absolute favorite. It basically turns your project into a giant spreadsheet. Each row is an issue or a pull request. And the columns are the data fields, like Title, Status, Assignee, Priority, and so on.

-

Alex: The Table view is highly optimized for keyboard navigation. When you load a project in Table view, you can press the letter T to jump your focus straight into the data grid. From there, you just use your arrow keys. You can press Control plus Alt plus Down Arrow to move down through the rows, hearing each issue. And you press Control plus Alt plus Right Arrow to move across the columns for that issue.

-

Jamie: So as I arrow across a row, my screen reader will say something like, Title: Fix keyboard trap. Column two, Status: In Progress. Column three, Assignee: Jamie. It is completely linear and incredibly fast to read. And if I want to change the status, I just press Space on the status cell, and a dropdown opens right there.

-

Alex: Exactly. It is essentially a fully accessible spreadsheet. Now, the second layout is the Board view. This is what people typically call a Kanban board. It organizes work into columns based on status. Usually, you have a To Do column, an In Progress column, and a Done column.

-

Jamie: This is where sighted users usually drag and drop cards from one column to another using their mouse. Obviously, drag and drop is not a great experience with a screen reader. So how do we move a card from To Do to In Progress?

-

Alex: GitHub has made this very straightforward. You do not need to drag and drop anything. Each column is marked as a region, so you can press the letter D, or use your screen reader's region navigation, to jump between To Do, In Progress, and Done. Once you are in a column, you press the number 3 to read the cards.

-

Jamie: And when I find the card I want to move?

-

Alex: You just press Enter on the card. This opens a detail panel on the right side of your screen. Inside that panel, there is a field called Status. You activate the status field, change it from To Do to In Progress, and press Escape. The card instantly moves to the correct column on the board. You are updating the underlying data, and the visual board simply updates to reflect your change.

-

Jamie: That is so much easier than trying to simulate a mouse drag. Just open the card, change the word, and close it. Okay, what about the third layout, the Roadmap view?

-

Alex: The Roadmap view is a timeline, often called a Gantt chart. It draws horizontal bars across a calendar to show when work starts and ends. It is heavily visual and is mostly used by project managers to plan capacity over months or quarters.

-

Jamie: To be honest, I rarely use the Roadmap view. Because all three views are just different ways of looking at the exact same data, I find it much easier to just switch back to the Table view. If I want to know the start and end dates of an issue, I just read the date columns in the table.

-

Alex: That is exactly the right approach. Treat the Roadmap as a visual summary for stakeholders, but use the Table view to actually read and edit your project data.

-

Jamie: So, how do I actually get my issues into this project? We talked about automation earlier, but what if I just want to add one specific issue manually?

-

Alex: You have two ways to do this. The first is from the issue itself. Just like labels and milestones, there is a Projects heading in the right sidebar of every issue. You press H to find it, activate the gear button, and select your project from the list.

-

Jamie: And the second way?

-

Alex: The second way is from inside the project board itself. At the bottom of the table or column, there is an Add Item button. If you activate it, a text field appears. You just type the pound sign, also known as the hash symbol, followed by a keyword from your issue title, or the issue number. A search dropdown appears, you select your issue, and it drops right into the project.

-

Jamie: I want to pause here and talk about how all three of these things, labels, milestones, and projects, fit together. Because when I first learned this, it felt like redundant work. Why do I need a milestone if I have a project board?

-

Alex: That is a great question, and it is the key to mastering GitHub organization. They are not redundant; they are complementary. Think of it like a sentence. Labels are the adjectives. They describe what the work is. It is an accessibility bug. Milestones are the deadlines. They describe when the work must be finished. It is due by the end of the hackathon. Projects are the map. They describe where the work currently is in the process. It is in progress, and assigned to Jamie.

-

Jamie: Oh, that is a great way to put it. And when you combine them, you can create incredibly powerful views. In my project board, I can create a filter that says, only show me issues where the label is accessibility, and the milestone is Hackathon Day 1. Suddenly, a chaotic repository becomes a highly focused to do list.

-

Alex: Exactly. And this is going to become critically important when we start talking about AI and Accessibility Agents later in the workshop. These labels and milestones are the exact language that automated workflows use to route work. If you do not apply labels properly, the automated agents will not know how to prioritize your issues. Labeling is not just overhead; it is how you program the project management system.

-

Jamie: This has been incredibly helpful. I feel like I finally have a mental model for how large open source projects actually function without collapsing into chaos.

-

Alex: It really is the secret to scaling collaboration. Let us recap the main takeaways from today's episode. First, labels are text based tags that categorize your issues. You apply them from the right sidebar of an issue, and you can use them in the filter bar to instantly narrow down your view.

-

Jamie: Second, milestones group issues together toward a shared deadline. The safest way to set a milestone due date with a screen reader is to ignore the calendar pop up and simply type the date in year, month, day format.

-

Alex: Third, GitHub Projects act as a central hub, pulling issues from multiple repositories into one view. You can navigate them seamlessly using the Table view, jumping to the grid with the letter T and moving through the data with Control plus Alt plus your arrow keys.

-

Jamie: And finally, do not try to drag and drop cards in a board view. Just press Enter to open the issue, change the status field in the sidebar, and let the board update itself.

-

Alex: Perfectly summarized. Now that you know how to organize work, you are going to want to know when people interact with that work. In our next episode, we are tackling one of the most requested topics: GitHub Notifications. We will show you how to tame your inbox, filter the noise, and ensure you never miss a mention.

-

Jamie: I cannot wait for that one. My inbox is currently a disaster zone. Thank you all for listening, and we will catch you in the next episode of Gitt Going with GitHub.

-
- - -

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 10: Notifications and Mentions - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode ten, Notifications and Mentions. I am Alex, and I am here to help you navigate the social and collaborative side of open source without getting completely overwhelmed by the noise.

-

Jamie: And I am Jamie. I am a blind developer who is still figuring out how to keep my digital life organized. I have to admit, Alex, the title of this episode gives me a little bit of anxiety. Notifications. Just the word makes me think of my phone buzzing non stop and an inbox with ten thousand unread messages.

-

Alex: That is a completely normal reaction, Jamie. In episode five, we talked about working with issues and commenting. Then in episode six, we covered pull requests and reviews. You have been putting your work out there, asking questions, and proposing changes. Now, the community is talking back. And when people talk back, GitHub generates notifications.

-

Jamie: It feels like a big transition. Going from being the person initiating the action, to being the person receiving all these updates. When I first started using GitHub about two years ago, I had this moment where I suddenly started receiving hundreds of emails a day from a repository I had visited only once. I thought I broke something.

-

Alex: You definitely did not break anything, but you did encounter one of the most common right of passage moments for new GitHub users. You probably accidentally subscribed to a very busy project. Today, we are going to make sure that never happens again. We are going to cover how GitHub generates notifications, the difference between participating and watching, how to manage your notification inbox, and how to use mentions to get someone else's attention.

-

Alex: Let us start with the core concept. How does GitHub decide to send you a notification in the first place? It all comes down to two concepts, participating and watching.

-

Jamie: Participating makes sense to me. If I am part of a conversation, I should probably know when someone replies.

-

Alex: Exactly. You are participating in a thread if you opened the issue or pull request, if you commented on it, or if someone explicitly assigned it to you. You are also participating if someone mentions your username directly. When you are participating, GitHub assumes you want to know how the story ends, so it subscribes you to that specific thread.

-

Jamie: So what is an analogy for that? Is participating like being on a group text message?

-

Alex: That is a perfect analogy. If you are on the group text, your phone is going to buzz when someone replies. But watching is completely different. Watching a repository is like installing a baby monitor in every room of a giant office building and piping the audio directly into your headphones.

-

Jamie: Oh wow. That sounds exhausting.

-

Alex: It really is, if you do it to the wrong repository. When you watch a repository, you are telling GitHub that you want to receive a notification for every single thing that happens in that project. Every new issue, every comment, every pull request, every automated test failure. For your own personal projects, watching is great. But for a massive open source project like Microsoft VS Code or the NVDA screen reader, watching means you will get thousands of notifications a week.

-

Jamie: That is exactly what happened to me! I thought I was bookmarking a repository so I could find it later. I navigated to the top of the repository page, found a button, and activated it. The next morning, my email inbox was completely destroyed.

-

Alex: I am so glad you brought that up, because new contributors constantly confuse watching with starring. They are two buttons located right next to each other at the top of every repository page. Let us clear up the difference right now. Starring a repository is what you actually wanted to do. Starring is like a public bookmark or a high five to the maintainers. It adds the project to a list on your profile, and it tells the creators that you like their work. Starring generates zero notifications.

-

Jamie: Zero notifications. That is beautiful. I wish I had known that.

-

Alex: Right. Starring is for bookmarking. Watching is for subscribing. By default, when you interact with a repository, your watch settings are set to participating and mentions. That is the sweet spot. It means you only hear about the things that actually involve you.

-

Jamie: But what if I do want to change my watch settings? Say I join a small team and I actually do need to know everything that happens in our team repository.

-

Alex: You can easily change your watch level. Navigate to the main page of the repository. If you are using NVDA or JAWS on Windows, you can press B to navigate through the buttons until you find the Watch button. Press Enter to open it. It is actually a drop down menu. Then use your up and down arrow keys to navigate the subscription options.

-

Jamie: And if I am using VoiceOver on a Mac?

-

Alex: With VoiceOver, you can use quick nav B to find the Watch button, then press VO plus Space to open the menu, use your arrow keys to find your preferred level, and press VO plus Space again to select it. The options you will hear are Participating and mentions, All Activity, Ignore, and Custom.

-

Jamie: Ignore sounds pretty intense.

-

Alex: Ignore is very useful if you are part of a massive organization and you are automatically subscribed to repositories you have nothing to do with. It completely mutes that repository. Custom is also great because it lets you get granular. You can say, only notify me when a new release is published, but ignore all the day to day issue comments.

-

Jamie: Okay, so we have covered how to control the fire hose of information. Let us talk about how we actually get someone else's attention. You mentioned that being mentioned makes you a participant. How does that work?

-

Alex: Mentions are how you tap someone on the shoulder in a crowded room. Anytime you are typing a comment in an issue, a pull request, or a discussion, you can type the at symbol followed by a person's GitHub username. For example, at Jamie blind dev. When you submit that comment, GitHub immediately sends a notification to that user, and it automatically subscribes them to that thread so they will see future replies.

-

Jamie: I love the shoulder tap analogy. It is literally requesting someone's specific attention. I use this a lot when I am stuck on a problem and I know exactly which developer wrote the code I am struggling with. I will drop a comment and mention them to ask for their input.

-

Alex: That is exactly what it is for. But there is a point of etiquette here. You should only tap someone on the shoulder if you actually need them. Tapping the lead maintainer of a huge project just to say hello or to ask them to look at your unrelated bug is generally frowned upon. Use mentions intentionally.

-

Jamie: That makes sense. What about when I need help from a group, but I do not know exactly who to ask? Like, I know the accessibility team needs to review my pull request, but I do not know the individual names of the people on that team.

-

Alex: That is where team mentions come in. It is a fantastic feature. Instead of mentioning a person, you can mention a whole team. The syntax is the at symbol, followed by the organization name, a forward slash, and the team name. So, at community dash access forward slash accessibility dash agents.

-

Jamie: Oh, that is clever. It is like using the public address system to page a specific department instead of paging one specific doctor.

-

Alex: Exactly. When you mention a team, GitHub sends a notification to everyone who is a member of that team. It is the best way to request a review from a specialized group without having to memorize everyone's individual usernames.

-

Jamie: Alright, so people are mentioning me, they are requesting my review, my automated continuous integration tests are failing and sending me alerts. Where does all this information go? Earlier I mentioned my email inbox getting destroyed. Is email the only way to manage this?

-

Alex: Email is one way, but it is rarely the best way. The problem with email is that GitHub notifications get mixed in with your bank statements, your newsletters, and messages from your family. It is too easy to lose context. The best way to handle this is the dedicated GitHub notification inbox.

-

Jamie: A dedicated inbox just for GitHub? Where do I find that?

-

Alex: You can navigate to github dot com forward slash notifications. But there is a much faster way. GitHub has a global keyboard shortcut for this. From almost anywhere on the GitHub website, you can press G then N.

-

Jamie: Let me clarify that for our screen reader users. When you say G then N, do you mean pressing them at the same time, like a chord?

-

Alex: Great question. No, it is a sequential shortcut. You press the letter G, release it, and then press the letter N. It stands for Go to Notifications. Just make sure you are in browse mode or reading mode, not focus mode, so your screen reader passes the keystrokes through to the browser.

-

Jamie: Okay, so I press G then N, and I arrive at the notification inbox. What is the layout of this page? I always find it helpful to understand the structure before I start arrowing around.

-

Alex: Structurally, the page has three main areas. On the far left, there is a sidebar with filters. In the center, taking up most of the page, is the notification list itself. And on the far right, there is a detail pane that shows a preview of whatever notification you have selected. Though, a quick tip, many screen reader users prefer to disable that right preview pane in their settings because it can make navigation a bit cluttered.

-

Jamie: I definitely turned that preview pane off. I prefer just a clean list. How do you recommend navigating the list itself?

-

Alex: The center list is grouped by date. So you will have a heading for Today, a heading for Yesterday, a heading for This Week, and so on. If you are using NVDA or JAWS, you can press the letter H to jump between these date headings. If you are using VoiceOver, make sure quick nav is on and press H.

-

Jamie: And once I am under a heading, like Today, how do I read the actual notifications?

-

Alex: This is a really important detail. Do not use your standard up and down arrow keys to read the list. The list is actually a complex interactive widget. The most reliable way to navigate it is to press the Tab key to move from one notification row to the next.

-

Jamie: What exactly does the screen reader announce when I tab to a notification row?

-

Alex: GitHub has done a lot of work to make this announcement comprehensive. When your focus lands on a row, you will hear four distinct pieces of information. First, the repository name. Second, the title of the issue or pull request. Third, the event type, which tells you why you received the notification, like review requested or mention. And fourth, the timestamp.

-

Jamie: So it might say something like, microsoft forward slash vscode, Add keyboard shortcut for accessible view, Jamie blind dev mentioned you, two hours ago.

-

Alex: Spot on. That single announcement gives you all the context you need to decide what to do next. And if you want to open that notification to read the full thread, you just press Enter. It will take you directly to the issue or pull request page, and it will automatically scroll your focus down to the exact comment that triggered the notification.

-

Jamie: Okay, so I tab to a notification, I hear what it is. Now I have to make a decision. This is where I struggle. I read it, but then it just sits in my inbox forever. How do I actually clear things out?

-

Alex: This brings us to inbox actions and keyboard shortcuts. The GitHub inbox is designed for rapid triage. You want to process these notifications like you process physical mail at your front door. You either throw it in the recycling, you file it away, or you open it immediately because it is urgent.

-

Jamie: I love that analogy. I am definitely a pile it on the kitchen counter kind of person, which explains my inbox. What are the shortcuts for processing the mail?

-

Alex: Once your focus is on a notification row, you have several single key shortcuts available. The most important one is the letter E. Pressing E marks the notification as done. It archives it and removes it from your inbox view.

-

Jamie: E for done. That is easy to remember. What if I want to keep it in my inbox, but I want to remember that I have already looked at it?

-

Alex: You can mark it as read without opening it by pressing Shift plus I. If you want to mark something as unread so it stays bold and catches your attention later, press Shift plus U.

-

Jamie: What if it is something really important that I need to work on tomorrow? Is there a way to pin it or save it?

-

Alex: Yes. Press the letter S to save it for later. This moves it to a special Saved filter in your sidebar, so it does not clutter your main inbox but it is securely filed away for when you have time.

-

Jamie: Okay, those are great. E for done, Shift plus I for read, S for save. But what about the opposite scenario? What if I am participating in a thread, maybe I left a tiny comment a month ago, and now two other developers are arguing back and forth with fifty comments a day. My inbox is filling up with their argument. How do I escape?

-

Alex: You need to mute the thread. This is a crucial survival skill. If you are focused on a notification row and you realize the conversation is no longer relevant to you, press the letter M. M stands for mute. It is the equivalent of silently leaving the group chat. You will not receive any more notifications for that specific issue or pull request, unless someone mentions your username directly.

-

Jamie: That is a lifesaver. M for mute. I am going to use that constantly. But what if I have already opened the issue? Do I have to go back to the inbox to mute it?

-

Alex: No, you can unsubscribe right from the issue page. Navigate to the right sidebar, find the section called Notifications, and activate the Unsubscribe button. It does the exact same thing as pressing M in the inbox.

-

Jamie: Let us talk about strategy. You mentioned earlier that some people have thousands of notifications. How do you personally manage your inbox without spending your entire day organizing it?

-

Alex: I am a big believer in the mark all as done workflow. When I come back from a long weekend, or if I just let things pile up, I do not process them one by one. I navigate to the top of the inbox, I find the filter field, and I type in the names of the repositories I care about the most.

-

Jamie: Wait, there is a search filter for the inbox?

-

Alex: Yes. At the top of the notification list, there is a text input field. You can navigate to it quickly by pressing the letter F for find, or E for edit, depending on your screen reader. You switch to focus mode, and you just type a repository name or an organization name. The list filters in real time to show only those notifications.

-

Jamie: Oh, that is incredibly powerful. So you filter for the important stuff first.

-

Alex: Exactly. I filter for my primary project. I read those, I reply to those, I press E to mark them done. Once I have handled the high priority items, I clear the filter by pressing Escape. Then, I tab to the button that says Mark all as done, and I press Enter.

-

Jamie: You just wipe out the rest of the inbox? Just like that?

-

Alex: Just like that. It clears everything. If I missed something truly critical, someone will mention me again. But realistically, most notifications are just conversational noise. If you try to read every single one, you will never get any actual coding done.

-

Jamie: That is incredibly liberating to hear from an experienced maintainer. It is okay to just let things go.

-

Alex: It is mandatory to let things go. You have to protect your focus. And speaking of protecting your focus, let us talk about the left sidebar filters. You can press the letter K to navigate through links, or just Tab to the sidebar. You will find filters like Unread, Saved, and Done. But the most powerful filters are Mentioned, Assigned, and Review requested.

-

Jamie: I can see why those are powerful. Those are the items that represent actual work waiting for me.

-

Alex: Exactly. If your inbox is overflowing, just activate the Review requested filter. That instantly narrows your view to only the pull requests where a teammate is literally blocked waiting for your approval. It cuts through all the noise.

-

Jamie: We talked earlier about email notifications. I still get emails along with my web notifications. It feels redundant. Should I turn one of them off?

-

Alex: I strongly recommend turning off email notifications for everything except maybe direct mentions or administrative alerts. Having both is a recipe for anxiety. To fix this, you need to configure your account settings. Navigate to github dot com forward slash settings forward slash notifications.

-

Jamie: What am I looking for on that settings page?

-

Alex: It is a long page, but it is well structured with headings. You can press H to jump from section to section. Look for the section called Email delivery. There, you can uncheck the boxes that send notifications to your email. I prefer to do all my triage in the web inbox because the keyboard shortcuts we just talked about make it so much faster than managing email.

-

Jamie: I am going to make that change as soon as we finish recording. What about the GitHub command line interface? In the last few episodes, we talked about how great the G H CLI is for creating issues and pull requests. Can I manage my notifications from the terminal?

-

Alex: You can, but it serves a slightly different purpose. The web interface is best for rapid triage and achieving inbox zero. The command line is best for targeted queries. For example, you can open your terminal and type g h search p r s dash dash review dash requested at me dash dash state open.

-

Jamie: That is a long command. Let me break that down. G h search p r s, means search pull requests. Dash dash review dash requested at me, filters for ones waiting on me. And dash dash state open, means only show me ones that are not closed yet.

-

Alex: Exactly. That command will output a clean text list in your terminal of exactly what you need to review. You can also run g h issue list dash dash assignee at me, to see all issues assigned to you. So, while the CLI does not have a fully featured inbox management tool for muting and archiving, it is fantastic for quickly finding out what your action items are without ever opening a web browser.

-

Jamie: That is really good to know. I like the idea of starting my morning in the terminal, running those two commands, and knowing exactly what my priorities are for the day, without getting distracted by a hundred other notifications in the web inbox.

-

Alex: That is a very professional workflow. It puts you in control of the information, rather than letting the information control you.

-

Jamie: Alright, we have covered a massive amount of ground today. This feels like the missing manual I needed two years ago. Let us recap the biggest takeaways for everyone listening.

-

Alex: First, understand the difference between watching and starring. Starring is a bookmark. Watching is a subscription. If you are overwhelmed with noise, check to make sure you have not accidentally watched a busy repository. You generally want your watch setting to be participating and mentions.

-

Jamie: Second, use the dedicated web inbox at github dot com forward slash notifications. The sequential keyboard shortcut is G then N. Do not rely on email. The web inbox gives you powerful filtering and triage tools.

-

Alex: Third, navigate the inbox list using the Tab key, not your reading arrows. Listen to the comprehensive announcement for each row, which includes the repository, title, event type, and timestamp.

-

Jamie: Fourth, learn the single key shortcuts. E marks a notification as done and gets it out of your way. M mutes a noisy thread so you stop hearing about it. And S saves it for later.

-

Alex: And finally, do not be afraid to use the mark all as done button. Your attention is your most valuable resource. Protect it ruthlessly. Filter for the things that matter, like review requests and direct mentions, and let the rest go.

-

Jamie: This has been incredibly helpful. I feel like I finally have a strategy to tame the beast. What is next on our journey?

-

Alex: This episode concludes the first major phase of our workshop. You now know how to navigate repositories, work with issues, review pull requests, and manage your communications. Next time, we are moving into the day two agenda, where things get really exciting. We are going to introduce GitHub Copilot, and we will talk about agentic workflows, where artificial intelligence can actually help you summarize those notifications and manage your project.

-

Jamie: Oh, I cannot wait for that. Having an AI assistant read my notifications sounds like a dream come true.

-

Alex: It is a game changer, but it relies entirely on the manual discipline we learned today. An agent can only summarize effectively if you have your watch settings configured correctly. So, practice taming your inbox today, and we will see you in the next episode. Thanks for listening to Gitt Going with GitHub.

-
- - -

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 5: VS Code Setup and Accessibility

- - -

Download Episode 11 (MP3)

-
-Read Transcript - Episode 11: VS Code Setup and Accessibility - -

Transcript

-

Alex: Welcome to episode eleven of Gitt Going with GitHub. I am Alex, your lead host for this series, and today we are tackling a massive and exciting topic. We are talking about setting up Visual Studio Code for accessibility.

-

Jamie: And I am Jamie. I have to admit, I am really looking forward to this one, but I also remember how overwhelming this exact topic was for me about two years ago. We spent episode one of this series making sure you all had Visual Studio Code and Git installed, which was a great first step. But actually opening the editor and figuring out how to make it talk nicely with a screen reader felt like a whole new mountain to climb.

-

Alex: That is a completely normal feeling. Moving from reading code on a website to actually writing and managing code in a professional editor is a big transition. When something might feel intimidating today, I want you to remember that you have already done most of this on day one of your learning journey. You already understand the workflow. Today, we are just learning how to let Visual Studio Code handle the heavy lifting.

-

Jamie: OK, that sounds like a good mindset to have. So, let us start at the very beginning. What exactly is Visual Studio Code? I hear developers just call it VS Code all the time.

-

Alex: Yes, we will refer to it as VS Code from here on out. VS Code is a free, extensible code editor built by Microsoft.

-

Jamie: Let us break that down. What do you mean by an extensible code editor? How is a code editor different from something like Microsoft Word?

-

Alex: That is a great question. A word processor like Microsoft Word is designed for rich text. It cares about fonts, bold text, page margins, and printing. A code editor is designed purely for plain text, but it is highly optimized for programming. It understands the structure of code, it can catch errors as you type, and it integrates directly with tools like Git.

-

Jamie: And what about that word, extensible?

-

Alex: Extensible means you can add new features to it. I like to think of VS Code as a heavy duty workshop bench. Out of the box, it is just a really solid table. But because it is extensible, you can bring your own tools and bolt them onto the bench. You can install tools for Python, tools for spell checking, or tools for GitHub Copilot. You customize the bench to fit exactly what you need to build.

-

Jamie: I love that analogy. You build your own perfect workspace. But before we talk about the desktop app that everyone installed in episode one, I want to talk about a really cool trick I learned. The browser version.

-

Alex: Ah, yes. The github dot dev experience. This is one of the most powerful features GitHub offers, and it requires zero installation.

-

Jamie: I remember the first time someone told me how to use this. They told me to open any repository on GitHub and just press the period key. I thought they were joking.

-

Alex: It sounds like a magic trick, but it is real. If you are navigating any GitHub repository in your browser, and you press the period key, just the dot on your keyboard, the webpage will instantly transform. The URL changes from github dot com to github dot dev, and suddenly, you are sitting inside a fully functional version of VS Code, running entirely in your browser.

-

Jamie: It is so fast. To use your workshop analogy, if the desktop app is your main heavy duty workbench in your garage, the github dot dev browser experience is like a pop up shop version of your workbench. You can access it from anywhere, on any computer, without installing a single thing.

-

Alex: Exactly. It uses the exact same keyboard shortcuts as the desktop version, and it has the exact same screen reader mode. It is the perfect bridge between browsing GitHub on the web and doing deep development work on your machine.

-

Jamie: Are there things the browser version cannot do? Why even bother with the desktop app if the browser version is so good?

-

Alex: The browser version does have limitations. Because it runs in your web browser, it does not have an integrated terminal. You cannot run command line scripts. It also does not support GitHub Copilot or running local accessibility agents. For those heavy duty tasks, you need the desktop application. But for quick edits, fixing a typo in documentation, or reviewing a pull request, pressing the period key is the fastest way to get to work.

-

Alex: Now, whether you are using the browser version or the desktop app, the very first thing you need to do is turn on screen reader mode. VS Code is built using web technologies, which means it behaves a lot like a complex web application. By default, it presents a lot of visual information that can be incredibly noisy or confusing for a screen reader.

-

Jamie: How do we fix that? How do we make it accessible?

-

Alex: You activate screen reader mode by pressing Shift plus Alt plus F1. If you are on a Mac, you will press Shift plus Option plus F1.

-

Jamie: What actually happens when I press Shift plus Alt plus F1?

-

Alex: It is like turning the lights on for your screen reader. When you enable this mode, VS Code changes how focus moves around the application. It suppresses a lot of the visual decorations that cause extra noise. Most importantly, it enables live regions for code suggestions and errors.

-

Jamie: Can you define live region for anyone who might be new to that term?

-

Alex: Certainly. A live region is an invisible area of the application that can send spoken announcements to your screen reader, even if your keyboard focus is somewhere else. So, if you are typing code, and VS Code finds an error, the live region will announce the error to you immediately, without you having to navigate away from the line you are typing on.

-

Jamie: That is incredibly helpful. OK, that sounds like a lot of steps to remember every time I open the app.

-

Alex: It does! But here is the thing, you really only have to configure this once. To make sure it stays on permanently, you should update a specific setting. You will want to navigate to your settings and search for the phrase editor dot accessibility support. You want to set this to the word on, rather than leaving it on auto.

-

Jamie: Why force it to on? Does the auto setting not work?

-

Alex: Auto usually works if you are on Windows using NVDA or JAWS. VS Code will try to detect your screen reader and turn the mode on automatically. But sometimes, especially if you start your screen reader after opening the editor, it might miss the detection. Forcing editor dot accessibility support to on guarantees that all those screen reader announcements and optimizations are always active.

-

Jamie: OK, so our screen reader is happy and talking to us properly. How do we actually do things in VS Code? There are so many menus and buttons. It can feel like being dropped into the cockpit of an airplane.

-

Alex: The secret to VS Code is that you do not need to memorize the menus. You only need to memorize one keyboard shortcut. Control plus Shift plus P.

-

Jamie: Ah, the Command Palette. I call this the magical concierge.

-

Alex: That is the perfect name for it. When you press Control plus Shift plus P, a text input field opens at the top of the window. This is the Command Palette. Every single action, setting, and feature in VS Code can be triggered by typing its name into this box.

-

Jamie: It is like going to a restaurant where you do not need to read the menu. You just walk up to the chef and say, I would like to format this document, or I would like to open my settings, and the chef just does it for you.

-

Alex: Exactly. If you want to change your color theme, you press Control plus Shift plus P, type the word theme, and press enter. If you want to toggle word wrap, you press Control plus Shift plus P, type word wrap, and press enter. You never have to dig through complex dropdown menus.

-

Jamie: And what if I want to learn the actual keyboard shortcuts for the area of the editor I am currently working in? Is there a quick way to get help without leaving the app?

-

Alex: Yes, and this is an essential tool for screen reader users. It is the accessibility help dialog. You can open it by pressing Control plus Shift plus H.

-

Jamie: What exactly does it tell you?

-

Alex: The accessibility help dialog is context aware. That means if your focus is currently inside the text editor, and you press Control plus Shift plus H, a plain text document pops up. It will read out exactly how to navigate the text editor, which shortcuts move you between errors, and how to trigger suggestions.

-

Jamie: Oh, that is clever! So if I move my focus to the terminal and press Control plus Shift plus H, it gives me different instructions?

-

Alex: Precisely. It will give you the specific accessibility commands for the terminal. It is your built in manual for wherever you happen to be standing at that exact moment. Use it as your first action whenever you land somewhere new in VS Code.

-

Alex: Speaking of landing somewhere new, let us talk about the layout of VS Code and how to navigate between its different areas. The interface is divided into a few main regions. The Sidebar, the Editor, the Terminal, and the Panels.

-

Jamie: I like to think of these as the rooms of a house. You do different tasks in different rooms, and you need to know how to walk between them.

-

Alex: Let us start with the Sidebar. On the far edge of the window is a vertical strip called the Activity Bar. The Activity Bar contains the main views of the application. The most important ones are the Explorer, the Search view, the Source Control view, and the Extensions view.

-

Jamie: Can we talk about the Explorer first? Because I remember being really confused about the difference between opening a file and opening a folder.

-

Alex: That is a very common stumbling block. The Explorer is your file tree. It shows you all the files in your project. But how you open your project matters. If you go to the file menu and select Open File, VS Code will open just that single document. The Explorer will be empty.

-

Jamie: Right, and my analogy for this is a filing cabinet. Opening a file is like taking a single piece of paper out of the filing cabinet and putting it on your desk. You can read it and write on it, but you cannot see any of the other papers that were next to it.

-

Alex: Exactly. But if you choose Open Folder instead, it is like bringing the entire filing cabinet to your desk. The Explorer will populate with every file and subfolder inside that project. This is how you should always work in VS Code. You open the root folder of your repository, so you have access to everything at once.

-

Jamie: So if I want to jump over to the Explorer to find a file, what is the shortcut?

-

Alex: You press Control plus Shift plus E. That moves your focus to the Explorer. You can use your up and down arrows to navigate through your files, and press Enter to open one.

-

Jamie: And when I press Enter, the file opens in the Editor room. How do I move my focus back and forth between the Explorer and the Editor?

-

Alex: To jump into your active Editor, you press Control plus 1. That puts your cursor directly into the text of the file you are working on. To go back to the Explorer, you press Control plus Shift plus E again. You will be doing this dance constantly. Control plus 1 for the editor, Control plus Shift plus E for the Explorer.

-

Jamie: What about the other views in the Activity Bar? You mentioned Search and Source Control.

-

Alex: Search allows you to find text across every file in your entire folder. You can navigate to it by pressing Control plus Shift plus F. Source Control is where you stage and commit your changes to Git. You can reach that by pressing Control plus Shift plus G.

-

Jamie: Earlier, you mentioned the Extensions view. You said VS Code is extensible, like bringing your own tools to a workbench. How do we actually install these tools?

-

Alex: You will open the Extensions view by pressing Control plus Shift plus X. This moves your focus into a search box. You simply type the name of the extension you want, for example, Python, or GitHub Pull Requests. Then you press the Tab key to navigate to the search results, use your arrow keys to find the exact match, and press Enter to install it.

-

Jamie: I wish I had known that when I started. It is so much faster than trying to use a mouse to find the little install buttons. Now, what about the terminal? You mentioned earlier that the browser version does not have one, but the desktop version does.

-

Alex: Yes, the integrated terminal. If the editor is where you write your code, the terminal is the engine room. It is where you type direct text commands to your computer's operating system, completely bypassing the graphical interface. You use it to run Git commands, install software packages, or start local web servers.

-

Jamie: How do we open the engine room?

-

Alex: You press Control plus Backtick.

-

Jamie: OK, let us pause for a second. What is a backtick? I spent an embarrassingly long time looking for this key.

-

Alex: The backtick key is usually located in the top left corner of your keyboard, right above the Tab key, and just to the left of the number one. It shares a key with the tilde symbol. Pressing Control plus Backtick will instantly open the integrated terminal panel at the bottom of your window and move your focus into it. Pressing Control plus Backtick a second time will hide the terminal and return your focus to the editor.

-

Jamie: Let us talk about something really fun. Audio cues. I think this is one of the best accessibility features Microsoft has ever added to an application.

-

Alex: I completely agree. VS Code has a system called accessibility signals. These are distinct audio cues, little chimes and sounds, that communicate the state of the editor without requiring your screen reader to speak a single word.

-

Jamie: It is so much like the dashboard sounds in a car. You do not need to take your eyes off the road to look at the dashboard to know your turn signal is on, because you can hear the rhythmic clicking. Audio cues do the exact same thing for coding.

-

Alex: A perfect example is the error signal. If you have the setting called accessibility dot signals dot line has error turned on, VS Code will play a distinct, slightly lower pitched tone whenever your cursor moves onto a line of code that contains a mistake.

-

Jamie: It is amazing because it does not interrupt your screen reader's speech. You hear your screen reader read the text of the line, and layered right underneath it, you hear the little error tone. You immediately know something is wrong before you even finish reading the line.

-

Alex: There are audio cues for everything. There is a cue for when a terminal command finishes successfully, a cue for when a terminal command fails, and cues for when you are navigating through changes in your code. You can configure all of these by opening your settings and searching for accessibility signals.

-

Jamie: Speaking of navigating through changes, I want to ask about the Accessible Diff Viewer. This is a concept that took me a while to wrap my head around. First, what exactly is a diff?

-

Alex: A diff is short for difference. So a pull request, and I love that name because you are literally requesting that someone pull your changes into their project, a pull request is essentially just a big diff. It is a representation of exactly what lines of code you added, and what lines of code you removed.

-

Jamie: Right. And visually, a diff is usually displayed side by side. You have the old file on the left side of the screen with the removed lines highlighted in red, and the new file on the right side with the added lines highlighted in green.

-

Alex: Which is an absolute nightmare to navigate with a screen reader. A spatial, color coded layout does not translate well to linear speech.

-

Jamie: It really does not. So how do we read a diff effectively?

-

Alex: This is where the Accessible Diff Viewer comes in. When you have a diff open in your editor, instead of trying to read the visual side by side layout, you open the Command Palette with Control plus Shift plus P. Then, you type Open Accessible Diff Viewer and press enter.

-

Jamie: What does that view actually look like to the screen reader?

-

Alex: It completely transforms the presentation. It turns the diff into a single, vertical list. It is like having a redline document read aloud to you line by line. As you use your up and down arrows, it will announce the change type before reading the code. It will say, Line added, followed by the text. Or it will say, Line removed, followed by the text. Or it will say, Unchanged, to give you the surrounding context.

-

Jamie: That is a game changer. You get the complete picture of what changed, in reading order, without having to scan visually.

-

Alex: Before we wrap up, there is one last piece of housekeeping regarding keyboard navigation. Sometimes, a built in VS Code shortcut might conflict with a screen reader command. For instance, NVDA or JAWS might intercept a keystroke before it ever reaches the editor.

-

Jamie: That used to drive me crazy. What is the fix for that? Do you just have to live without that command?

-

Alex: Not at all. VS Code allows for total keyboard shortcut customization. If a shortcut does not work for you, you can change it. You just open the Command Palette with Control plus Shift plus P, type Open Keyboard Shortcuts, and press enter. You can search for the command you want to change, press enter on it, and then simply type your new preferred key combination.

-

Jamie: I love that. The editor really bends to fit your workflow, not the other way around.

-

Alex: Exactly. Let us summarize our key takeaways for today. First, remember the period key trick. Pressing period on any GitHub repository opens the github dot dev browser experience for fast, lightweight editing.

-

Jamie: Second, always turn on screen reader mode by pressing Shift plus Alt plus F1, and make sure your editor dot accessibility support setting is forced to on.

-

Alex: Third, the Command Palette is your best friend. Press Control plus Shift plus P to find any command without digging through menus. And remember Control plus Shift plus H to open the accessibility help dialog for context aware shortcut lists.

-

Jamie: Fourth, always open a folder, not a file, so you have access to your entire project in the Explorer.

-

Alex: And finally, when reviewing changes, use the Command Palette to open the Accessible Diff Viewer for a clean, line by line reading experience.

-

Jamie: This has been incredibly helpful. I feel like my workbench is finally set up and my tools are organized. What are we building next?

-

Alex: In our next episode, we are going to take everything we just learned about the interface and apply it to version control. We will be covering Git and Source Control directly inside VS Code. We will learn how to stage, commit, and push our code without ever leaving the editor. Thank you for listening to Gitt Going with GitHub, and we will catch you in the next episode.

-
- - -

Episode 12: Git and Source Control in VS Code

-

Cloning, branching, staging, committing, pushing, and pulling from VS Code.

-

Based on: Chapter 11: Git and Source Control in VS Code

- - -

Download Episode 12 (MP3)

-
-Read Transcript - Episode 12: Git and Source Control in VS Code - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode 12, Git and Source Control in VS Code. I am Alex, and I am here with Jamie.

-

Jamie: Hello everyone! I am really excited for this one. I feel like we have been building up to this moment for the entire series.

-

Alex: We absolutely have. In episode 3, we talked about the big concepts of Git, like repositories, branches, and commits. Then in episode 11, we got our VS Code environment set up, learned how to use the Command Palette, and got comfortable navigating the sidebar. Today, we are bringing those two worlds together. We are going to learn how to actually do Git operations right inside VS Code.

-

Jamie: And I want to say right up front to anyone listening, if this feels like a lot of steps, that is completely normal. I remember learning GitHub about two years ago, and I was terrified I was going to push the wrong button and delete someone else's code. But the beauty of Git is that it is actually really hard to permanently break things. And doing it in VS Code makes the heavy lifting so much easier.

-

Alex: That is a great point, Jamie. We are going to normalize that feeling of intimidation today. Because honestly, the workflow we are going to cover is the exact same workflow you will use whether it is your first day on a project or your tenth year as a senior developer.

-

Alex: Let us start at the very beginning. To work on a project, you need a copy of it on your computer. In Git terminology, this is called cloning a repository.

-

Jamie: I remember when I first started coding, before I knew Git, I would just go to a website, download a ZIP file of the code, and extract it to a folder. How is cloning different from just downloading a ZIP file?

-

Alex: That is the perfect question. When you download a ZIP file, you are just getting the files exactly as they exist at that exact second. It is a snapshot. But when you clone a repository, you are downloading the files plus the entire hidden history of the project. You get every commit, every branch, and most importantly, a permanent connection back to the original repository on GitHub.

-

Jamie: So it is like the difference between taking a photo of a document, versus having a live shared document where you can see all the version history.

-

Alex: Exactly. Now, there are a few different ways to clone a repository. The most accessible way, and the one we recommend for screen reader users, is using the VS Code Command Palette.

-

Jamie: Right, we talked about the Command Palette in the last episode. That is Control plus Shift plus P on Windows, or Command plus Shift plus P on a Mac.

-

Alex: Correct. When you open the Command Palette, you just type the words Git Clone. You will hear your screen reader announce Git: Clone as an option. You press Enter, and VS Code will ask you for the repository URL. You paste in the web address of the GitHub repository, press Enter again, and VS Code will open a standard file dialog asking where you want to save the folder on your computer.

-

Jamie: That sounds pretty straightforward. Navigate to the folder you want, press Enter, and it downloads everything. But I have also heard people talk about doing this in the terminal. Like using the words git clone or gh repo clone. What is the difference there?

-

Alex: Those are the command line alternatives. The standard Git command line interface, or CLI, uses the command git clone followed by the URL. That does the exact same thing as VS Code, it just does it in the terminal. Then there is the GitHub CLI, which is a separate tool you can install. Its command is gh repo clone. The neat thing about the GitHub CLI is that it already knows you are talking to GitHub. So instead of pasting a massive URL, you just type gh repo clone followed by the owner name, a slash, and the repository name. Like gh repo clone community-access slash learning-room.

-

Jamie: Oh, that is clever! It saves you from having to copy and paste full web addresses. But for today, we will stick to the VS Code Command Palette method. So, I have cloned the repository. I have the files on my computer. Before I start typing and changing code, I feel like I need a mental model of how Git tracks these files.

-

Alex: You absolutely do. Understanding the mental model is the secret to never getting lost in Git. There are three main areas you need to understand: the working tree, the staging area, and the repository.

-

Jamie: Okay, hit me with an analogy. I need a way to picture this.

-

Alex: Let us use a mailroom or a shipping department. Imagine you are putting together a care package for a friend.

-

Jamie: I love care packages.

-

Alex: Right. So, the room you are standing in, with tables and shelves and items scattered everywhere, that is your working tree. The working tree is just the actual files on your computer right now. You can pick things up, change them, break them, or create new things.

-

Jamie: So when I open a file in VS Code and type a new paragraph, I am messing around in the working tree.

-

Alex: Exactly. Now, eventually, you want to send some of these items to your friend. But you do not just throw the whole room into a truck. You get a shipping box. You take specific items from your workbench and you place them into the box. That box is the staging area. You are preparing a specific set of changes to be grouped together.

-

Jamie: And I can add things to the box, or take things out of the box, before I tape it shut.

-

Alex: Precisely. The staging area is where you build your next commit. Finally, when the box is perfectly packed, you tape it shut, stick a label on it describing what is inside, and put it on the outbound truck. Taping the box shut is creating a commit, and the truck takes it to the warehouse. That warehouse is the repository. The repository is the permanent, safe archive of all your sealed boxes.

-

Jamie: That makes so much sense. Working tree is the messy room. Staging area is the open box. Repository is the warehouse of sealed boxes. And I assume files can have different states depending on where they are in this process?

-

Alex: Yes. Git tracks files in three distinct states. First is untracked. This is a brand new file you just created. Git says, I have never seen this before, I am not tracking it. It is like a brand new item you just bought that is not on your inventory list yet.

-

Jamie: Okay. Untracked means brand new.

-

Alex: Second is modified. This means Git knows about the file, but you have changed it in your working tree, and you have not put it in the shipping box yet.

-

Jamie: Modified means changed, but still on the workbench.

-

Alex: And third is staged. This means you have moved that modified or untracked file into the staging area. It is in the box, ready to be committed.

-

Jamie: Untracked, modified, staged. I wish I had known that when I started. It makes the error messages make so much more sense when Git complains about modified files. So, how do we actually see these states in VS Code?

-

Alex: This brings us to the most important interface for Git in VS Code, which is the Source Control view. It lives in the Activity Bar on the far left of the screen, but you do not need to hunt for it. You just use the keyboard shortcut Control plus Shift plus G. That is G for Git. If you are on a Mac, it is Command plus Shift plus G.

-

Jamie: Control plus Shift plus G. I am pressing it now. What happens?

-

Alex: A side panel opens up, and your screen reader focus usually lands right in the middle of it. Let us break down the structure of this panel from top to bottom. At the very top is the Source Control title bar. This is actually super helpful because it announces the name of the branch you are currently on, like main or feature slash add-documentation.

-

Jamie: That is a nice quick way to check where you are without having to use the terminal. What is below the title bar?

-

Alex: Below that is a multi-line text input field. Your screen reader will call it Source Control Input. This is where you will eventually type your commit message, which is the label for your shipping box.

-

Jamie: Okay, so the text box is waiting for me. And below the text box?

-

Alex: Below the text box is the really magical part. It is a specialized tree view that lists your files. But it does not list all the files in your project. It only lists the files that have changed. It is divided into two collapsible sections. The bottom section is called Changes. This is your working tree. It shows all your modified and untracked files.

-

Jamie: So if I fix a typo in the readme file, the readme file will show up under Changes.

-

Alex: Exactly. And the section right above Changes is called Staged Changes. This is your shipping box. When you first open the panel, Staged Changes might be completely empty or even hidden, because you have not put anything in the box yet.

-

Jamie: How do I navigate this tree view with a screen reader? Is it just like a normal file explorer?

-

Alex: It is similar, but it has some special behaviors. For NVDA and JAWS users, you use your Up and Down arrow keys to move through the lists. When you land on a section header like Changes, your screen reader will say Changes, expanded, or Changes, collapsed. You can use your Right arrow to expand a section, and your Left arrow to collapse it.

-

Jamie: And when I arrow down onto an actual file, what does it say?

-

Alex: It will read the file name, the folder path, and the state. So it might say, index dot HTML, Modified. Or, styles dot CSS, Untracked.

-

Jamie: Okay, that sounds very efficient. I do not have to guess what I changed today, VS Code just gives me a tidy list of my messy workbench. Before we start moving things into the staging box, though, we should probably talk about branches. Because I know I am not supposed to do my messy work on the main branch.

-

Alex: That is a fantastic point. Whenever you want to make a change, whether it is fixing a bug or writing a new feature, you should create a new branch. A branch is basically an isolated copy of the code where you can experiment safely.

-

Jamie: Creating branches from the terminal always made me nervous. How do we do it in VS Code?

-

Alex: It is incredibly easy. We go back to our trusty Command Palette. Control plus Shift plus P. You type the words Create Branch. You will hear Git: Create Branch. Press Enter.

-

Jamie: And then it asks for a name?

-

Alex: Yes, a text input appears. You type your branch name. A quick tip on naming conventions: use lowercase letters and hyphens instead of spaces. So you might type, feature hyphen update hyphen readme. Then you press Enter.

-

Jamie: And that is it? Does it switch me to that branch automatically?

-

Alex: It does. VS Code creates the branch and immediately checks it out, which is Git terminology for switching to it. Your working files stay exactly as they were, but now Git knows that any new commits you make will be saved to this new branch, leaving the main branch perfectly safe and untouched.

-

Jamie: That takes so much anxiety out of the process. What if I need to switch back to the main branch to check something?

-

Alex: Command Palette again. Control plus Shift plus P. This time, type Checkout. You will select Git: Checkout to. A list of all your branches will appear. You just use your Up and Down arrows to find main, and press Enter.

-

Jamie: So I can bounce back and forth between branches just by searching for them. I love that. Okay, so I am on my new branch. I have made some changes to my files. I press Control plus Shift plus G to open the Source Control panel. I arrow down to the Changes section, and I hear that three of my files are modified. It is time to pack the shipping box. How do I stage a file?

-

Alex: Staging is very satisfying in VS Code. When you are navigating the Source Control panel and your screen reader focus is on a specific file under the Changes list, you have a couple of options. The fastest way is to just press the Spacebar, or press Control plus Enter. For Mac users, that is Command plus Enter.

-

Jamie: Wait, just pressing Spacebar moves it into the box?

-

Alex: Yes. The file immediately disappears from the Changes list and reappears up in the Staged Changes list. Your screen reader might not announce the move automatically, depending on your verbosity settings, but if you arrow up, you will find it sitting safely in the Staged Changes section.

-

Jamie: What if I change my mind? What if I put it in the box and realize I am not ready to ship it?

-

Alex: You do the exact reverse. You arrow up into the Staged Changes list, focus on the file, and press Spacebar or Control plus Enter again. It unstages the file. It takes it out of the box and puts it back on the workbench. The file itself does not lose any of your typed changes, it just changes its Git status.

-

Jamie: That is so forgiving. Now, you mentioned earlier that I had three modified files. What if I want to stage all of them at once? Do I have to press Spacebar on every single one?

-

Alex: You can, but there is a faster way. If you move your focus to the actual section heading that says Changes, expanded, you can open the context menu. For Windows users, you can press Shift plus F10, or the Application key if your keyboard has one. For Mac users, you can use VoiceOver keys plus Shift plus M.

-

Jamie: The context menu is like right-clicking with the mouse, right?

-

Alex: Exactly. When the context menu opens, you just arrow down to the option that says Stage All Changes, and press Enter. Boom. Everything on your workbench is swept into the shipping box.

-

Jamie: Okay, so why wouldn't I just do that every time? Why does Git even have a staging step? Why not just say, hey Git, save everything I just did?

-

Alex: That is the million dollar question. The reason Git has a staging step is to help you create atomic commits. Let us say you are working on a new feature, writing a bunch of new code. While you are doing that, you notice a really embarrassing spelling mistake in a completely unrelated documentation file. So you fix the typo, and you keep writing your feature.

-

Jamie: I do that all the time. I get distracted by typos.

-

Alex: Right! Now, at the end of the day, you have a bunch of changed files. If you just saved everything at once, your project history would have one giant commit that says, Added new feature and also fixed a typo. That makes it really hard for other developers to review your work.

-

Jamie: Oh, I see. With the staging area, I can put just the documentation file into the box, seal it up, and call it Typo fix. And then I can put all the feature files into a second box, and call that New feature.

-

Alex: Exactly. You stage individual files to group related changes together. In fact, VS Code even lets you stage individual lines of code within a single file. If you press Enter on a file in the Source Control panel, it opens a diff view showing exactly what lines changed. You can navigate to a specific line, open the context menu with Shift plus F10, and choose Stage Selected Ranges. It is incredibly powerful.

-

Jamie: Okay, that is a total power user move. Staging just a few lines of a file while leaving the rest unstaged. That is amazing. But let us stick to the basics for now. I have staged my files. They are in the Staged Changes list. The box is packed. How do I tape it shut and write the label?

-

Alex: It is time to commit. In the Source Control panel, you will press Tab or Shift plus Tab until your focus lands in the multi-line text field called Source Control Input. This is where you write your commit message.

-

Jamie: And writing a good commit message is an art form, isn't it? I know when I first started, my commit messages were literally just the word updates, or fixed stuff, over and over again.

-

Alex: We have all been there. But in open source, your commit messages are how you communicate with the maintainers. We use a convention called Conventional Commits. The subject line should be short, fifty characters or less, and it follows a specific format.

-

Jamie: What is the format?

-

Alex: You start with a type, then a colon, then a space, and then a short summary of what you did in lowercase letters. So for example, if you fixed a bug, you type the word fix, f i x, colon, space, and then something like correct heading hierarchy.

-

Jamie: Fix colon correct heading hierarchy. What if I am adding a new feature?

-

Alex: Then you use the word feat, f e a t. Feat colon add search button. If you are just updating documentation, you use docs, d o c s. Docs colon update screen reader instructions.

-

Jamie: That makes reading the project history so much easier. You can just scan down the list and see exactly what kind of work was done. So, I have typed my message into the input box. How do I actually execute the commit? Do I press Enter?

-

Alex: If you just press Enter, you will actually just create a new line in the text box, because it is a multi-line input. To actually execute the commit, you press Control plus Enter. Or Command plus Enter on a Mac.

-

Jamie: Control plus Enter. And what happens when I press it?

-

Alex: The text box clears out. The files disappear from the Staged Changes list. And your screen reader might announce that the commit was successful. You have officially sealed the shipping box.

-

Jamie: Success! My code is safe. But wait, where is it safe? Is it on GitHub yet?

-

Alex: Ah. This is the most common point of confusion for Git beginners. When you commit, you are only saving that snapshot to your local repository. The warehouse on your computer. GitHub has no idea that you just made a commit.

-

Jamie: So if I drop my laptop in a lake right now, that commit is gone forever.

-

Alex: Unfortunately, yes. To send your commits to GitHub, you have to perform an operation called a push. You are literally pushing your commits up to the remote server.

-

Jamie: Okay, how do I push?

-

Alex: The easiest way is back in the Command Palette. Control plus Shift plus P. Type Git Push, and select Git: Push. VS Code will contact GitHub and upload your commits.

-

Jamie: What if I get an error? I remember getting an error about no upstream branch when I tried to push my first branch.

-

Alex: Yes, the dreaded no upstream branch error. This happens because of the relationship between your local branch and the remote tracking branch. Think of your local branch like your personal private journal. You created it on your computer. GitHub does not have a journal with that name yet.

-

Jamie: So when I try to push, Git says, I do not know where to put this on GitHub?

-

Alex: Exactly. When you create a new branch locally and try to push it for the very first time, you have to publish the branch. In the VS Code Command Palette, instead of Git Push, you can select Git: Publish Branch. This tells Git to create a matching branch up on GitHub, and then push your commits to it. From then on, a normal Git Push will work perfectly.

-

Jamie: Git Publish Branch for the first time. Got it. Okay, so pushing is sending my stuff up. What about pulling? I hear people say they need to pull changes.

-

Alex: Pulling is the exact opposite. It is downloading new commits from GitHub into your local repository. Let us say you are collaborating with another developer. They push a new commit to the branch you are both working on. You need to download their work so your local files are up to date. You open the Command Palette, type Git Pull, and select Git: Pull. VS Code downloads their commits and merges them into your working tree.

-

Jamie: That sounds great, until we both edit the exact same line of code. What happens then? Does my computer explode?

-

Alex: No explosions, but you will get what is called a merge conflict. Git is very smart, but it refuses to guess which person's code is the correct one. If you both changed line 42 of the readme file, and you try to pull their changes, Git will stop and say, hey, I have a conflict here. You need to resolve this manually.

-

Jamie: We actually talked about the theory of merge conflicts in episode 6, but in VS Code, how does it handle it?

-

Alex: When a conflict happens during a pull, VS Code will show the conflicted files in your Source Control panel under a new section called Merge Changes. If you open one of those files, Git has literally injected both versions of the code into the file, separated by some markers like less-than and greater-than signs.

-

Jamie: That sounds a bit messy for a screen reader to read through.

-

Alex: It can be. The most accessible way to handle it is to open the file and press F7. F7 jumps you directly to the next conflict in the editor. Then you can press Alt plus F2 to open the Accessible Diff Viewer, which presents both versions very cleanly. You decide which version you want to keep, delete the other version and the markers, save the file, and then stage it just like a normal change.

-

Jamie: So a conflict is just a file that Git forces you to manually edit and stage again. That is not too scary. I also saw something in our notes about git pull dash dash rebase. What is a rebase?

-

Alex: Rebase is a slightly more advanced way to pull changes, but it is incredibly useful. Normally, when you pull someone else's changes while you have your own local commits, Git creates an extra merge commit to tie the two histories together. It can make the project history look like a messy subway map with lines crossing everywhere.

-

Jamie: And rebase prevents that?

-

Alex: Yes. Think of a rebase like stepping out of line at the grocery store. When you run git pull --rebase in the terminal, Git temporarily un-applies your local commits. It sets them aside. Then it downloads the other person's commits and applies them in a straight line. Finally, it takes your commits and replays them on top of the new history.

-

Jamie: Oh, wow. So it is like saying, let me pause my work, let you go first, and then I will do my work after you. It keeps the history as one perfectly straight timeline.

-

Alex: Exactly. It is a very elegant way to keep history clean, and many open source projects prefer you to use rebase when pulling updates from the main branch.

-

Jamie: So we have covered cloning, branching, staging, committing, pushing, and pulling, all using the VS Code interface. Are there other ways to do this? What if I am on a computer that does not have VS Code installed?

-

Alex: There is a fantastic web alternative. You can do almost all of this directly on GitHub dot com. If you navigate to a repository on the GitHub website, you can find any file, open it, and activate the Edit button, which visually looks like a pencil icon.

-

Jamie: And I can just type right there in the browser?

-

Alex: Yes, it opens a web editor. And here is the interesting difference. On the web, there is no staging step. When you finish editing, you just activate the Commit changes button. GitHub creates the commit directly, either on your current branch or it will automatically create a new branch for you.

-

Jamie: That is super fast for small changes, like fixing a single typo. But I imagine if you are changing five different files, navigating through the web interface for each one gets tedious.

-

Alex: Exactly. The web interface is brilliant for quick single-file edits. But when you are building a complex feature across multiple files, you want the control of VS Code, where you can stage specific files and review everything locally.

-

Jamie: And for the folks who love the terminal, they can do all of this using the Git CLI, right?

-

Alex: Absolutely. In VS Code, you can open the integrated terminal by pressing Control plus Backtick. From there, you can type git status to see your modified files, git add dot to stage all changes, git commit dash m to write your message, and git push. Many blind developers actually prefer the terminal because the output is pure plain text, which is very predictable for screen readers.

-

Jamie: That makes sense. It is all about finding the tool that fits your brain. But I have to say, the VS Code Source Control panel with Control plus Shift plus G feels like the perfect middle ground. It organizes the information visually and structurally, but gives you complete keyboard control.

-

Alex: Let us wrap up with some key takeaways from today's episode. Jamie, what is the first one?

-

Jamie: Takeaway number one: Understand the three environments. The working tree is your messy workbench. The staging area is the shipping box where you pack specific changes. And the repository is the permanent warehouse of sealed boxes.

-

Alex: Perfect. Takeaway number two: Use the Source Control panel in VS Code. Press Control plus Shift plus G to open it. It is a dedicated tree view that only shows your modified files, separated into Changes and Staged Changes.

-

Jamie: Takeaway number three: Staging is how you create atomic commits. You do not have to save everything at once. You can focus on a file, press Spacebar to stage it, and commit just that specific fix with a clear message.

-

Alex: And finally, takeaway number four: Committing only saves locally. Do not forget to push! You have to use Git Push to send your sealed boxes up to GitHub so everyone else can see them.

-

Jamie: This has been incredibly clarifying, Alex. I feel like I am ready to actually contribute code now. But once my code is pushed to a branch on GitHub, how do I actually ask the project maintainers to merge it into the main project?

-

Alex: That is the final piece of the puzzle. In our next episode, we are going to dive into the GitHub Pull Requests extension. We will learn how to create, review, and merge pull requests without ever leaving VS Code.

-

Jamie: I cannot wait. Thank you all for listening!

-

Alex: Thank you for joining us. Keep exploring, keep committing, and we will see you next time on Gitt Going with GitHub.

-
- - -

Episode 13: The GitHub Pull Requests Extension

-

Viewing, creating, reviewing, and merging PRs from inside VS Code.

-

Based on: Chapter 12: The GitHub Pull Requests Extension

- - -

Download Episode 13 (MP3)

-
-Read Transcript - Episode 13: The GitHub Pull Requests Extension - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode thirteen: The GitHub Pull Requests Extension. I am Alex, and I am here with Jamie.

-

Jamie: Hi everyone! I am so ready for this episode. We are at the point in the workshop where everything starts coming together.

-

Alex: We really are. If you have been following along, in episode six we covered the full pull request lifecycle from the web interface, using GitHub dot com. And in episode twelve, our last episode, we talked about doing local Git operations right inside Visual Studio Code.

-

Jamie: Right, so committing, branching, and pushing without ever leaving the editor. Which was a huge time saver.

-

Alex: Exactly. But what happens when you push that branch and you are ready to open a pull request? Or what if someone asks you to review their code? Up until now, you would have to switch over to your web browser, navigate GitHub dot com, find the pull request, and review it there.

-

Jamie: Which works! We learned how to do that, and it is fully accessible. But switching contexts between your editor and your browser all day can be exhausting.

-

Alex: It can be. And that brings us to the core concept of today's episode: The GitHub Pull Requests and Issues extension for VS Code. This extension essentially brings the GitHub website directly into your editor.

-

Jamie: I like to think of it like this. Imagine you are writing a book. Using the web interface for pull requests is like having to drive down to the post office every time you want to mail a chapter to your editor, and then driving back to the post office to pick up their feedback.

-

Alex: That is a great analogy.

-

Jamie: Right? But installing this extension is like having a direct mail chute installed right at your desk. You write the code, you package it up, and you send it off, all from the exact same chair. You even receive their feedback right on your original manuscript.

-

Alex: Perfectly said. The extension lets you view, create, review, and merge pull requests without ever pressing Alt plus Tab to open a browser. So, let us talk about how to get it.

-

Alex: To start using this, you need to install the extension and sign in.

-

Jamie: Okay, walk me through it. I am in VS Code.

-

Alex: First, open your Extensions sidebar. The keyboard shortcut is Control plus Shift plus X on Windows, or Command plus Shift plus X on Mac.

-

Jamie: Control plus Shift plus X. Got it. And that puts my focus in a search box, right?

-

Alex: Yes. Type in the words GitHub Pull Requests. You will hear your screen reader announce the search results. You want to navigate down to the one called GitHub Pull Requests and Issues, published by GitHub. Press Enter to open its detail page, Tab to the Install button, and press Enter again.

-

Jamie: Nice and easy. And since it is connecting to my GitHub account, I assume I need to log in?

-

Alex: You do. After it installs, VS Code will prompt you with a notification asking to sign in to GitHub. You can navigate to your notifications with Alt plus N on Windows, or Option plus N on Mac. When you activate the Sign In button, it briefly opens your web browser to authorize VS Code, and then sends you right back to the editor.

-

Jamie: And if I miss the notification, can I just use the Command Palette?

-

Alex: Absolutely. Just press Control plus Shift plus P, type GitHub Pull Requests Sign In, and press Enter. It does the exact same thing.

-

Jamie: Okay, I am installed and signed in. Where did my pull requests go? How do I find them?

-

Alex: The extension adds a brand new section to VS Code. If you are navigating the Activity Bar, it is a new icon that just says GitHub. But the most reliable way to jump straight to it with a screen reader is, as always, the Command Palette.

-

Jamie: Control plus Shift plus P.

-

Alex: Exactly. Press Control plus Shift plus P, and type Focus on Pull Requests View. When you press Enter, your focus moves to a new tree view in the sidebar.

-

Jamie: A tree view. So that means I am using my Up and Down Arrow keys to move through items, and Right Arrow to expand them.

-

Alex: Spot on. And this tree is organized brilliantly. It is like an email inbox that has already been sorted into folders for you. At the top, you have a section called My Pull Requests. If you expand that, you will find categories like Assigned to Me, Created by Me, and Waiting for my Review.

-

Jamie: Oh, that is incredibly helpful. So if I just want to see the things I am personally responsible for, I can just expand Assigned to Me.

-

Alex: Right. And as you arrow down through the list, your screen reader will announce the PR number, the title, the author, and the status. Something like: Pull Request number 42, Add Timeline Guide, opened by Jeff, 2 days ago.

-

Jamie: That is so much cleaner than tabbing through all the extra links and badges on the web interface. Though I should mention, if you prefer the web, or if you do not have VS Code open, you can still just navigate to the Pull Requests tab on your repository page on GitHub dot com.

-

Alex: Or use the GitHub Command Line Interface. If you have the gh CLI installed, you can open your terminal and type gh space pr space list. That prints out a beautifully clean text list of all open pull requests right in your console.

-

Jamie: So let us say I find Pull Request number 42 in that tree view, and I want to read it. What happens when I press Enter on it?

-

Alex: When you press Enter on a pull request in the tree, VS Code opens a Pull Request Detail View in your main editor area. This is a fully rendered, highly accessible document.

-

Jamie: What kind of information is in there?

-

Alex: Everything you would find on the Conversation tab on the web. It has the title, the description, the CI status checks telling you if the automated tests passed, a list of reviewers, and a section called Files Changed.

-

Jamie: Files Changed. That is the big one. That is where we see the diff, right? The actual code that was added or removed.

-

Alex: Exactly. A diff, short for difference, is the before-and-after comparison of the code. Now, you can review the diff simply by navigating to the Files Changed list in that detail view and pressing Enter on any file. It opens a split view or an inline view showing the changes.

-

Jamie: Okay, wait. Reading visual diffs with a screen reader used to be a nightmare for me. Hearing the screen reader try to parse out table columns, jumping between the old file and the new file. It was a lot of cognitive load.

-

Alex: It was. But VS Code has completely solved this with a feature called the Accessible Diff Viewer. This is perhaps the most important keyboard shortcut we will share today.

-

Jamie: I have my notepad ready.

-

Alex: When you have a diff open in the editor, press F7. This jumps your cursor directly to the first chunk of changed code, which is called a hunk.

-

Jamie: A hunk. I love programmer terminology.

-

Alex: It gets better. Once your cursor is on that change, press Alt plus F2 on Windows, or Option plus F2 on Mac. This opens the Accessible Diff Viewer.

-

Jamie: And what does that do?

-

Alex: It presents the change in a clean, sequential text format that is perfectly optimized for a screen reader. It announces exactly where you are, like Hunk 1 of 3. Then it reads the unchanged context lines, followed by the removed lines prefixed with the word Removed, and then the added lines prefixed with the word Added.

-

Jamie: Oh, that is brilliant. It is like comparing two drafts of a recipe. Instead of making you scan two pieces of paper side-by-side to figure out what changed, the Accessible Diff Viewer just reads it to you clearly: Removed: one cup of sugar. Added: two cups of sugar.

-

Alex: Exactly. And when you are done reading that hunk, you press Escape to close the viewer, and press F7 again to jump to the next change. It turns a frustrating visual layout into a logical, readable stream.

-

Jamie: And if I want to actually run their code to test it out? Can I do that?

-

Alex: Yes! That is called checking out a pull request. In the PR detail view, there is a Checkout button. When you activate it, VS Code downloads their branch to your local machine and switches your files over to their version. You can run the code, test it with your screen reader, and verify it actually works before you approve it.

-

Jamie: That is a massive advantage over the web interface. On the web, you can read the code, but you cannot easily run it.

-

Alex: Exactly. Though if you are using the terminal, you can achieve the same thing by typing gh space pr space checkout space 42. It pulls down the branch for pull request 42 instantly.

-

Jamie: Okay, so I am reading their code using the Accessible Diff Viewer, and I spot a mistake. They used a heading level two when it should have been a heading level three. How do I tell them?

-

Alex: You leave an inline comment. This is just like sticking a physical sticky note directly onto a specific line of a manuscript.

-

Jamie: How do I place the sticky note?

-

Alex: While you are in the diff view, navigate your cursor to the exact line with the mistake. Then, press Shift plus F10 on Windows, or Control plus Return on Mac, to open the context menu.

-

Jamie: Shift plus F10. Got it.

-

Alex: Navigate to Add Comment and press Enter. A text input box will appear right there in the editor. You type your feedback, like: This heading should be an H3 to maintain the document outline.

-

Jamie: And then I just hit submit?

-

Alex: You have two choices. You can choose Add Single Comment, which posts it to GitHub immediately. Or, you can choose Start Review.

-

Jamie: What is the difference?

-

Alex: Starting a review saves your comment as a draft. It lets you go through the rest of the files, leaving more comments as you go, without spamming the author with an email notification for every single typo you find. Once you are done looking at all the files, you submit the review all at once.

-

Jamie: That is polite. I appreciate that. So how do I submit the batch of comments when I am finished?

-

Alex: Open your Command Palette with Control plus Shift plus P, and type GitHub Pull Requests Finish Review.

-

Jamie: And that is where I give my final verdict, right?

-

Alex: Exactly. A prompt will ask you to choose a review type. You can select Comment, which just leaves your feedback without a formal decision. You can select Request Changes, which means the author must fix the issues before the code can be merged. Or, if everything looks great, you select Approve.

-

Jamie: And once I press Enter, all my draft comments and my final verdict are published to GitHub.

-

Alex: You got it.

-

Jamie: For folks tracking the alternatives, you can do all of this on the web by navigating to the Files Changed tab, finding a line, and activating the Add Comment button. And if you are a terminal fan, you can submit your verdict by typing gh space pr space review, followed by dash dash approve, or dash dash request dash changes.

-

Alex: So, we have covered reviewing other people's work. Let us flip the script. You have been writing code on a feature branch, you have committed your changes, and you have pushed them to GitHub. How do you create your own pull request from VS Code?

-

Jamie: I am going to guess it involves the Command Palette.

-

Alex: You know me so well. Press Control plus Shift plus P, and type GitHub Pull Requests Create. Select Create Pull Request, and a form opens right in your editor.

-

Jamie: What do I need to fill out in this form?

-

Alex: The most important concepts here are the Base branch and the Compare branch.

-

Jamie: Ah, yes. The terminology can be a little confusing at first. Base and Compare.

-

Alex: Let us use a highway analogy. The Base branch is the main highway. It is the destination. Usually, this is your main branch. The Compare branch is your car on the on-ramp. It is the source of the new changes you want to merge into traffic.

-

Jamie: That makes perfect sense. So my feature branch is the Compare branch, and I am requesting to merge it into the Base branch, which is main.

-

Alex: Exactly. VS Code usually selects these for you automatically, but it is good to verify them. After that, you just fill in the Title and the Description.

-

Jamie: On Day 1 of the workshop, when we opened pull requests on the web, we talked about Pull Request Templates. Those checklists that automatically populate the description box so you remember to test your code. Does VS Code support those?

-

Alex: It does! If your repository has a template file hidden in the dot github folder, the extension automatically loads it into your description field. You just use your arrow keys to navigate through the Markdown text, fill in the blanks, and put an X inside the brackets for the checkboxes.

-

Jamie: That is fantastic. It is literally the exact same workflow as the web.

-

Alex: It is. It maps perfectly to what you learned on Day 1. The underlying Git process is identical; you are just interacting with it through VS Code instead of a browser.

-

Jamie: Is there a way to open a Draft PR? Like, if I want to push my code to back it up and get early feedback, but I am not quite ready for a formal review?

-

Alex: Yes, there is a Draft PR checkbox right there in the creation form. If you check that, the PR is marked as a work in progress and cannot be merged until you mark it as ready. Once you have filled everything out, just Tab to the Create button and press Enter.

-

Jamie: And again, just to map this out for everyone: on the web, you would do this by pushing your code and then clicking the yellow Compare and Pull Request banner. In the CLI, you would just type gh space pr space create.

-

Alex: Alright, we have reached the final step of the lifecycle. The PR is open, the reviewers have approved it, and the CI checks are green. It is time to merge.

-

Jamie: The best feeling. How do we merge from VS Code?

-

Alex: Open the pull request in the PR detail view, scroll down to the bottom, and you will find a Merge Pull Request button. When you press Enter on it, you will be asked to choose a merge type.

-

Jamie: Merge types. This is where people get nervous. We have Merge Commit, Squash and Merge, and Rebase and Merge. Can we break those down?

-

Alex: Absolutely. Let us go back to our traffic analogy. You have a bunch of cars, which are your commits, waiting on the on-ramp, which is your feature branch. A Merge Commit is like a zipper merge. All of your individual cars merge onto the highway one by one, keeping their original identities, and a special sign is put up saying where they merged. It preserves your entire detailed history.

-

Jamie: Okay, what about Squash and Merge?

-

Alex: Squash and Merge is like taking everyone out of their individual cars and putting them all onto a single bus before they get on the highway.

-

Jamie: Oh, I love that.

-

Alex: It takes all of your tiny, messy commits, like "fix typo" and "forgot a semicolon", and squashes them into one single, clean commit on the main branch. This is incredibly common for feature branches to keep the project history tidy.

-

Jamie: And Rebase and Merge?

-

Alex: Rebase is like magically teleporting your cars so they were always on the highway to begin with. It replays your commits one by one at the very tip of the main branch, creating a perfectly straight, linear history without any merge signs.

-

Jamie: Which one should I use?

-

Alex: Always check your project's contributing guidelines. But if you are unsure, Merge Commit is the default and the safest option. Choose your strategy, confirm it, and the PR is merged.

-

Jamie: And then I should probably delete my feature branch, right? Keep the garage clean.

-

Alex: Exactly. VS Code will usually prompt you, asking if you want to delete the branch. Say yes. Then, use the Command Palette to check out your main branch and do a Git Pull, so your local machine gets the updated, merged code.

-

Jamie: And to round out our alternatives: on the web, this is the big green Merge button on the conversation tab. In the CLI, it is gh space pr space merge.

-

Alex: That covers the entire pull request lifecycle, entirely within VS Code. Let us recap our key takeaways.

-

Jamie: Takeaway number one: You do not have to leave your editor to collaborate. The GitHub Pull Requests extension lets you view, review, create, and merge PRs right where you write your code.

-

Alex: Takeaway number two: The Accessible Diff Viewer is a game changer for screen reader users. Remember to press F7 to jump to a change, and Alt plus F2, or Option plus F2 on Mac, to read the diff cleanly.

-

Jamie: Takeaway number three: The VS Code workflow maps exactly to the web workflow we learned on Day 1. The concepts of Base and Compare branches, PR templates, and Draft PRs are exactly the same. You are just using a different interface.

-

Alex: Perfectly summarized. Now that you are comfortable navigating code and collaborating in VS Code, you are ready for some artificial intelligence assistance. In our next episode, we are going to explore GitHub Copilot, and how it can help explain code, suggest changes, and write documentation.

-

Jamie: I cannot wait for that one. See you all then!

-

Alex: Thanks for listening to Gitt Going with GitHub.

-
- - -

Episode 14: GitHub Copilot

-

Inline suggestions, Copilot Chat, prompting strategies, and custom instructions.

-

Based on: Chapter 13: GitHub Copilot

- - -

Download Episode 14 (MP3)

-
-Read Transcript - Episode 14: GitHub Copilot - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub, the audio learning series for blind and low-vision developers who are mastering GitHub and open source collaboration. I am your host, Alex, and I am thrilled to be here with you today for episode fourteen, titled GitHub Copilot. Today, we are diving into the world of AI coding assistants.

-

Jamie: Hi everyone, I am Jamie. I am so excited for this one. I keep hearing developers talk about AI and Copilot, but I have been a little hesitant to jump in. I am really hoping we can break down how this actually works with a screen reader.

-

Alex: We absolutely will. Before we get into the new material, let us do a quick recap. In episode eleven, we covered the basics of Visual Studio Code. We talked about how to navigate the interface using your screen reader, how to open the command palette with Control plus Shift plus P, and how to manage your files. You will want to have those basic navigation skills fresh in your mind because Copilot lives right inside VS Code.

-

Jamie: I definitely recommend going back to episode eleven if you have not listened to it yet. Getting comfortable with the basic keyboard shortcuts in VS Code makes adding Copilot to the mix much easier. So, Alex, let us start at the very beginning. What exactly is GitHub Copilot?

-

Alex: At its core, GitHub Copilot is an AI pair programmer. But I like to think of it as a highly caffeinated, very well-read assistant sitting right next to you at your desk. As you type, it tries to guess what you are going to write next and offers suggestions. You can also talk to it conversationally and ask it questions about your project.

-

Jamie: When you say pair programmer, does that mean I only use this when I am writing code? Because as someone who is still learning, a lot of my open source contributions are actually documentation, writing issue responses, and formatting pull requests.

-

Alex: That is a fantastic question, and it is a huge misconception. Copilot is brilliant at non-code tasks. In fact, for this workshop, we are going to focus heavily on using Copilot to write Markdown documentation, draft commit messages, and review pull request descriptions. It understands human languages just as well as it understands Python or JavaScript.

-

Jamie: Oh, that is a relief. So how does it actually know what I am trying to do? Does it just read the current line I am on?

-

Alex: It reads much more than that. Copilot generates its suggestions based on context. Imagine you are cooking in a kitchen. A good sous-chef does not just look at the knife in your hand. They look at the ingredients you have already chopped on the cutting board, they look at the recipe book you have open on the counter, and they look at the pots on the stove. Based on all of that, they hand you the exact spice you need before you even ask for it.

-

Jamie: I love that analogy. So Copilot is looking at my whole kitchen.

-

Alex: Exactly. It looks at the file you are currently editing, where your cursor is positioned, other files you have open in your editor, and even the structure of your project. It gathers all of this context, sends it to the AI model, and returns a suggestion in milliseconds.

-

Alex: Let us talk about how these suggestions actually appear while you are typing. This is a feature called inline code completions. As you are typing a sentence or a line of code, Copilot will suddenly offer a completion for the rest of the line, or sometimes even an entire paragraph.

-

Jamie: I have heard sighted developers call this ghost text. What does that mean?

-

Alex: Yes, ghost text is the industry term for this. For a sighted user, the suggestion appears on their screen as light gray text just ahead of their cursor. It looks like a ghost because it is not actually part of the document yet. It is just a visual preview. But of course, visual previews are not helpful for us.

-

Jamie: Right. So how does my screen reader know the ghost text is there?

-

Alex: VS Code handles this beautifully by using an ARIA live region. When Copilot generates a suggestion, your screen reader will simply announce, suggestion available, or it will read the suggestion out loud, depending on how you have your verbosity settings configured.

-

Jamie: Okay, so I am typing, I hear suggestion available, and I want to accept it. What do I press?

-

Alex: You simply press the Tab key. Pressing Tab takes that ghost text and permanently inserts it into your document, moving your cursor to the end of the new text.

-

Jamie: And what if the suggestion is completely wrong? Like, it suggests I write about apples when I am writing about oranges.

-

Alex: You just press the Escape key to dismiss it. Or, honestly, you can just keep typing. The moment you type a letter that contradicts the suggestion, Copilot will dismiss it automatically and try to generate a new one based on your new keystrokes.

-

Jamie: That sounds easy enough. Tab to accept, Escape to dismiss. What if it gives me a suggestion, but I wonder if it has any other ideas? Can I ask for a different option?

-

Alex: You can. If you have a suggestion active and you want to see an alternative, you can press Alt plus the right bracket key. That will cycle to the next alternative suggestion. If you want to go back, you press Alt plus the left bracket key.

-

Jamie: Okay, that sounds like a lot of steps. I am imagining myself typing, getting interrupted by the screen reader, trying to cycle through options, and losing my train of thought.

-

Alex: It does sound intimidating! And it is completely normal to feel overwhelmed when your screen reader suddenly starts talking over you while you are trying to think. But here is the thing, you have already done most of this on Day one when we learned basic text editing. This is the exact same workflow, just with VS Code handling the heavy lifting of writing the text. And there are two incredible tricks to make this completely manageable.

-

Jamie: Please share the tricks, because I definitely need them.

-

Alex: The first trick is for when you only want part of the suggestion. Let us say Copilot suggests a whole sentence, but you only agree with the first few words. Instead of pressing Tab to accept the whole thing, you can press Control plus the right arrow key. This accepts the suggestion exactly one word at a time.

-

Jamie: Oh, that is clever! So I can just tap Control plus right arrow three times, take the first three words, and then just resume typing my own thought.

-

Alex: Exactly. It puts you completely in control. The second trick is even more important, and it solves the biggest current limitation with Copilot and accessibility.

-

Jamie: What limitation is that?

-

Alex: When Copilot generates a long suggestion, it streams the text in piece by piece, or token by token. For a sighted user, this looks like the text is being typed out really fast. But for a screen reader, this streaming effect can cause the live region to update repeatedly. It fragments the announcements. You might hear half a sentence, then an interruption, then the end of the sentence. It can be very noisy and hard to understand.

-

Jamie: Yes, I have experienced that with other AI tools. It is like someone trying to read you a letter while it is still coming out of the printer.

-

Alex: That is a perfect description. To solve this, VS Code has a feature called the Accessible View. Whenever you hear that a suggestion is available, do not press Tab yet. Instead, press Alt plus F2.

-

Jamie: Alt plus F2. What does that do?

-

Alex: It pauses the action and opens the complete suggestion in a separate, static text panel called the Accessible View. There is no streaming noise. There are no live region interruptions. It is just plain text. You can use your up and down arrow keys to read the suggestion line by line at your own pace.

-

Jamie: I wish I had known that when I started. So I press Alt plus F2, I read the suggestion in peace, and then what? How do I get it into my document?

-

Alex: While you are still inside the Accessible View, if you decide you like the text, you just press Control plus slash. That immediately inserts the suggestion into your document at your original cursor position and closes the Accessible View. If you do not like the suggestion, you just press Escape to close the view and go back to typing.

-

Jamie: That changes everything. Alt plus F2 to read it, Control plus slash to insert it. That feels so much more controlled.

-

Alex: Now that we have conquered inline suggestions, let us talk about the other half of GitHub Copilot. The Chat interface.

-

Jamie: This is where I can actually talk to it, right? Like a messaging app?

-

Alex: Exactly. You can open the Copilot Chat panel at any time by pressing Control plus Shift plus I. This opens a dedicated view in your sidebar. When you press Control plus Shift plus I, your screen reader will focus an input field. From there, you can ask questions in natural language.

-

Jamie: When you say natural language, do you mean I do not have to write code to talk to it?

-

Alex: Right. You just talk to it like you would talk to a human colleague. You could type, how do I create a pull request using the GitHub command line interface? Or, can you explain what this Markdown file is used for? Then you press Enter to send the message.

-

Jamie: And does the answer stream in and get all fragmented like the inline suggestions?

-

Alex: It does stream in, yes. But you can use the exact same trick. As soon as you press Enter to send your question, immediately press Alt plus F2 to open the Accessible View. The response will stream safely into that static view, and you can just use your arrow keys to read it. The Accessible View even formats code blocks and headings properly so your screen reader announces them correctly.

-

Jamie: That is so consistent. I love that the same shortcut works in both places. So, what if I want to ask a question about a specific file, or a specific part of VS Code? Does it just know what I am thinking about?

-

Alex: It is smart, but it cannot read your mind. To help Copilot understand exactly what you are asking about, we use Chat Participants. You can think of these like directing your question to a specific expert department in a massive company. You invoke them by typing the at symbol, followed by the participant name.

-

Jamie: Like tagging someone on social media?

-

Alex: Exactly like that. The three most common ones you will use are at workspace, at terminal, and at vscode.

-

Jamie: Let us break those down. What does at workspace do?

-

Alex: If you start your chat message with at workspace, Copilot will search across every single file in your current project folder to find the answer. So you could ask, at workspace, where do we document our accessibility guidelines? Copilot will scan the entire repository, find the contributing guide, and summarize the answer for you.

-

Jamie: That is incredible. It saves me from having to open a dozen files and use the find command. What about at terminal?

-

Alex: At terminal is a lifesaver when you get an error message on the command line that you do not understand. If you type at terminal, what does this error mean, Copilot will look at the recent text in your VS Code integrated terminal, read the error output, and explain it to you in plain English.

-

Jamie: Oh, I am definitely going to use that. Command line errors always look like a wall of gibberish to me. And the last one was at vscode?

-

Alex: Yes, at vscode. This participant is the expert on the VS Code editor itself. If you forget a keyboard shortcut, or you do not know how to change a setting, you just ask, at vscode, how do I turn on word wrap? It will give you the exact steps and the keyboard shortcuts.

-

Jamie: So participants tell Copilot where to look. Are there ways to tell Copilot what kind of action I want it to take?

-

Alex: Yes! For that, we use slash commands. If you type a forward slash in the chat input, you invoke a specific command. There are four major ones to memorize: slash explain, slash fix, slash tests, and slash doc.

-

Jamie: Those sound pretty self-explanatory, but let us go through them. Slash explain?

-

Alex: If you select a paragraph of complex text, or a dense block of code, and type slash explain, Copilot will break it down and explain how it works step by step. This is amazing when you are reading someone else's pull request and you cannot figure out what their code is doing.

-

Jamie: And slash fix?

-

Alex: If you select a broken piece of code, or even a Markdown table that is not formatted correctly, you type slash fix. Copilot will analyze the selection, figure out what is wrong, and propose a corrected version that you can accept.

-

Jamie: That is so much faster than hunting for a missing comma. What about slash tests and slash doc?

-

Alex: Slash tests will automatically generate unit tests for a function you have selected. And slash doc will automatically write the formal documentation block above a function or class. They are massive time savers for the repetitive parts of software development.

-

Jamie: Okay, so we have participants like at workspace to set the context, and commands like slash explain to set the action. I feel like I am learning a new syntax. But you said earlier I could just use natural language. Is there a trick to getting good answers when I am just typing regular sentences?

-

Alex: There is absolutely an art to it. We call it effective prompting. The biggest mistake beginners make is being too vague. If you type, write about accessibility, Copilot will give you a very generic, boring encyclopedia entry.

-

Jamie: So what makes a good prompt?

-

Alex: A good prompt is specific, it provides context, and it sets constraints. Think about ordering a sandwich at a deli. You do not just walk up and say, make me food. You say, I would like a turkey sandwich on rye bread, no mayo, add mustard, and please cut it in half.

-

Jamie: I am getting hungry. But I see your point. How does the sandwich order translate to Copilot?

-

Alex: Instead of saying, write about accessibility, you would say, write a three-paragraph section explaining how screen reader users can navigate the VS Code sidebar. Include keyboard shortcuts for NVDA. Assume the reader is a beginner. Use clear headings and bullet points.

-

Jamie: Wow, that is incredibly specific. You gave it the topic, the audience, the length, and the formatting.

-

Alex: Exactly. And the best part of effective prompting is iterating. Copilot remembers the conversation. So if it gives you an answer and it is a little too technical, you do not have to start over. You just reply, make that a little simpler, or, rewrite that in a friendlier tone. It will adjust the text immediately.

-

Jamie: Alex, I noticed in the settings there is a place to choose different AI models. What does that mean? Why are there different models?

-

Alex: That is a great observation. GitHub Copilot does not just rely on one single AI brain. It gives you access to multiple AI models from different companies, like OpenAI, Anthropic, and Google. You can switch between them using the model picker, which is a dropdown menu located at the bottom of the chat panel.

-

Jamie: Why would I want to switch? Are they really that different?

-

Alex: They are! Think of it like hiring different contractors for different jobs. If you select the GPT five mini model, it is incredibly fast and completely free to use. It is great for everyday questions and quick code completions. It is like riding a bicycle for a quick errand.

-

Jamie: But what if I have a really complex problem? Like a bug that spans across five different files?

-

Alex: Then you might want to open the model picker and select something like Claude Sonnet four point six, or GPT five point two. These models have much deeper reasoning capabilities. They are like renting a heavy-duty moving truck. They are slower, and if you are on a paid plan, they consume what are called premium requests, but they can handle incredibly complex logic.

-

Jamie: That makes sense. But honestly, having to choose which model to use every time I ask a question sounds exhausting.

-

Alex: I completely agree. And that is why the default setting in the model picker is simply called Auto mode.

-

Jamie: Auto mode. Let me guess, it chooses the vehicle for me?

-

Alex: Exactly. When you leave the model picker on Auto, Copilot evaluates your prompt behind the scenes. If you ask a simple question, it routes it to a fast, lightweight model. If you ask it to architect a complex new feature, it automatically upgrades to a heavy-duty model like Codex. It manages the cost and the speed for you, so you can just focus on writing.

-

Jamie: I will definitely be leaving that on Auto.

-

Jamie: So, Alex, I have a question about consistency. If I am working on an open source project, and we have very specific rules. For example, let us say our project requires all Markdown headings to use sentence case, and we never use the word click in our documentation. Do I have to type those rules into my prompt every single time I ask Copilot to write something?

-

Alex: That would be incredibly tedious. Thankfully, the answer is no. This brings us to one of the most powerful features for project maintainers: custom instructions files.

-

Jamie: Custom instructions. Is that a setting in VS Code?

-

Alex: It is actually a file you commit directly to your repository. You create a regular text file at the path dot github, slash copilot dash instructions dot m d.

-

Jamie: So it is just a Markdown file living in the dot github folder?

-

Alex: Exactly. And it acts like an employee handbook for Copilot. You can write your project's rules in plain English in that file. You might write, always write for screen reader users first. Never skip heading levels. Use imperative mood for commit messages.

-

Jamie: And Copilot just reads this file automatically?

-

Alex: Yes! Once that file is committed to your repository, Copilot silently reads it in the background every single time you ask a question or generate a completion. You never have to mention it. Copilot simply follows the rules of the house.

-

Jamie: That is brilliant. So if someone clones my repository and uses Copilot, their Copilot will automatically follow my accessibility rules?

-

Alex: Exactly. It is a fantastic way to enforce accessibility standards across an entire team without being a micromanager. Now, there is one more file type I want to mention, which is related to custom instructions, and that is prompt files.

-

Jamie: Prompt files. How are those different from the instructions file?

-

Alex: The instructions file is always on, in the background. Prompt files allow you to create your own custom slash commands that you invoke on demand. They are stored in the dot github, slash prompts folder, and they end with the extension dot prompt dot m d.

-

Jamie: Oh, I see. So earlier we talked about built-in commands like slash explain. I can make my own?

-

Alex: You got it. Let us say you do a lot of accessibility audits. You could create a file called dot github, slash prompts, slash audit dot prompt dot m d. Inside that file, you write a detailed prompt asking the AI to check for missing alt text, skipped headings, and improper link names.

-

Jamie: And then in the chat panel, I just type slash audit?

-

Alex: Exactly. You type slash audit, and Copilot executes that massive, detailed prompt perfectly every single time. It saves you from having to type out complex requests over and over again.

-

Jamie: Alex, this has been an incredibly packed episode. We went from ghost text to custom AI employees.

-

Alex: It is a lot to take in! But remember, you do not have to use all of this on day one. Start by just leaving Copilot turned on while you write, and get used to how it feels. Let us wrap up with our key takeaways for today.

-

Jamie: I will take the first one. When Copilot offers an inline suggestion, your screen reader will announce it. You can press Tab to accept the whole thing, Escape to dismiss it, or my favorite, Control plus the right arrow key to accept it one word at a time.

-
- - -

Episode 15: Accessible Code Review

-

Navigating diffs with a screen reader, reviewing PRs in browser and VS Code.

-

Based on: Chapter 14: Accessible Code Review

- - -

Download Episode 15 (MP3)

-
-Read Transcript - Episode 15: Accessible Code Review - -

Transcript

-

Alex: Welcome back to Gitt Going with GitHub. This is episode fifteen, Accessible Code Review. I am your host, Alex.

-

Jamie: And I am Jamie! I am so ready for this one.

-

Alex: Today is all about the reviewer experience. We are going to cover how to navigate file changes, read code comparisons, leave helpful comments, and submit your final review, entirely using your keyboard and screen reader.

-

Jamie: Before we jump in, let us quickly remind everyone of a couple of prerequisites. We will be building heavily on two previous episodes. First, episode six, where we introduced the concept of pull requests and the general review process. And second, episode eleven, which covered VS Code accessibility features. If you have not listened to those yet, you might want to open them up and give them a quick listen first.

-

Alex: Exactly. Now, in episode six, we talked about how a pull request, or PR, is a way to propose changes to a repository. You are literally requesting that the maintainers pull your code into their project. But before they do that, someone needs to review it.

-

Jamie: So, Alex, let us start with the big picture. Why is code review so important? When I first started learning GitHub about two years ago, I thought code review was just a way for senior developers to catch my typos.

-

Alex: That is a very common misconception. Code review does catch bugs, but it is fundamentally about quality and learning. It is a two-way street. The author gets another set of eyes on their work, and the reviewer gets to learn new techniques or familiarise themselves with a different part of the codebase.

-

Jamie: I love that. It reminds me of a writer's workshop. You do not just hand your manuscript to an editor to fix your grammar. You share it with peers. They might point out that a character's motivation is confusing, or they might learn a new way to write dialogue by reading your work.

-

Alex: That is a brilliant analogy. And just like a writer's workshop, building a habit of reviewing others' work regularly is one of the fastest ways to level up your own skills.

-

Jamie: I will be honest, though. Reviewing code still feels intimidating sometimes. Especially when I am looking at a pull request from someone who has been coding for ten years longer than I have.

-

Alex: It does feel intimidating! But here is the thing, you bring a unique perspective. Even if you do not catch a complex logic bug, you might catch an unclear variable name, or a missing documentation update. What we look for in a review really falls into four categories. Correctness, clarity, style, and accessibility.

-

Jamie: Correctness meaning, does the code actually do what it is supposed to do?

-

Alex: Right. Clarity means, is it easy to understand? Style means, does it follow the project's conventions? And accessibility means, does this change introduce any barriers for users with disabilities? You do not have to be an expert in all four to leave a valuable review.

-

Jamie: Okay, so I am sold on the why. Let us talk about the where. Where do we actually do these reviews?

-

Alex: You have two main environments for code review. The GitHub web interface in your browser, and your local code editor, which for our workshop is VS Code.

-

Jamie: Is one better than the other?

-

Alex: They just have different strengths. Both give you full keyboard and screen reader access. I like to think of the web browser as a quick chat at a coffee shop. It is great for quick reviews, leaving a few comments, and you can do it from any machine without downloading the code.

-

Jamie: And VS Code?

-

Alex: VS Code is like setting up in your home office for deep work. It is best for large reviews where you need to navigate through a lot of files, test the code locally, or use advanced screen reader features.

-

Jamie: I should also mention there is a third path, right? The GitHub CLI, or command line interface.

-

Alex: Yes, absolutely. The GitHub CLI is fantastic. You can open your terminal and type gh pr review to approve or request changes without ever leaving the command line. It is like the drive-through window of code review. Very fast, very efficient, but maybe not where you want to sit down and leave twenty detailed inline comments.

-

Jamie: Let us start with the coffee shop. The web browser. When I open a pull request on GitHub, how do I actually read the changes?

-

Alex: You need to navigate to the Files Changed tab. When you load a pull request page, you are usually on the Conversation tab, which has the description and the comments.

-

Jamie: Right, so how do I get to the files?

-

Alex: The most reliable way with a screen reader is to use your landmark navigation. Press the D key if you are using NVDA or JAWS, or use your VoiceOver landmarks rotor, to navigate to the Pull request navigation tabs landmark. From there, you can press the Right Arrow or Tab key to find the Files changed link, and press Enter.

-

Jamie: And when I open that, what am I actually listening to?

-

Alex: You are listening to a diff. Diff is short for difference. It is a format that shows exactly what changed between the old version of a file and the new version.

-

Jamie: I always explain a diff like a recipe where someone has crossed out a line and written a new one. Imagine a recipe card that says one cup of sugar, but the words one cup have a line through them, and next to it, someone wrote two cups.

-

Alex: That is exactly what a unified diff format looks like. It is called unified because it shows the old and new text combined into a single continuous flow. Every line in a diff is categorized in one of three ways. An addition line, a deletion line, or a context line.

-

Jamie: Let us break those down.

-

Alex: An addition line is new code that the author added. It starts with a plus sign prefix. A deletion line is code the author removed. It starts with a minus sign prefix.

-

Jamie: And context lines?

-

Alex: Context lines are the unchanged lines of code right above and below the changes. They do not have a plus or minus prefix. They are just there to give you context, so you know where the change is happening in the file.

-

Jamie: Okay, so I am on the Files Changed tab. How do I navigate through this diff?

-

Alex: First, orient yourself using the file tree. This is a region on the page that lists every changed file. You can navigate to the File tree region using your landmark shortcut, and just press the Down Arrow to move through the list. It will announce the file name, and how many additions and deletions it has.

-

Jamie: That is so helpful for getting a summary. If I see a file has five hundred additions, I know I need a coffee.

-

Alex: Exactly. Once you know what files you are dealing with, you can move to the actual code. Each changed file is presented under a heading level three containing the file name. So you can just press the number 3 key on your keyboard to jump from file to file.

-

Jamie: And what happens when I reach a file I want to read?

-

Alex: The diff for each file is structured as a table. Every row in the table is one line of code. To read it, you will navigate to the table using the T key. Then, and this is important, you need to turn on Focus Mode if you are using NVDA, or turn off the Virtual PC Cursor if you are using JAWS.

-

Jamie: Ah, right. Because in Browse Mode, pressing the Down Arrow just moves through the page structure. In Focus Mode, your arrow keys let you navigate the table cells directly.

-

Alex: Precisely. Once you are interacting with the table, you can press the Down Arrow to move through the lines of code one at a time. To read across the columns of a specific line, you press Control plus Alt plus the Right Arrow key. It will read the line number, then the change type, meaning whether it was added or deleted, and then the actual code content.

-

Jamie: Okay, so I am reading down the table, line by line. I hear a minus prefix, then a plus prefix, so I know a line was replaced. Let us say I spot a problem. The author changed a heading, but they skipped a heading level. They went from level two to level four. As an accessibility advocate, I know that breaks navigation for screen reader users. How do I tell them?

-

Alex: You need to write an inline review comment. This means you are attaching your comment directly to the specific line of code that has the issue, rather than just leaving a general comment at the bottom of the page.

-

Jamie: Like sticking a post-it note exactly on the sentence in a book that needs a rewrite.

-

Alex: Exactly. To do this, while your focus is on that specific line in the diff table, press the Tab key to look for a comment button. Or you can press the B key to navigate to the next button, which will say Add a comment to this line.

-

Jamie: Okay, that sounds like a lot of steps.

-

Alex: It does! But here is the thing, you have already done most of this on Day One of the workshop. It is the exact same workflow as opening an issue or replying to a discussion, just attached to a line of code. You press Enter on that button, an inline comment box opens, you switch to Focus Mode, and you type your feedback.

-

Jamie: What makes a good review comment? I remember early on, I would just write things like, this is wrong, or please fix. And people would get frustrated because they did not know what I wanted.

-

Alex: A helpful review comment is specific, educational, and graduated.

-

Jamie: Graduated? What does that mean?

-

Alex: It means signalling how important the comment is. Is it a strict requirement that blocks the pull request from merging, or is it just a stylistic preference? Using prefixes at the start of your comment is a great way to set expectations.

-

Jamie: Oh, I love prefixes. I use the word nit, spelled N I T, all the time. Like, nit, the link text says click here, which is not great for screen readers. Consider changing it to read the setup guide.

-

Alex: That is a perfect example. Nit means a non-blocking stylistic preference. Another good prefix is blocking. For your heading example, you could write, blocking, heading hierarchy violation. This skips level three. Please change to a level three heading before this merges.

-

Jamie: That is so clear. It names the issue, explains why it matters, and tells them exactly how to fix it.

-

Alex: Right. And once you type that comment, you tab to the button that says Start a review, and press Enter.

-

Jamie: Wait, why Start a review? Why not just click Add single comment?

-

Alex: If you use Add single comment, it posts immediately and sends an email notification to the author right then and there. If you leave ten comments, they get ten emails. Start a review batches all your comments together into a draft. When you are done looking at all the files, you submit the review all at once, and they get one single notification. It is much kinder to your teammates.

-

Jamie: Let us talk about that final submission. I have gone through all the files, I have left my post-it notes on various lines. How do I wrap this up?

-

Alex: You need to submit your review. You navigate to the top right of the Files Changed page, or the bottom of the Conversation tab, and find the Review changes button. Press Enter on that, and a dialog opens.

-

Jamie: This is where I give it my final grade, right?

-

Alex: Exactly. The dialog has a summary text area where you can write an overall thought, like, great work, just a few accessibility tweaks needed. Below that are three radio buttons for your verdict. Comment, Approve, or Request changes.

-

Jamie: Approve is pretty obvious. It means the code looks good to me, let us merge it. Request changes means I found a blocking issue, and they need to fix it before it can merge. What about Comment?

-

Alex: Comment means you have observations or questions, but you do not have a strong position on whether it should be blocked or approved. You are just leaving notes. Once you select your radio button, tab to Submit review, and press Enter.

-

Jamie: Okay, so that is the coffee shop experience. The web browser. It is incredibly powerful, but navigating those diff tables can get a little tedious if a pull request has hundreds of changes.

-

Alex: And that is exactly why we have the home office. VS Code. When you are dealing with a large review, VS Code offers a feature that completely changes the game for screen reader users. It is called the Accessible Diff Viewer.

-

Jamie: I remember the first time I used this. It was an absolute revelation.

-

Alex: How would you describe the difference between the browser diff and the VS Code Accessible Diff Viewer?

-

Jamie: In the browser, as we discussed, it is a big table. You have to navigate down rows, and across columns to figure out what line you are on, whether it is a plus or minus, and what the text says. The Accessible Diff Viewer is like a guided museum audio tour. It skips all the empty hallways and unchanged context lines, and just takes you straight to the exhibits that actually changed, and tells you exactly what happened to them.

-

Alex: That is a beautiful way to put it. Let us walk through how to use it. First, you open the pull request in VS Code. If you have the GitHub Pull Requests extension installed, you can open the Command Palette with Control plus Shift plus P, and search for GitHub Pull Requests View Pull Request.

-

Jamie: And once the pull request is open, the changed files appear in a tree on the sidebar. You navigate to a file and press Enter to open its diff editor.

-

Alex: Right. Now, when the standard diff editor opens, it is still a side-by-side visual comparison, which can be noisy. But here is the magic trick. Press the F7 key.

-

Jamie: F7. The magic button. What happens?

-

Alex: The Accessible Diff Viewer opens as a dedicated panel. Instead of a table, it presents each change, which programmers sometimes call a hunk, as a structured block of text designed specifically for sequential listening.

-

Jamie: So what does my screen reader actually say when I press F7?

-

Alex: It announces something like this. Changed lines fourteen to fourteen in docs slash keyboard-shortcuts dot markdown. Change one of three. Removed, heading level four, NVDA Single-Key Navigation. Added, heading level three, NVDA Single-Key Navigation.

-

Jamie: It is just so clean. It tells me exactly where I am, how many changes there are in total, and gives me clear Removed and Added labels. I do not have to guess what changed.

-

Alex: Exactly. And the navigation is purpose-built. You just press F7 again to jump to the next change. Or Shift plus F7 to jump to the previous change. You do not have to mess around with table navigation or focus modes. It just works with NVDA, JAWS, and VoiceOver right out of the box.

-

Jamie: And if I want to leave a comment while I am in VS Code?

-

Alex: You close the Accessible Diff Viewer by pressing Escape. That puts your cursor right back on the line you were just reviewing in the main editor. From there, you can open the Command Palette with Control plus Shift plus P, and select GitHub Pull Requests Add Comment. A text area opens, you type your comment, and submit it.

-

Jamie: And those comments sync directly back to GitHub, right? The author sees them on the web exactly as if I had used the browser.

-

Alex: Yes, they sync instantly. The author gets the exact same experience. They do not know or care which tool you used to write the review.

-

Jamie: This is so empowering. Whether I use the browser for a quick check or VS Code for a deep dive, I have complete access to the review process.

-

Alex: You do. And developing this manual review skill is critical. You need to know how to spot a heading hierarchy issue, or a missing alt attribute, or unclear link text yourself.

-

Jamie: Why is that so critical?

-

Alex: Because in our next episode, we are going to introduce Accessibility Agents. These are AI tools that can automatically scan a pull request and draft a review for you.

-

Jamie: Oh, wow. So the AI just does the review for me?

-

Alex: Not quite. The AI generates a draft. It will point out potential issues and suggest comments. But the AI does not have your human judgment. Your job shifts from finding every single issue manually, to reading the AI's draft, verifying if it is correct, and deciding what is actually worth saying to the author.

-

Jamie: I see. So if I do not know what a good review looks like, I will not know if the AI is giving me good advice.

-

Alex: Exactly. The manual skill is the foundation. The AI is just an amplifier.

-

Jamie: Let us wrap this up with a few concrete takeaways from today's episode. Number one, code review is a two-way street for quality and learning. It is not just about finding bugs, it is about improving the whole team.

-

Alex: Number two, you have two great environments. The browser is fantastic for quick, accessible reviews using landmark and table navigation. But for deep, line-by-line reading, press F7 in VS Code to open the Accessible Diff Viewer for a streamlined, sequential experience.

-

Jamie: Number three, when writing comments, be specific, educational, and graduated. Use prefixes like nit or blocking to clearly communicate your expectations to the author.

-

Alex: And number four, always use Start a review to batch your comments, rather than sending a dozen single comment notifications.

-

Jamie: This has been incredibly helpful. I feel like I am ready to go leave some blocking post-it notes on some pull requests.

-

Alex: I am sure your team will appreciate the thorough feedback. Thank you all for listening to Gitt Going with GitHub. In episode sixteen, we will dive into those Accessibility Agents and see how AI can speed up your workflow. Until then, keep practicing those reviews.

-

Jamie: See you next time!

-
- - -

Episode 16: Issue Templates

-

Creating YAML-based issue templates for bug reports, features, and custom forms.

-

Based on: Chapter 15: Issue Templates

- - -

Download Episode 16 (MP3)

-
-Read Transcript - Episode 16: Issue Templates - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode 16, Issue Templates. I am Alex, and as always, I am joined by Jamie.

-

Jamie: Hello everyone! I am very excited for this one because, if you remember way back in episode 5, we talked about how to file an issue. And I mentioned that staring at a completely blank text box was one of the most intimidating parts of learning GitHub for me. I never knew what information I was supposed to provide.

-

Alex: It is a universal feeling. You find a bug, you navigate to the Issues tab, you activate the New Issue button, and GitHub just hands you a blank page. You are left wondering, what do the maintainers actually need to know? Do they want my operating system? My screen reader version? Steps to reproduce?

-

Jamie: Exactly. And then you write what you think is a helpful description, and a day later a maintainer replies asking for exactly the details you left out. It is frustrating for everyone. It feels like a lot of unnecessary back and forth.

-

Alex: That is exactly the problem issue templates solve. Today, we are going to learn what issue templates are, how to use them, and most importantly, how to create them for your own repositories. We will cover where they live in your project, how to configure them, and the two different types of templates. We have traditional Markdown templates, and we have YAML form templates. We will talk about why YAML forms are a massive upgrade for screen reader accessibility.

-

Jamie: I love anything that makes screen reader navigation smoother. And just to remind our listeners, if you have not listened to episode 5 on working with issues, you might want to brush up on that first. But if you know how to navigate to the Issues tab and activate the New Issue button, you are ready for today.

-

Alex: Perfect. Let us start by defining what an issue template actually is. Think of an issue template like going to a new doctor. When you walk in, the receptionist does not just hand you a blank piece of paper and say, write down why you are here.

-

Jamie: Right, they give you an intake form. It asks for your name, your symptoms, your medical history, your current medications. It guides you to provide exactly what the doctor needs to know before they even see you.

-

Alex: Exactly. An issue template is an intake form for your GitHub repository. It turns that intimidating blank text editor into a structured guide. When contributors use a template, they provide the exact information you need to triage their issue. This drastically improves the quality of the issues you receive and reduces the burden on you as a maintainer. You spend less time asking follow up questions and more time actually fixing bugs.

-

Jamie: So as a user, when I activate that New Issue button on a repository that has templates set up, what actually happens? Because I know I do not just drop straight into a text editor anymore.

-

Alex: Right. When a repository has multiple templates, GitHub places a new step in between. You land on what is called the template chooser page. Your screen reader will announce a list of available templates. Each template appears as a card with a title, a short description, and a button that says Get started.

-

Jamie: So I might hear something like, Bug Report, report a problem with the software, Get started button. And if I press Enter on that button, then I am taken to the actual form.

-

Alex: Exactly. And the beauty of this template chooser page is that you, as the repository owner, can completely customize it using a special file called config dot y m l. That is spelled c o n f i g dot y m l.

-

Jamie: I have heard of YAML files before. Y A M L. It is a text format used for configuration, right?

-

Alex: Yes. YAML is a data serialization language, which is just a fancy way of saying it is a way to write structured data using plain text and indentation. It is very common for configuration files. In your config dot y m l file, you can control a few really important things about the template chooser page.

-

Jamie: What kind of things? Like adding more templates?

-

Alex: Actually, the templates themselves live in their own files. The config file is like the lobby directory of a large office building. It tells people where to go. One of the best features is that you can add external links. Let us say someone wants to ask a general question, not report a bug. You can add a contact link in your config file that points them to a GitHub Discussions board, or a community Slack channel.

-

Jamie: Oh, that is clever! So right on the page where they are about to file an issue, you can intercept them and say, hey, if you just have a question, go over here instead. That must save so much clutter in the issue tracker.

-

Alex: It really does. Another common use case for external links is security vulnerabilities. You never want someone posting a security flaw in a public issue. So you can add a link to the chooser page that directs them to a private security reporting form.

-

Jamie: That makes perfect sense. Now, what if I just want to write a regular issue? Can I bypass the chooser page and just get a blank text box?

-

Alex: By default, yes. At the bottom of the template chooser page, there is a link that says Open a blank issue. However, in your config dot y m l file, you have the power to turn that off. You can set a property called blank issues enabled to false.

-

Jamie: Wow. So you can force people to use your templates. That sounds a little strict, but I can completely see why a maintainer would do that. If you need their screen reader version to fix a bug, and they keep skipping the template, you just disable the blank issue option.

-

Alex: Exactly. For accessibility projects in particular, disabling blank issues is one of the most effective ways to improve the quality of incoming reports. An accessibility bug report without reproduction steps or assistive technology versions is almost impossible to triage.

-

Jamie: Okay, so we have the template chooser page, which is controlled by the config dot y m l file. Where do all these files actually live in my project?

-

Alex: They live in a very specific hidden folder. In the root directory of your repository, you will create a folder called dot github. Inside that dot github folder, you create another folder called ISSUE underscore TEMPLATE. That is all uppercase, issue underscore template.

-

Jamie: Okay, so the path is dot github slash issue underscore template. And inside that folder is where I put my config dot y m l file, and also all my actual template files.

-

Alex: You got it. Now, let us talk about how to build those template files. As I mentioned earlier, there are two ways to do this. The older, traditional way is using Markdown templates. These are files that end in dot m d.

-

Jamie: Markdown is the formatting language we use all over GitHub, right? With the hash symbols for headings and things like that.

-

Alex: Exactly. A Markdown template is essentially a text file that pre fills the issue editor. When a user selects your Markdown template from the chooser page, they are dropped into the standard issue text box, but the box already has text in it.

-

Jamie: Like a Mad Libs page! The headings are already there, and maybe some placeholder text, and I just have to type my answers in between the headings.

-

Alex: That is a perfect analogy. It is exactly like a fill in the blank Mad Libs page. To create one, you just create a Markdown file in your issue template directory. But there is a special section at the very top of the file called YAML front matter.

-

Jamie: Front matter. That sounds like the title pages of a book. What does it do?

-

Alex: Think of YAML front matter like a routing slip attached to the front of a physical file folder. It is a block of YAML code at the very top of your Markdown file, enclosed by three dashes at the top and three dashes at the bottom. This routing slip tells GitHub metadata about your template.

-

Jamie: What kind of metadata?

-

Alex: Five key things. First, the name of the template. This is what appears as the title on the template chooser page. Second, the description, which is the short text that appears under the name. Third, you can specify a title. This is really cool because you can pre fill the title of the issue itself. For example, you could have the title automatically start with a bracketed word like BUG, so every issue filed with this template has a consistent naming convention.

-

Jamie: Oh, I wish I had known that when I started. I always wondered how some projects had such perfectly formatted issue titles. What are the other two things in the front matter?

-

Alex: Labels and assignees. You can provide a comma separated list of labels, like bug or needs triage. When the user submits the issue, GitHub automatically applies those labels. And you can do the same with assignees, automatically assigning a specific maintainer to issues created with this template.

-

Jamie: That routing slip analogy is perfect. The front matter handles all the administrative sorting, labeling, and titling automatically. And then below those three dashes, I just write standard Markdown for the body of my template.

-

Alex: Exactly. You use hash marks for your section headings, like Steps to Reproduce, or Expected Behavior. You can also use HTML comments to leave instructions that the user can read, but that will not show up when the issue is finally published.

-

Jamie: Markdown templates sound really easy to set up. But you mentioned there was a second type. A YAML form template. Why would we use that instead?

-

Alex: Markdown templates are easy, but they have a massive flaw when it comes to accessibility and data consistency. Because a Markdown template just dumps text into a giant open text box, the user can do whatever they want. They can accidentally delete your headings. They can ignore your instructions. And most importantly, for a screen reader user, navigating a pre filled text box full of HTML comments and placeholder text can be incredibly noisy and confusing.

-

Jamie: That is so true. When I open a Markdown template, my screen reader just announces a massive block of text, and I have to use my arrow keys to carefully find the exact spot where I am supposed to start typing, making sure I do not accidentally delete the formatting. It is tedious.

-

Alex: Enter YAML form templates. These are files that end in dot y m l instead of dot m d. When a user selects a YAML form template, GitHub does not give them a single giant text box. Instead, GitHub generates a proper, accessible web form.

-

Jamie: Like a digital tax software wizard! Instead of handing you a blank tax form and saying good luck, the software asks you one question at a time with specific input fields.

-

Alex: Yes! A YAML form template creates distinct form fields. Each field has an explicit, programmatic label that your screen reader will announce. You navigate the template just like any other web form, pressing the Tab key to move from the operating system field, to the browser field, to the description field.

-

Jamie: That sounds so much better. What kinds of fields can we build with these YAML templates?

-

Alex: There are five main types you can define in your YAML file. The first is called markdown. This is not an input field, it is just static text. You use this to display instructions or warnings at the top of the form. Your screen reader will just read it as normal text content.

-

Jamie: Okay, so that is how I give them background information before they start typing. What is the next type?

-

Alex: The second type is input. This is a single line text field. It is perfect for short answers like a version number, or a URL. Your screen reader will announce it as edit text. The third type is textarea. This is a multi line text box. You use this for long form answers, like steps to reproduce, or describing the expected behavior.

-

Jamie: So if I want them to write a paragraph, I use textarea. If I just want a quick string of text, I use input.

-

Alex: Exactly. Now, the fourth type is where things get really powerful. Dropdown. This creates a select menu with predefined options.

-

Jamie: Oh, this is huge. Because if you ask people what operating system they use in a blank text box, one person writes Windows 11, another writes Win 11, another writes W 11. It is impossible to filter or search later. With a dropdown, you force them to pick from your exact list.

-

Alex: Precisely. And dropdowns are highly accessible. Your screen reader will announce it as a combo box. You press Down Arrow or Alt plus Down Arrow to expand it, and you can arrow through the specific choices. The fifth and final type is checkboxes. This creates a group of checkboxes that the user can toggle with the Space bar. This is fantastic for creating a pre submission checklist, like asking them to confirm they have searched for existing issues before filing a new one.

-

Jamie: Okay that sounds like a lot of steps to build all these fields. Do I have to write all of this YAML by hand?

-

Alex: It does sound like a lot! But here is the thing, you have already interacted with these exact types of fields whenever you use the web. You are just defining them in a text file. Each field in your YAML file gets a type, an ID, a label, and optionally a description and placeholder text. But the real magic of YAML form templates is validation.

-

Jamie: Validation? You mean making fields required?

-

Alex: Yes. In a Markdown template, someone can just submit a blank issue. In a YAML form template, you can add a property called required and set it to true for any input, textarea, or dropdown. If a user tries to submit the issue without filling out that field, GitHub stops them and displays an error. And yes, those errors are properly announced to screen readers.

-

Jamie: That is a game changer for maintainers. You can absolutely guarantee that every single bug report includes the screen reader version, because they literally cannot click submit until they provide it.

-

Alex: So, let us put this together and talk about the specific templates you might want to create for your projects. Every repository should generally have at least two templates. A bug report, and a feature request.

-

Jamie: Let us start with the bug report. Especially an accessibility bug report, since that is what our listeners are most likely dealing with. What should go into that template?

-

Alex: If you are building an accessibility bug report as a YAML form, you want to use dropdowns for the bounded information. You want a dropdown for the operating system. A dropdown for the screen reader, with options like NVDA, JAWS, VoiceOver on Mac, VoiceOver on iOS, and TalkBack. You want a dropdown for the browser.

-

Jamie: And I am guessing we want those all set to required equals true.

-

Alex: Absolutely. Then, you want textareas for the narrative information. You need a textarea for Expected Behavior, a textarea for Actual Behavior, and a critical textarea for Steps to Reproduce.

-

Jamie: I always struggle with what to write in Steps to Reproduce. How can we help users fill that out correctly?

-

Alex: That is where the placeholder attribute comes in. In your YAML file, you can define placeholder text that appears inside the empty textarea. Do not just write, enter steps here. Write an actual example. Number 1, navigate to the settings page. Number 2, activate the save button. Number 3, observe that focus is lost. By modeling good behavior in the placeholder, you teach the contributor exactly what you expect.

-

Jamie: That is a great tip. Okay, what about a feature request template? How is that different from a bug report?

-

Alex: A feature request template is about understanding a problem, not a system failure. So instead of asking for operating systems and browser versions, you ask different questions. You might have a textarea labeled Problem or Gap, where they explain what they are trying to achieve but cannot. Then another textarea labeled Proposed Solution, where they describe how they want the new feature to work.

-

Jamie: And maybe a checkbox at the bottom asking them to confirm that this feature has not already been requested by someone else.

-

Alex: Exactly. And the beauty of this system is that you are not limited to just bugs and features. You can create custom templates for literally any purpose. If you run a documentation repository, you can create a template specifically for requesting new tutorials. If you run a design system, you can create a template for proposing a new color token. You just name the YAML file whatever you want, put it in the issue template folder, and it will appear on the chooser page.

-

Jamie: Okay, so I have written my YAML file, I have added my dropdowns and textareas, and I have saved it in the dot github slash issue underscore template folder. How do I actually test it to make sure it works and is accessible?

-

Alex: Testing your templates is a crucial final step. The best way to do this is to commit your new template file to a branch and push it to your repository. You do not even have to merge it to your main branch yet. Once it is pushed, you navigate to the Issues tab on your repository and activate the New Issue button.

-

Jamie: And because I pushed the template, the template chooser page should appear, right?

-

Alex: Yes. You should see your new template listed there. Activate the Get started button for your template. This is where you do your screen reader testing. Do not just look at the code, actually navigate the generated form.

-

Jamie: Right, I would use my Tab key to move through the form. I want to listen carefully. Does the screen reader read the label clearly? Does it announce whether the field is required? When I open a dropdown, does it read all the options correctly?

-

Alex: Exactly. And try to submit the form while leaving a required field blank. Verify that your screen reader announces the validation error and moves focus appropriately. If everything sounds good, and the form guides you smoothly from top to bottom, your template is ready for the world.

-

Jamie: This really reframes how I think about issues. It is not just about complaining that something is broken. It is a structured conversation. And as a maintainer, you get to design exactly how that conversation flows by building a good template.

-

Alex: That is a beautiful way to put it. You are designing the contribution experience. A well designed YAML form template is an act of hospitality. It tells the contributor, we value your time, we want your feedback, and here is exactly how you can help us understand it.

-

Alex: We have covered a lot of ground today. Let us recap with some concrete takeaways. First, issue templates turn a blank text box into a guided intake form, improving the quality of contributions and saving maintainers time.

-

Jamie: Second, templates live in a specific folder in your repository. You navigate to the dot github folder, and inside that, you create an issue underscore template folder. That is where all your template files and your config dot y m l file will live.

-

Alex: Third, while you can use Markdown files for simple templates, YAML form templates are vastly superior for accessibility and data quality. They generate real web forms with explicit labels, structured dropdowns, and required field validation.

-

Jamie: And fourth, always test your templates with your screen reader. Make sure your labels are clear, your placeholder text is helpful, and your required fields are actually catching empty submissions.

-

Alex: If you are following along with the curriculum, your hands on activity for this chapter is to create a comprehensive accessibility bug report template using YAML, and submit it as a pull request to your fork. It is fantastic practice for writing YAML syntax and understanding form validation.

-

Jamie: But wait, earlier I asked if I really have to write all this YAML by hand. And you kind of dodged the question by saying it is just defining fields. Is there an easier way?

-

Alex: I am so glad you remembered that. Writing YAML by hand is a great way to learn the structure, which is why we teach it here. But in our next episode, Episode 17, we are going to introduce you to Accessibility Agents. Specifically, we will look at the Template Builder agent, an AI tool that will ask you conversational questions about what you want in your template, and then automatically generate the flawless YAML code for you.

-

Jamie: Oh, I cannot wait for that. No more worrying about missing colons or incorrect indentation!

-

Alex: Exactly. But understanding the concepts we discussed today is what makes you able to direct that agent effectively. Until next time, keep exploring, keep testing your forms, and we will see you in the next episode.

-
- - -

Episode 17: Accessibility Agents

-

Six agents, 28 slash commands, custom agents, and agentic accessibility workflows.

-

Based on: Chapter 16: Accessibility Agents

- - -

Download Episode 17 (MP3)

-
-Read Transcript - Episode 17: Accessibility Agents - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub, the audio series for blind and low-vision developers learning GitHub and open source. I am Alex, your lead host, and as always, I am joined by my co-host, Jamie.

-

Jamie: Hi everyone. I am Jamie. I am so ready for today. We are on Episode 17, which is called Accessibility Agents. And I have to admit, I peeked at the workshop materials for today and my mind is a little blown by what we are covering.

-

Alex: It is a big one. Today we are talking about specialized AI assistants that live right inside your editor and your repositories, designed specifically to help with accessibility tasks and GitHub workflows.

-

Jamie: Before we get too deep, we should probably remind everyone where we are coming from. If you are listening to this, you should have already completed the prerequisites we covered in a few earlier episodes. Specifically, Episode 11, where we talked about setting up VS Code extensions and settings, and Episode 14, where we covered GitHub Copilot Chat and how to interact with it.

-

Alex: Exactly. You need to know how to open Copilot Chat, which you can do by pressing Control plus Shift plus I on Windows, or Command plus Shift plus I on a Mac. If you are comfortable with that, you are ready for today.

-

Alex: Let us start with the big question. What exactly are accessibility agents?

-

Jamie: I know we have been using GitHub Copilot to help us write code and understand errors. Are agents just a different name for Copilot?

-

Alex: That is a great question. Think of GitHub Copilot as a general practitioner doctor. You can go to them with almost any problem, and they have a broad, baseline understanding of everything. They can help you with a lot of general coding tasks.

-

Jamie: Right, like asking it to explain a block of JavaScript or write a regular expression.

-

Alex: Exactly. But an accessibility agent is like a specialist. It is a cardiologist or a physical therapist. It is a custom AI assistant that extends GitHub Copilot with deep, specialized domain expertise. These agents know specific accessibility standards, they know how to audit document structures, and they know the exact workflows for managing GitHub repositories.

-

Jamie: Oh, I love that analogy. So instead of just asking general Copilot to check my code, I am bringing in an expert who only cares about keyboard navigation, or only cares about color contrast.

-

Alex: You nailed it. And this ecosystem is massive. There are currently fifty five different agents, organized into three distinct teams, and they run across five different platforms.

-

Jamie: Wait, fifty five? Okay, that sounds like a lot of steps. I am feeling a little intimidated just hearing that number. Am I supposed to memorize fifty five different AI assistants?

-

Alex: Not at all. And it is completely normal to feel overwhelmed by that number. But here is the thing, you have already done most of this on Day 1 of the workshop. Every single agent automates a sequence of steps you already know how to do manually. You do not need to use all fifty five. You just pick the ones that match the tasks you do every day.

-

Jamie: Okay, that makes me feel better. So what is the catch?

-

Alex: The catch is what we call the skill first principle. The agents are only useful if you have already done the work manually. An agent that summarizes pull requests is useless to someone who has never read a pull request. An agent that audits a web page for accessibility is useless if you do not understand the Web Content Accessibility Guidelines.

-

Jamie: That makes total sense. It is like power steering in a car. Power steering makes it much easier to turn the wheel, but it does not teach you how to drive. You still need to know the rules of the road and how to navigate. The agent does not teach you the skill, it multiplies a skill you already have.

-

Alex: That is a perfect comparison. So before you run any agent, ask yourself, could I do this task manually right now? If the answer is no, learn the manual skill first. The agents are designed to amplify your abilities, not replace your understanding.

-

Alex: Let us break down this ecosystem. I mentioned there are fifty five agents across three teams. Let us look at Team 1. This is the Accessibility team, and it is the largest, with twenty six agents.

-

Jamie: What kinds of specialists are on this team?

-

Alex: These agents audit, fix, and enforce accessibility across web, document, and mobile platforms. For example, there is an ARIA specialist for checking roles and states. There is a modal specialist that checks dialog focus trapping. There is a contrast master, a keyboard navigator, and agents specifically for auditing Microsoft Word, Excel, PowerPoint, and PDF documents.

-

Jamie: Wow. So if I am working on a complex data table, I can literally just call in the tables specialist agent to check my markup?

-

Alex: Exactly. Team 2 is the GitHub Workflow team, which has twelve agents. These automate GitHub operations. Things like issue triage, pull request reviews, contribution analytics, and repository management.

-

Jamie: Oh, I remember doing all of that manually in Episode 4 and 5. Navigating issues and reviewing pull requests takes a lot of time.

-

Alex: It does, and that is where these agents shine. Team 3 is the Developer Tools team, with six agents. These support accessible application development across desktop and cross platform frameworks. There is a Python specialist, a desktop accessibility specialist, and tools to help you build your own custom accessibility linters.

-

Jamie: You also mentioned they run on five platforms. Does that mean I have to leave VS Code to use them?

-

Alex: No, you can do everything right inside VS Code using GitHub Copilot. But the exact same fifty five agents are also available on Claude Code, Gemini Command Line Interface, Claude Desktop, and the Codex Command Line Interface. They are portable.

-

Jamie: So how do these teams actually work together? If I have a complex problem, do I have to talk to the keyboard navigator, and then separately talk to the contrast master?

-

Alex: You can, but you do not have to. This brings us to orchestrator agents. An orchestrator agent is like a general manager or a wedding planner. You give them the big picture goal, and they go hire the right specialists for the job.

-

Jamie: That sounds incredibly helpful. What are the names of these orchestrators?

-

Alex: There are a few key ones. In the GitHub Workflow team, there is an agent called at nexus. You literally type the at symbol, followed by the word nexus. At nexus handles cross agent orchestration for complex, multi step workflows. In the Accessibility team, there is at accessibility dash lead, which delegates audits to the various specialists. And there is at web dash accessibility dash wizard, which runs a full guided audit, invoking the contrast, keyboard, and forms specialists automatically.

-

Jamie: So if I am reviewing a pull request, how does that multi agent workflow happen in practice?

-

Alex: Let us walk through a real world example. Say you start your morning by asking the daily briefing agent what needs your attention. It flags a new pull request. Then, you ask the PR review agent to generate a structured review of that pull request. The review agent notices some changes to ARIA attributes, so it suggests you talk to the ARIA specialist. You invoke the ARIA specialist, it finds a missing expanded state on a button, and then you fix it. The teams connect naturally. The workflow agent tells you what happened, the accessibility agent evaluates if it is correct, and the developer tools agent helps you implement the fix.

-

Jamie: Okay, I am sold. How do I actually talk to these agents? You mentioned typing the at symbol.

-

Alex: Yes. To invoke an agent in Copilot Chat, you simply type the at symbol, and a list of available agents will pop up. You can use your arrow keys to navigate the list and press Enter to select one, or just type its name. For example, at daily dash briefing, followed by your request, like, morning briefing.

-

Jamie: That is easy enough. But what if I just want to run a quick command without having a whole conversation with an agent persona?

-

Alex: That is where slash commands come in. The ecosystem includes more than fifty four slash commands organized by workflow. You invoke them by typing a forward slash in the chat input.

-

Jamie: Oh, like how we use forward slash explain to ask Copilot to explain code.

-

Alex: Exactly. But these are custom slash commands built for our workflows. Let me give you some high impact starting points. These are the slash commands that save the most time.

-

Jamie: I have my notebook ready.

-

Alex: First is forward slash my dash issues. This gives you an instant dashboard of your open work across all repositories, complete with priority signals.

-

Jamie: That beats manually checking the notifications page and filtering by assigned issues.

-

Alex: It really does. Next is forward slash review dash p r, followed by the pull request number. So, forward slash review dash p r space pound fourteen. This generates a full AI generated review with inline suggestions, evaluating the risk level and summarizing the changes.

-

Jamie: Wait, does it actually post the review to GitHub automatically?

-

Alex: No, and this is a critical limitation we need to discuss. Agents suggest, humans decide and verify. The agent generates a draft review document in your chat window. It is your job to read it, edit it, make sure the tone is right, and verify that it did not miss any important context. Then, you post it under your own name.

-

Jamie: That goes back to the skill first principle. If I do not know how to review a pull request manually, I will not know if the agent gave me a good review or a terrible one.

-

Alex: Exactly right. A few other massive time savers to try first. Forward slash triage, followed by an issue number. This will suggest labels, priorities, and assignments for a new issue. Forward slash daily dash briefing gives you a morning snapshot of repository activity. And forward slash a eleven y dash update gives you the latest accessibility improvements across your repositories, complete with cross references to the Web Content Accessibility Guidelines.

-

Jamie: So how do I actually get all of these agents and slash commands onto my computer? Is it a complex installation?

-

Alex: It is surprisingly simple. There are two ways. For this workshop, the easiest way is to just fork the accessibility agents repository on GitHub, and then clone your fork to your local machine. When you open that folder in VS Code, Copilot automatically discovers the agents.

-

Jamie: Wait, that is it? No API keys or complex settings?

-

Alex: That is it. The agents live inside a folder called dot github, slash agents. Because they are just files in the repository, they travel with the code. If you clone a repository that has these files, you instantly have the agents.

-

Jamie: What if I want to use these agents on my own personal projects, not just the workshop repository?

-

Alex: Then you can use the quick install script. It is a single line you paste into your terminal. It detects what platforms you have installed and configures all fifty five agents globally on your machine. The exact commands are in the chapter text.

-

Jamie: I noticed you mentioned these agents are just files. How does a file tell the AI how to act like a specialist?

-

Alex: That is the magic of agent instruction files. Every agent is defined by a simple text file ending in dot agent dot m d. It is just a markdown file.

-

Jamie: So I can open these files and read them?

-

Alex: Absolutely, and you should. If you open the dot github slash agents folder, you will see files like issue dash tracker dot agent dot m d. If you read it, you will see it has two parts. At the top is some metadata, like the agent's name, a description of what it does, and what tools it is allowed to use.

-

Jamie: What do you mean by tools?

-

Alex: Tools give the agent permission to take actions. For example, an informational agent only needs permission to read files and search GitHub. But a task oriented agent might need permission to edit files, run shell commands, or create a pull request. Restricting tool access is a security best practice.

-

Jamie: That makes sense. What is the second part of the file?

-

Alex: The second part is the system prompt. It is plain English instructions. It is basically like writing a highly specific company employee handbook or a job description. You tell the agent its purpose, its domain knowledge, the step by step behavioral rules it must follow, and exactly how to format its output.

-

Jamie: If they are just markdown files, does that mean I can build my own custom agent?

-

Alex: You absolutely can, and that is one of the core exercises in the workshop. Building your own custom agent with agent dot m d files is how you tailor the AI to your exact workflow.

-

Jamie: How would I start doing that? Let us say I want an agent that specifically checks markdown files for accessibility errors, like making sure my heading levels do not skip from heading level one to heading level three.

-

Alex: You would create a new file in the dot github slash agents folder. Let us call it markdown dash assistant dot agent dot m d. At the top, you give it a name and tell it to use tools that let it read and edit files. Then, in plain English, you write its rules. You literally type, never skip heading levels. You tell it to verify that all images have alt text. You tell it to fix bare URLs.

-

Jamie: And once I save that file and reload the VS Code window, I can just type at markdown dash assistant in the chat?

-

Alex: Yes. And there are already real world examples of agent assisted contributions just like this. The GitHub Accessibility team actually published a complete walkthrough for building exactly the Markdown Accessibility Assistant you just described. It is a task oriented agent that not only reviews the file, but makes direct fixes.

-

Jamie: Oh, I love the idea of it making the fixes for me. But wait, what about things that require human judgment, like writing good alt text? I do not want the AI guessing what an image represents.

-

Alex: That is brilliant, Jamie, and it highlights a key pattern for custom agents called tiered decision making. When you write the agent's instructions, you tell it to fix objective issues automatically. Things like heading hierarchy or list structure. But for subjective issues, like alt text or plain language, you instruct the agent to flag the issue, suggest a fix, and wait for human approval before changing anything.

-

Jamie: That keeps the human in the loop for the important stuff, but automates the boring mechanical fixes.

-

Alex: Exactly. Let me give you another real world example from the workshop materials. There is an agent called at template dash builder. Creating GitHub issue templates manually requires writing YAML syntax, which is error prone and tedious. The template builder agent turns this into an interactive wizard.

-

Jamie: How does it do that?

-

Alex: You invoke it by typing at template dash builder, create accessibility template. Instead of just dumping code, the agent uses VS Code to ask you questions one by one. It asks, what is this template called? You type your answer. It asks, what field do you want to add? You type, screen reader dropdown. It asks what the options should be.

-

Jamie: So it interviews me, and then writes the YAML file perfectly based on my answers?

-

Alex: Yes. And if you want to change it later, you just tell the agent, add a checkbox for version compatibility, and it modifies the file for you. It takes a fifteen minute manual task and turns it into a two minute conversation.

-

Jamie: Everything we have talked about so far happens inside VS Code on my local machine. But what if I want an agent to do something automatically when I am not at my computer? Like, when someone opens an issue in my repository at three in the morning.

-

Alex: That brings us to agentic workflows. This is the bridge between the local agents we use in VS Code and cloud based automation. You can chain multiple agents together and run them on GitHub Actions infrastructure.

-

Jamie: So it works like an assembly line, where each station handles a specific task automatically?

-

Alex: Exactly. You can write a workflow file that says, whenever a new issue is opened with the word accessibility in the title, assign it to the accessibility team, add a needs triage label, and post a comment asking the user what screen reader they are using. The workflow runs serverlessly. No local machine required.

-

Jamie: That is incredibly powerful. But it all comes back to defining the intent in plain language, just like the local agents.

-

Alex: Yes. Understanding how to write local agent instructions in VS Code is the exact conceptual precursor to writing GitHub Agentic Workflows. Once you understand one, the other is immediately readable.

-

Jamie: We have covered so much ground today. The fifty five agents, the three teams, slash commands, building custom agents, and agentic workflows.

-

Alex: It is a massive topic. If you want to go deeper, and I highly recommend you do, check out Appendix V in the workshop materials. It is the complete reference for all fifty five agents, all fifty four plus slash commands, and all the customization formats.

-

Jamie: And there is an audio version for that too, right?

-

Alex: Yes, Episode 39 walks through the entire Appendix V reference step by step. It is a fantastic resource when you are ready to start building your own advanced workflows.

-

Jamie: So, Alex, what are the concrete takeaways for our listeners today?

-

Alex: I have three main takeaways. First, embrace the skill first principle. Agents do not teach you how to use GitHub; they multiply the skills you already have. Always do the task manually at least once before asking an agent to do it.

-

Jamie: Second, do not try to learn all fifty five agents at once. Start with high impact slash commands like forward slash my dash issues, or forward slash review dash p r. Let them save you time on tasks you already do every day.

-

Alex: And third, remember that agents suggest, but humans decide. Whether you are using a pre built agent or building your own custom agent dot m d file, you are responsible for the final output. Use tiered decision making to automate the objective tasks and keep yourself in the loop for the subjective ones.

-

Jamie: This has been such an eye opening episode. I am going to go play with the template builder agent right now. What are we covering in the next episode?

-

Alex: Next time, we are diving into Episode 18, which is all about GitHub Actions. We have touched on it briefly today with agentic workflows, but in the next episode, we are going to break down exactly how to automate your testing, your deployments, and your repository maintenance using continuous integration.

-

Jamie: I cannot wait. Thank you all for listening to Gitt Going with GitHub. We will see you in the next episode.

-
- - -

Appendices

-

Episode 18: Glossary of Terms

-

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

-

Based on: Appendix A: Glossary of Terms

- - -

Download Episode 18 (MP3)

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

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode eighteen, Glossary of Terms. I am Alex, and today we are doing something a little different. Instead of a step by step tutorial, we are taking a step back to build our vocabulary. If you are attending our two day workshop, this episode is your foundational reference guide.

-

Jamie: And I am Jamie. I am so glad we are doing this because when I started learning GitHub about two years ago, the jargon was honestly the biggest barrier. People would say things like, just fork the repo, clone it local, branch off upstream, and push a pull request. And my brain would just shut down. It sounded like a completely different language.

-

Alex: It really is a different language. And that is exactly why we want to normalize this right now. If you are feeling intimidated by the terminology, that is completely normal. You have already done most of the underlying workflows in your day to day life without realizing it. Today, we are just giving you the official names for those concepts so you can communicate effectively with other developers and open source maintainers.

-

Jamie: That is a relief. So, what is the plan for today?

-

Alex: We are going to break our glossary down into five main categories. First, we will cover the core version control terms, the absolute basics of Git. Second, we will move into GitHub specific collaboration terms. Third, we will untangle the web of remotes, things like upstream and origin. Fourth, we will define the accessibility terms we use throughout this workshop when we describe navigating the interface. And finally, we will cover terms related to artificial intelligence agents and GitHub Copilot.

-

Jamie: And just a quick reminder for our listeners, the prerequisite for this episode is simply a basic understanding of web navigation with your screen reader. We covered how GitHub structures its web pages in episode one, so if you need a refresher on that, feel free to navigate back to that episode.

-

Alex: Perfect. Let us dive right into category one, version control terms. And we have to start with the container that holds everything, the repository. You will almost always hear this shortened to repo. A repository is the main folder for an entire project. It holds all the files, all the documentation, and most importantly, the complete history of every change ever made to those files.

-

Jamie: I always like to think of a repository as a project folder that has a time machine built into it. If you have ever worked on a document and saved it as final version, then final final version, then absolute final version use this one, you were trying to do what a repository does automatically. It remembers every past state of your project.

-

Alex: That is a brilliant analogy. And the way it remembers those past states is through our next term, a commit. A commit is a saved snapshot of your changes at a specific moment in time. But it is not just hitting control plus S on your keyboard. When you make a commit, you are required to attach a message explaining what you changed and why you changed it.

-

Jamie: Right, it is like hitting save, but you have to attach a sticky note to the file explaining your thought process. I remember learning that a good commit message should complete the sentence, if applied, this commit will... so, if applied, this commit will fix the broken login button.

-

Alex: Exactly. Now, as your repository grows, you might want to experiment with a new feature without breaking the working version of your project. That is where a branch comes in. A branch is a separate, parallel line of development inside your repository. The default, stable version of your project lives on a branch usually called main. When you want to build something new, you create a new branch.

-

Jamie: This is my favorite concept. A branch is literally a parallel universe or an alternate timeline. You branch off from the main timeline, you make your changes in your own little universe, and the main timeline is completely unaffected. You can switch back and forth between these universes whenever you want.

-

Alex: And when you are happy with the work in your parallel universe, you need a way to bring those changes back into the main timeline. That process is called a merge. To merge is to combine the changes from one branch into another.

-

Jamie: But what happens if two people changed the exact same thing in their own parallel universes, and then they both try to merge back into the main timeline?

-

Alex: That brings us to a term that strikes fear into the hearts of many beginners, the merge conflict. A merge conflict happens when Git cannot automatically figure out which changes to keep. For example, if you changed the background of the website to blue, and I changed it to red on the exact same line of code, Git throws its hands up and says, I need a human to decide this.

-

Jamie: I used to panic when my screen reader announced a merge conflict. It sounds so aggressive. But it is really just Git pausing the process to ask for your help.

-

Alex: Exactly. And the way Git asks for help is by inserting special text markers into your file. When you are reading the file with your screen reader, you will hear a line of less than signs, followed by the word HEAD, which represents your current branch. Then you will read your changes. Then you will hear a line of equals signs, which divides your changes from the incoming changes. Then you read the other person's changes. And finally, a line of greater than signs. To fix it, you just delete the markers, keep the text you want, and save the file.

-

Jamie: That takes so much of the mystery out of it. Okay, so we have our repository, we make commits on branches, and we merge them together. But how do we get our code onto the internet or onto our computer?

-

Alex: That is where push and pull come into play. These are action verbs. When you push, you are uploading your local commits from your computer up to a remote server, like GitHub. When you pull, you are downloading new commits from GitHub down to your computer and merging them into your current branch.

-

Jamie: So push is upload, pull is download. But specifically for commits, not just loose files.

-

Alex: Spot on. Now, to do any pushing or pulling, you need the repository on your computer in the first place. This introduces two terms that confuse almost everyone at first, clone and fork.

-

Jamie: Oh, absolutely. I thought these were interchangeable for the longest time.

-

Alex: They are related, but very different. Let us start with fork. A fork is a personal copy of someone else's repository that lives on your own GitHub account. You do this when you want to contribute to a project where you do not have permission to make changes directly. You fork their project, which gives you a playground copy on your own GitHub account where you have full control.

-

Jamie: So a fork happens entirely in the cloud, on GitHub's servers. My analogy for this is walking into a library, finding a reference book you are not allowed to write in, and making a photocopy of it to put in your own personal locker. You can draw all over your photocopy.

-

Alex: I love that. Now, clone is the next step. Cloning is the act of copying a repository from the internet down to your local computer's hard drive so you can work on it in an editor like Visual Studio Code.

-

Jamie: Keeping with the library analogy, cloning is taking that photocopied book out of your locker and bringing it home to your kitchen table so you can actually work on it.

-

Alex: That is exactly right. You fork a repository to get your own copy on GitHub, and then you clone your fork to get it onto your laptop.

-

Alex: Let us transition into our second category, GitHub specific collaboration terms. Once you have made your changes and you are ready to share them, you will interact with the GitHub website. The absolute core of GitHub collaboration is the pull request, often abbreviated as PR.

-

Jamie: So a pull request, and I love this name because it tells you exactly what it is, is you literally requesting that the maintainers of a project pull your changes into their repository. You are saying, hey, I fixed that bug on my branch, please pull my branch into your main branch.

-

Alex: Precisely. When you open a pull request, GitHub provides a beautiful interface for discussing the proposed changes. Which leads us to a helpful feature, the draft pull request. Sometimes you want to show people what you are working on before it is actually finished. When you open a draft PR, it clearly signals to everyone that this is a work in progress. It prevents maintainers from accidentally merging it before you are ready.

-

Jamie: Draft PRs take so much pressure off. I use them all the time just to get early feedback on my approach. And speaking of feedback, that brings up the term review.

-

Alex: Yes, a code review is the process where other developers read through the changes in your pull request. They can leave comments on specific lines of code, they can approve the changes, or they can request modifications. It is a peer review system to ensure quality.

-

Jamie: And it is not just humans doing the reviewing, right? When I open a pull request, my screen reader always starts announcing things like, some checks haven't completed yet. What is a status check?

-

Alex: A status check is an automated test that runs against your pull request. Think of it like an automated bouncer at a club. Before your code is allowed to merge, the repository might have a robot automatically check if your code compiles, if it follows formatting rules, or if it passes accessibility scans. If the status check fails, you get a red X, and you usually cannot merge until you fix the issue.

-

Jamie: That is actually really reassuring. The robots catch my typos before the human reviewers even have to see them. Now, before you even write code or open a pull request, you usually start with an issue, right?

-

Alex: Correct. An issue is a tracking item in a GitHub repository. Despite the name, an issue does not just mean a problem or a bug. Issues are used to request new features, ask questions, or discuss ideas. Think of the issues tab as a combination of a to do list and a discussion forum for the project. Every issue gets a unique number, like issue number forty two, which makes it very easy to reference later.

-

Alex: Now we are moving into category three. This is where we untangle collaboration network terms. We are talking about local, remote, origin, upstream, and downstream. Jamie, I know this was a sticking point for you early on.

-

Jamie: Oh, it was a nightmare. I would read documentation saying to fetch from upstream and push to origin, and I had no idea where my code was actually going.

-

Alex: Let us break it down simply. Local refers to the files sitting physically on your computer's hard drive. When you are working offline in Visual Studio Code, you are working local. Remote refers to any version of the repository that is hosted on the internet, like on GitHub.

-

Jamie: Okay, so local is my laptop, remote is the cloud. That is easy enough. But what are origin and upstream? Because those are both remotes, right?

-

Alex: Yes, they are both specific names for remote repositories. Let us use the open source contribution workflow to explain them. Imagine you want to contribute to the official Python programming language repository. You do not have permission to change their code, so you fork it. Now you have a copy on your personal GitHub account. Then you clone your personal copy down to your local computer.

-

Jamie: Right, so I have my local copy on my laptop, and my personal fork on GitHub.

-

Alex: Exactly. From the perspective of your local computer, your personal fork on GitHub is called origin. Origin is the default name Git gives to the place you cloned from. It is your home base in the cloud. When you type git push, it sends your code to origin.

-

Jamie: Okay, so origin is my personal fork. Then what is upstream?

-

Alex: Upstream refers to the original repository that you forked from, in this case, the official Python repository. It is called upstream because changes flow down from it to you. If the maintainers of Python update their code, you need to pull those changes down to keep your fork up to date. You are pulling from the upstream source.

-

Jamie: That analogy actually makes perfect sense. Upstream is the original source of the river. Origin is my personal reservoir that I built by piping water from the river. And local is the glass of water sitting on my desk.

-

Alex: That is a fantastic way to visualize it. And just to complete the metaphor, downstream refers to anyone who forks your repository. To them, you are the upstream. It is all relative to where you are standing.

-

Alex: Let us shift gears to category four. Throughout this audio series and the two day workshop, we use specific accessibility terms to describe how to navigate GitHub and Visual Studio Code. We want to define those clearly so everyone is on the same page.

-

Jamie: Yes, and the most fundamental term we use is screen reader. A screen reader is assistive technology that converts digital text and interface elements into synthesized speech or Braille. Common ones are NVDA or JAWS on Windows, and VoiceOver on Mac. When we say, listen to what your screen reader announces, we are referring to the feedback from this software.

-

Alex: Next is a term crucial for efficient navigation, the landmark. A landmark is an invisible, structural tag applied to sections of a web page. Common landmarks include the banner, the main content area, navigation regions, and the footer.

-

Jamie: Landmarks are like teleportation pads. Instead of hitting the tab key a hundred times to get past the top menu, I can use my screen reader's shortcut, usually the letter D or the region navigation key, to jump instantly to the main landmark where the actual content begins.

-

Alex: Exactly. Similar to landmarks are headings. A heading is a structural element that acts like the outline of a document. They range from heading level one, which is usually the page title, down to heading level six for deeply nested subsections. When we tell you to navigate to the heading called Pull Requests, we are instructing you to use your screen reader's heading shortcut, usually the letter H, to jump directly to that section.

-

Jamie: And then there is a term that sounds like a musical concept, but it is actually highly technical. ARIA. Could you explain what ARIA is, and also clarify how to pronounce it? I have heard people say it a few different ways.

-

Alex: I pronounce it are-ee-uh. It stands for Accessible Rich Internet Applications. ARIA is a set of attributes that developers add to code to communicate complex interface behaviors to screen readers. For example, if a menu is collapsed, an ARIA attribute tells the screen reader to announce collapsed. When you press enter, the attribute changes, and the screen reader announces expanded. You do not need to know how to write ARIA to take this workshop, but you will hear us mention it when we explain why GitHub announces certain things.

-

Jamie: That makes sense. Two more accessibility terms we use constantly are focus and tab order. Focus refers to the specific element on the screen that is currently active and ready to receive keyboard input. If you type a letter, it goes into the element that has focus.

-

Alex: And tab order is the sequential path that your focus takes when you press the Tab key to move forward, or Shift plus Tab to move backward. A well designed page has a logical tab order that follows the visual reading order. When we say, move your focus to the commit button, we generally mean to tab through the interface until that button is the active element.

-

Alex: Finally, we arrive at category five. This workshop incorporates modern development tools, specifically artificial intelligence agents. The primary tool we use is GitHub Copilot.

-

Jamie: GitHub Copilot is incredible. It is an AI powered coding assistant built directly into Visual Studio Code and GitHub.com. But it does not just write code, right? We use it to explain error messages, write documentation, and even help us resolve those merge conflicts we talked about earlier.

-

Alex: That is right. And Copilot operates using what we call an agent. An agent is a specialized AI helper designed for a specific context. For example, in Visual Studio Code, there is a workspace agent that knows about all the files in your local repository. There is also a terminal agent that specializes in command line errors.

-

Jamie: And how do we talk to these agents? I know we use something called a slash command.

-

Alex: Yes, a slash command is a shortcut to give the agent a specific task. In the Copilot chat window, you literally type the forward slash character followed by a word. If you type slash explain, the agent knows you want an explanation of the code that currently has focus. If you type slash fix, it will analyze an error and propose a solution.

-

Jamie: After you use a slash command, you usually provide a prompt. A prompt is simply the human language instruction or question you are asking the AI. So you might type, slash explain, and then your prompt could be, what does this regular expression do?

-

Alex: Exactly. And the last term in this category is the instruction file. An instruction file is a plain text file you can add to your repository to give Copilot custom rules for your specific project. You can tell it things like, always write explanations at a beginner level, or, never use certain outdated functions. It is a way to tailor the AI's behavior so it aligns with your project's standards.

-

Alex: We have covered a massive amount of ground today. Let us quickly recap with some concrete takeaways. First, remember the fundamental Git workflow. You make a commit to save a snapshot of your work, you do this on a separate branch to isolate your changes, and then you merge it when you are done.

-

Jamie: Second, keep your remotes straight. Origin is your personal fork on GitHub. Upstream is the original project you want to contribute to. And local is the computer sitting in front of you.

-

Alex: Third, utilize pull requests and issues. Issues are where discussions and bug reports happen. Pull requests are where you actually propose the code changes to solve those issues. And do not be afraid to use a draft pull request to get early feedback.

-

Jamie: And finally, lean on the accessibility structures. Use landmarks and headings to jump around GitHub's interface quickly, rather than tabbing through every single link.

-

Alex: Well said, Jamie. Having this shared vocabulary is going to make the rest of the workshop so much smoother. In our next episode, we are going to dive into the magic of automation with GitHub Actions and Workflows. We will learn how to make the repository do the heavy lifting for us.

-

Jamie: I cannot wait for that one. Thank you all for listening, and we will see you next time on Gitt Going with GitHub.

-
- - -

Episode 19: Screen Reader Cheat Sheet

-

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

-

Based on: Appendix B: Screen Reader Cheat Sheet

- - -

Download Episode 19 (MP3)

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

Transcript

-

Alex: Welcome to Gitt Going with GitHub, the audio learning series for blind and low-vision developers who are mastering GitHub and open source collaboration. This is episode nineteen, titled Screen Reader Cheat Sheet. I am your host, Alex, and as always, I am joined by my fantastic co-host, Jamie.

-

Jamie: Hello everyone! I am so excited for this episode. If you are following along in the two-day workshop, we are looking at Appendix B today. And I have to admit, when I first started learning GitHub about two years ago, I felt like I was drowning in keyboard shortcuts. There are screen reader shortcuts, browser shortcuts, and GitHub shortcuts. It felt like trying to learn to play a piano with three different sets of sheet music at the same time.

-

Alex: That is a perfect analogy, Jamie. It can feel completely overwhelming at first. But the secret is that you do not need to memorize every single command to be successful. You just need to understand the underlying patterns. Once you understand how the piano is tuned, to borrow your analogy, you can play almost any song. Today, we are going to break down the essential keyboard commands for NVDA, JAWS, and VoiceOver, plus GitHub's built-in shortcuts, and even some critical commands for Visual Studio Code.

-

Jamie: And if you are listening to this and thinking, okay, that sounds like a lot of steps, please know that it is completely normal to feel that way. You have actually already done most of this on Day One of the workshop. We are just giving you the official names and the fastest routes for the workflows you already know.

-

Alex: Exactly. Before we dive into the specific keys, we have to talk about the most fundamental concept for screen reader users on the web. We need to talk about the two different modes that your screen reader uses. If you do not understand these two modes, GitHub will feel completely broken to you. These are Browse Mode and Focus Mode.

-

Jamie: Oh, this is the big one. I remember the exact moment this finally clicked for me. I was trying to leave a comment on an issue, and I kept pressing the letter H to type the word Hello, and instead of typing, my screen reader just kept jumping wildly around the page to different headings. I was so frustrated.

-

Alex: We have all been there! Let us define what is happening. Browse Mode, which JAWS calls the Virtual Cursor, is your primary mode for reading and navigating web pages. When you are in Browse Mode, your screen reader intercepts every key you press and uses it as a navigation command. So pressing the letter H tells the screen reader to jump to the next heading, rather than sending the letter H to the website.

-

Jamie: Right. And I like to think of Browse Mode like walking through a museum. You are moving from exhibit to exhibit, reading the plaques, taking in the structure of the room. You are observing, but you are not touching or changing anything.

-

Alex: I love that museum analogy. But eventually, you need to interact. You need to type a comment, or rename a file, or fill out a search box. That is where Focus Mode comes in. Focus Mode, which is sometimes called Forms Mode, tells your screen reader to stop intercepting your keys. It passes your keystrokes directly through to the web page.

-

Jamie: So sticking with the museum, Focus Mode is like stepping up to the guestbook at the end of the tour and picking up a pen. Now you are writing. You are interacting directly with the canvas.

-

Alex: Exactly. Let us talk about how to switch between these modes, starting with NVDA, which is the primary screen reader we use in this workshop. To toggle between Browse Mode and Focus Mode in NVDA, you press NVDA plus Space. You will hear a distinct sound. A higher pitched click means you entered Focus Mode, and a lower pitched clack means you went back to Browse Mode.

-

Jamie: And for JAWS users, the concept is the same, but the keystroke is Insert plus Z to toggle the Virtual PC Cursor on and off. Though JAWS is generally pretty good at switching into forms mode automatically when you navigate to an edit field, it is still crucial to know how to force it manually with Insert plus Z when things get stuck.

-

Alex: Now, VoiceOver on macOS handles this a bit differently. VoiceOver does not have a global Browse or Focus mode in the same way. Instead, you interact with specific elements. To type in a text box, you navigate to it and press VoiceOver keys, which are Control plus Option, plus Shift plus Down Arrow. This tells VoiceOver you are stepping inside that element to interact with it. When you are done typing, you press VoiceOver keys plus Shift plus Up Arrow to stop interacting and step back out.

-

Jamie: VoiceOver interacting always reminds me of opening a Russian nesting doll. You step down into the container to play with the pieces inside, and then you step back up and close the doll when you are finished.

-

Alex: So now that we understand our modes, let us talk about how we actually move around GitHub in Browse Mode. We will start with single-key navigation for NVDA and JAWS. VoiceOver users can also use these if they have Quick Nav turned on. The absolute most important key you will use on GitHub is the letter H, for Headings.

-

Jamie: Headings are the skeleton of any GitHub page. Pressing H jumps you forward to the next heading, and Shift plus H moves you backwards. But you can also be more specific by pressing the numbers one through six.

-

Alex: Yes, and GitHub is very consistent about how they use these heading levels. If you press the number one, you will jump to the main title of the page. On a repository page, the level one heading is the name of the repository itself. Pressing the number two will jump you to major sections, like the repository file tree or the README file.

-

Jamie: And the number three is my favorite shortcut on GitHub. Issue titles and Pull Request titles are always level three headings. So if you are on a page with a list of fifty open issues, you do not have to read through all the dates and labels and author names. You just rapidly press the number three to jump from one issue title to the next. It is incredibly fast.

-

Alex: It is a massive time saver. The next crucial navigation key is the letter D for NVDA users, or the letter R for JAWS users. This jumps you between Landmarks. Landmarks are named regions of the page, like the main content area, the navigation menu, or the sidebar.

-

Jamie: Landmarks are fantastic when you first land on a page and want to skip over the hundreds of navigation links at the top. You just press D until you hear Main Landmark, and you are right where the actual content begins.

-

Alex: Exactly. Next we have the letter K for Links, and the letter B for Buttons. You will use B constantly to find things like the Clone or Download button, or the Submit Comment button. And to find form fields, like the search bar or a comment box, you use the letter F, or the letter E in NVDA.

-

Jamie: We also have to talk about tables. GitHub uses tables to display the list of files in a repository. When you land on a repository page, pressing the letter T will jump you straight to that file table.

-

Alex: And once you are inside the table, you do not want to just use your standard up and down arrows, because that will read every single piece of information out of order. Instead, you hold down Control plus Alt, and then use your arrow keys. Control plus Alt plus Down Arrow moves you down the rows, so you can read the list of file names. Control plus Alt plus Right Arrow moves you across the columns, so you can read when that file was last updated or the commit message associated with it.

-

Jamie: Okay, Alex, those are a lot of single keys to remember. What if I am on a complex Pull Request page, and I cannot remember if the thing I want is a button, or a link, or a heading? I just know the name of it.

-

Alex: That brings us to your navigation superpower. The Elements List. If you only remember one thing from this entire episode, remember the Elements List. In NVDA, you open it by pressing NVDA plus F7. In JAWS, you can press Insert plus F6 for a headings list, or Insert plus F7 for a links list.

-

Jamie: The Elements List is like walking into a massive shopping mall and looking at the electronic directory board. Instead of wandering around hoping you bump into the store you want, you just pull up the master list.

-

Alex: Exactly right. When you press NVDA plus F7, a dialog box opens. It gathers every single link, heading, button, and landmark on the entire page and puts them into clean, alphabetical lists. You can use your Tab key to switch between the types of elements. But the best part is that you can type to filter. If you want to create a new issue, you just open the Elements List, make sure you are on the links or buttons tab, and type the word new. It instantly filters the list down to the New Issue button. You press Enter, and the screen reader activates that button for you.

-

Jamie: It feels like magic. And for our Mac users, VoiceOver has the exact same concept, called the Rotor. You open it by pressing VoiceOver keys plus the letter U. Then you use your left and right arrows to switch between lists of headings, links, form controls, and landmarks. You can type to filter the Rotor exactly the same way.

-

Alex: Let us transition to something unique to GitHub. Everything we just discussed relies on your screen reader doing the heavy lifting. But GitHub actually has its own internal system of keyboard shortcuts built directly into the website. These are JavaScript shortcuts that trigger actions without you needing to navigate to a button at all.

-

Jamie: And this is where the clash happens, right? Because if I press the letter G on GitHub, GitHub wants to use that as a shortcut. But my screen reader intercepts it and says, no, there are no graphics on this page, because G is the screen reader shortcut for graphics.

-

Alex: Precisely. This is why we spent so much time talking about Browse Mode and Focus Mode earlier. To use GitHub's built-in shortcuts, you must force your screen reader into Focus Mode. You press NVDA plus Space, or Insert plus Z for JAWS. Now, your screen reader goes to sleep, and your keystrokes go straight to GitHub.

-

Jamie: So what are these GitHub shortcuts? How do I even know what they are?

-

Alex: The most important shortcut to learn is the Question Mark key, which is Shift plus Forward Slash. If you are not inside a text box, pressing the Question Mark key opens a dialog on the screen that lists every single GitHub shortcut available for the exact page you are currently on.

-

Jamie: And it is context aware! If you press the Question Mark on a repository page, it shows you repository shortcuts. If you press it while looking at a Pull Request, it shows you Pull Request shortcuts. It is essentially a built-in cheat sheet that updates dynamically.

-

Alex: Let us talk about some of the most powerful ones. GitHub uses a lot of sequence shortcuts, where you press one key, let go, and then press a second key. The letter G is used for going places. If you enter Focus Mode and press G, pause for half a second, and then press I, GitHub will instantly teleport you to the Issues tab of the repository.

-

Jamie: I love the teleportation analogy. You do not have to find the navigation landmark, you do not have to tab through menus. You just type G then I, and boom, you are on the Issues page. And if you type G then P, you teleport to the Pull Requests page. It is like knowing the secret knock to get into different rooms.

-

Alex: Another essential one is the Forward Slash key. Pressing Forward Slash from anywhere on the page instantly moves your focus into the primary search bar. And what is great about the Forward Slash is that it often works even if you are still in Browse Mode, because it immediately moves browser focus to an interactive form field, which usually wakes your screen reader up automatically.

-

Jamie: Okay, what about finding a specific file? Because navigating the table with Control plus Alt plus arrows is great, but what if a repository has hundreds of files nested in dozens of folders?

-

Alex: Great question. GitHub has a file finder shortcut, which is the letter T. But we have a major conflict here. In NVDA, the letter T jumps to the next table. So if you are in Browse Mode and press T, you just jump to the file list. You must enter Focus Mode first by pressing NVDA plus Space. Then, when you press T, GitHub opens a search box that lets you type the name of any file in the entire repository and jump straight to it.

-

Jamie: That is a perfect example of why understanding the difference between your screen reader shortcuts and GitHub shortcuts is so critical. If you do not know about Focus Mode, you will press T and wonder why the file finder never opens.

-

Alex: Let us cover two more advanced GitHub shortcuts that are incredibly useful for collaboration. The first is the letter Y. Jamie, do you want to explain what the Y key does?

-

Jamie: Yes! The Y key expands the current web address into its canonical URL. Let me explain what that means. Let us say you are looking at a piece of code, and you want to send a link to your coworker pointing to line forty-two. You copy the link and send it. But tomorrow, someone else adds ten lines of code at the top of that file. Now, your coworker clicks your link, and line forty-two is completely different code. The link broke because the file changed.

-

Alex: Exactly. It is like giving someone directions to a house based on the color of the paint. If the house gets repainted, they are lost.

-

Jamie: Right! So when you are looking at a file, if you press the letter Y, GitHub changes the URL in your browser to a permanent, canonical link tied to the exact commit hash of that exact moment in time. It creates a GPS coordinate that never moves. Even if the file is updated a hundred times, that link will always show the exact version you were looking at.

-

Alex: That is a brilliant explanation. The last GitHub shortcut we will mention here is the letter L. When you are viewing an issue or a Pull Request, pressing L will open the Labels menu. From there, you can easily use your arrow keys to check or uncheck labels to organize the work. Just remember, L is another conflict key. In NVDA, L means next list. So you must be in Focus Mode to use the GitHub shortcut.

-

Alex: Now, the prompt for this episode specifically mentions our Concept Coverage Checklist, and one of the items we absolutely must cover is Visual Studio Code screen reader shortcuts. Even though this cheat sheet focuses primarily on the GitHub website, your workflow heavily involves taking code from GitHub and opening it in VS Code, or opening it directly in the browser using GitHub dot dev.

-

Jamie: And honestly, VS Code can feel even more intimidating than GitHub because it is a full Integrated Development Environment. It has sidebars, panels, terminals, and editor groups. Where do we even start?

-

Alex: The best place to start is with the Accessible Help Menu. VS Code has a dedicated help system designed specifically for screen reader users. You can access it by pressing Alt plus F2. This menu will dynamically explain the accessibility features of whatever part of VS Code you are currently focused on.

-

Jamie: Oh, that is clever! So if I am in the terminal and I press Alt plus F2, it tells me how to navigate the terminal. But if I am in the editor, it gives me editor tips. It is like having a specialized tour guide who taps you on the shoulder and whispers exactly what you need to know in that moment.

-

Alex: Exactly. And the second VS Code feature we must discuss is the Accessible Diff Viewer. A diff, short for difference, is how GitHub and VS Code show you what has changed between two versions of a file. Visually, this is usually shown with red and green highlighting. For screen reader users, reading a standard diff table line by line, trying to figure out what was added and what was removed, is agonizingly slow.

-

Jamie: It really is. You end up listening to the screen reader read twenty lines of code that did not even change, just to find the one word that was deleted.

-

Alex: This is why the Accessible Diff Viewer is a game changer. When you are looking at a file with changes in VS Code, you press F7 to jump to the next change, or Shift plus F7 to jump to the previous change. This opens a special accessible view that presents the changes as a clean, simple list. It will explicitly announce, for example, line thirty-two removed, followed by the old code, and then line thirty-two added, followed by the new code.

-

Jamie: It isolates the signal from the noise. It is like having a highly trained assistant who reads a hundred-page contract, but only reads you the three sentences that were actually modified. You do not have to sift through the entire document yourself.

-

Alex: That is exactly what it does. And you can use this same F7 navigation whether you are in your local desktop VS Code, or if you press the Period key on a GitHub repository to open the web-based VS Code editor in your browser.

-

Alex: Before we wrap up, let us run through a few quick navigation patterns for everyday tasks. We already talked about using H to jump to headings, and D or R to jump to landmarks. But what about when you want to actually leave a comment?

-

Jamie: This is a pattern you will use a dozen times a day. You open an issue. You press the letter D until you hear the Add a Comment landmark. Then you press the letter E to jump into the edit field. You switch to Focus Mode with NVDA plus Space, and you type your message.

-

Alex: And here is the pro-tip. When you are finished typing, you do not need to switch back to Browse Mode, press Tab to find the Submit button, and press Enter. That takes too long. While you are still in Focus Mode inside the text box, just press Control plus Enter. On a Mac, that is Command plus Enter. This is the universal submit shortcut across all of GitHub. It submits your comment instantly and saves you a ton of keystrokes.

-

Jamie: I wish I had known that when I started. Control plus Enter is burned into my muscle memory now. Another quick pattern is dealing with dropdown menus. When you press Enter on a button like Assignees or Reviewers, a popup menu appears. Do not try to use your screen reader's Browse Mode to read it. Just start typing to filter the list, use your up and down arrows to hear the filtered options, press Enter to select one, and then press the Escape key to close the menu.

-

Alex: That Escape key step is vital. GitHub applies your selections as soon as you press Escape to close the menu. If you try to navigate away without pressing Escape, the menu might stay floating open and trap your screen reader focus.

-

Jamie: So, if things ever feel stuck, or if your screen reader starts reading things that do not make sense, what is the best troubleshooting step?

-

Alex: The number one rule of troubleshooting on GitHub is to check your mode. Nine times out of ten, if something is not working, it is because you are in Browse Mode when you need to be in Focus Mode, or vice versa. Press NVDA plus Space or Insert plus Z to toggle your mode and try the action again.

-

Jamie: And if the page layout seems completely different than what we described, make sure your browser window is maximized. GitHub's interface is responsive, meaning it collapses sidebars and moves landmarks around if your window is too small. Maximizing the window ensures you get the consistent desktop layout.

-

Alex: Excellent point. Let us summarize our key takeaways for this episode. First, master the difference between Browse Mode for navigating, and Focus Mode for typing and using GitHub's built-in shortcuts. Second, rely on headings, landmarks, and the Elements List to jump through complex pages quickly.

-

Jamie: Third, remember the Question Mark key to open the context-aware shortcut cheat sheet on any GitHub page. And fourth, when you are in VS Code, use Alt plus F2 for accessibility help, and F7 to navigate diffs clearly.

-

Alex: Perfectly summarized. I highly recommend keeping Appendix B open in a separate window or printing it out to keep near your keyboard as you work through the workshop exercises. It will become your best friend.

-

Jamie: It really will. Muscle memory takes time, so be patient with yourself. You are learning a new language, and soon you will be speaking it fluently.

-

Alex: Thank you all for listening. In our next episode, episode twenty, we are going to dive deep into managing notifications. We will learn how to tame the GitHub inbox so you only see the alerts that actually matter to your work. Until then, keep practicing those shortcuts, and happy collaborating.

-
- - -

Episode 20: Accessibility Standards Reference

-

WCAG 2.2, ARIA roles, and the PR accessibility checklist.

-

Based on: Appendix C: Accessibility Standards Reference

- - -

Download Episode 20 (MP3)

-
-Read Transcript - Episode 20: Accessibility Standards Reference - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is Episode 20, Accessibility Standards Reference. I am Alex, and today we are going to talk about the rules of the road for making web applications and open source projects usable by everyone.

-

Jamie: And I am Jamie. If you are joining us at the workshop, you have probably heard these acronyms tossed around all week. Things like W C A G, or ARIA, or Level double A. To be honest, when I started learning GitHub two years ago, this alphabet soup was one of the most intimidating parts. I felt like I needed a law degree just to write a simple button.

-

Alex: That is such a common feeling, Jamie. It does sound like a lot of legal jargon. But here is the thing. You do not need to memorize these standards like a textbook. Today, we are going to give you a working understanding of the accessibility standards that govern the web, how they shape GitHub's interface, and most importantly, how they apply to the code you write and review.

-

Jamie: Okay, that sounds much more manageable. Just a reference guide, not a final exam. Where do we start?

-

Alex: We start with the big one. W C A G. You will often hear people pronounce this as wuh-cag. It stands for the Web Content Accessibility Guidelines. Right now, the standard most modern projects use is W C A G 2 point 2.

-

Jamie: Web Content Accessibility Guidelines. Okay. Who actually writes these guidelines? Is it a government?

-

Alex: Good question. No, it is not a government. It is maintained by the World Wide Web Consortium, or the W 3 C. They are the same international community that develops the standards for HTML and CSS. W C A G is essentially the global gold standard for what makes digital content accessible to people with disabilities, including screen reader users like many of our listeners.

-

Jamie: Got it. So if I want to make sure the pull request I am submitting to an open source project is accessible, W C A G is the measuring stick. But W C A G is massive. I have tried reading the official specification and it is incredibly dense. How do we break it down?

-

Alex: We break it down using an acronym. The four principles of W C A G are often abbreviated as POUR. P O U R. Perceivable, Operable, Understandable, and Robust. Every single rule in W C A G belongs to one of these four buckets.

-

Jamie: POUR. Okay, let us go through them. What does Perceivable mean in a coding context?

-

Alex: Perceivable means information and user interface components must be presentable to users in ways they can perceive. An analogy I like to use is going to a restaurant. If the menu is printed on paper, a sighted person can perceive it by reading it. But if you are totally blind, that paper menu is not perceivable to you. The information is there, but it is locked in a format you cannot access.

-

Jamie: Right. So in code, a classic failure of Perceivable would be an image that has no alternative text. If I am navigating a web page and my screen reader just says "image dot J P G", I get absolutely nothing out of it.

-

Alex: Exactly. To fix it, you add an alt attribute with descriptive text. Now the information is perceivable through an audio interface or a braille display. Another big part of Perceivable is contrast. W C A G has strict rules about text contrast against its background, which is crucial for low-vision developers. It also dictates that information cannot be conveyed by color alone.

-

Jamie: Oh, I have run into that one! A form where the instructions just say, "required fields are marked in red." My screen reader does not announce the color of the text by default, so I had no idea which fields were required. It was incredibly frustrating.

-

Alex: That is exactly why the Perceivable principle exists. Okay, let us move to the O in POUR. Operable. This means the user interface components and navigation must be operable by the user. Think of that same restaurant. Even if you can read the menu, can you physically open the door to get inside?

-

Jamie: So in web development, Operable is all about how we interact with the page. Keyboard accessibility has to be the biggest part of this, right?

-

Alex: It is the cornerstone. W C A G requires that all functionality must be available using only a keyboard. No mouse required. That means you should be able to navigate to every button, every link, and every form field using the Tab key, and activate them using the Enter key or the Spacebar.

-

Jamie: And avoid keyboard traps! I have to mention keyboard traps. A few months ago, I was reviewing a pull request for a custom modal dialog. I pressed the Tab key to move inside the modal, but then I could not Tab out of it, and pressing the Escape key did nothing. I was locked inside this pop-up window. I literally had to refresh the whole page to escape.

-

Alex: That is a perfect, and painful, example of a W C A G failure under the Operable principle. A user must always be able to move keyboard focus away from a component. Other Operable criteria include giving users enough time to read content before it times out, and providing ways to skip repeated blocks of content, like those "Skip to main content" links you hear at the top of accessible websites.

-

Jamie: Alright, we have P for Perceivable, O for Operable. Next is U for Understandable.

-

Alex: Understandable means information and the operation of the user interface must be, well, understandable. Going back to the restaurant, you got inside, you can read the menu, but what if the menu is in a language you do not speak, and there are no descriptions of the dishes? You cannot make an informed choice.

-

Jamie: How does that translate to code? Are we talking about plain language guidelines?

-

Alex: Partly, yes. But programmatically, it means things like identifying the default language of the HTML document using the lang attribute, so the screen reader knows which pronunciation engine to load. If the page is in French, but you do not tell the screen reader it is in French, it will try to read French words using English phonetics, which is entirely incomprehensible.

-

Jamie: Oh, I have heard that happen. It sounds like absolute nonsense. What else falls under Understandable?

-

Alex: Predictability. When a user navigates to a component, it should not trigger a massive, unexpected change in context. And error handling is huge here. If a user makes a mistake submitting a form, W C A G requires that the error is identified clearly in text, and suggestions for correction are provided. Just putting a red border around an invalid text input is not enough. You need a text message that says "Password must be at least eight characters."

-

Jamie: That makes sense. It is about not leaving the user guessing. So the last letter in POUR is R. Robust. What does Robust mean in this context?

-

Alex: Robust means content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. Think of it like building a sturdy foundation for a house. If you use standard, well-supported materials, the house will stand up to bad weather. If you use experimental or broken materials, it might collapse.

-

Jamie: So this is about writing clean, valid HTML.

-

Alex: Exactly. It means your HTML markup does not have major parsing errors, like elements missing their closing tags, or duplicate ID attributes. But the most critical success criterion under Robust is called Name, Role, Value. It states that for every single user interface component, its name, its role, and its current value must be programmatically determinable by assistive technologies.

-

Jamie: Name, Role, Value. We are definitely going to dig into that when we talk about ARIA later, because I know that is where ARIA does a lot of the heavy lifting. But before we move on from W C A G, I want to ask about the grading system. I always hear people say things like, "We are targeting W C A G double A compliance." What are the levels?

-

Alex: W C A G has three conformance levels. Single A, Double A, and Triple A. Think of them like building codes for accessibility.

-

Jamie: Okay, so what is Single A?

-

Alex: Level A is the absolute minimum baseline. It removes the most severe barriers that would make the site completely unusable for people with disabilities. Having some form of alt text, and being able to use a keyboard, are Level A. If you do not meet Level A, your site is broken for a lot of people.

-

Jamie: So Double A is the next step up.

-

Alex: Yes. Level AA includes all the requirements of Level A, plus additional criteria that remove significant barriers. This is the sweet spot. It is the target required by most accessibility laws, government standards, and enterprise policies. GitHub itself is officially committed to W C A G 2 point 2 Level AA compliance. When you are contributing to an open source project and they ask for accessibility, they almost always mean Level AA.

-

Jamie: Got it. So what is Level Triple A? Is that like achieving accessibility enlightenment?

-

Alex: Sort of. Level AAA includes all A and AA criteria, plus the strictest, most comprehensive rules. It removes remaining barriers for very niche cases. But the W 3 C actually states that it is not recommended to require Level AAA across entire sites, because for some complex content, it is practically impossible to achieve. You apply Triple A where it is feasible, but Double A is your mandatory target.

-

Jamie: Okay, so if I am writing code, I am aiming for W C A G 2 point 2 Level AA. And I am keeping POUR in mind. Perceivable, Operable, Understandable, Robust.

-

Alex: Exactly. And there are a few specific success criteria you will run into constantly as a developer. We already mentioned 1 point 1 point 1, which requires alt text for non-text content. And 2 point 1 point 1, which requires keyboard accessibility.

-

Jamie: What about focus indicators? I know that is a big one for sighted keyboard users and low-vision users.

-

Alex: Yes. That is criterion 2 point 4 point 7, Focus Visible. It is a Level AA requirement. It means that when you are navigating with a keyboard, there must be a visible outline or highlight showing you exactly which element currently has focus. And in W C A G 2 point 2, they added a new rule called Focus Appearance, which dictates the minimum size and color contrast of that focus indicator, so it is actually easy to spot.

-

Jamie: That is a great addition. I use screen magnification sometimes, and trying to find a tiny, faint gray dotted line around a button is nearly impossible.

-

Alex: So, we have covered the W C A G guidelines. Now we need to talk about the tools we use to meet those guidelines when standard HTML is not enough. This brings us to ARIA. A R I A.

-

Jamie: Yes, ARIA. I know it stands for Accessible Rich Internet Applications. But for the longest time, I thought ARIA was a totally separate programming language.

-

Alex: That is a very common misconception. ARIA is not a separate language. It is a set of specialized attributes you can add to your existing HTML elements.

-

Jamie: So why do we need it? If I write good HTML, is that not enough?

-

Alex: If you are writing a simple document with headings, paragraphs, standard links, and standard form fields, then yes, native HTML is absolutely enough. In fact, standard HTML is incredibly accessible right out of the box. But the modern web is not just documents anymore. It is full of complex, interactive widgets. Think about a drag-and-drop kanban board, or a multi-select combobox, or an expandable accordion menu.

-

Jamie: Right. HTML does not have a native tag for a kanban board.

-

Alex: Exactly. HTML has gaps. ARIA fills the gap between what native HTML can express and what complex interactive widgets require. Let me give you an analogy. Imagine a play at a theater. HTML is the script. It tells the actors what to say. But sometimes, a lot is happening on stage without any dialogue. Someone enters the room, someone looks angry, the lights go down.

-

Jamie: A sighted audience member can just watch that happen. But a blind audience member needs audio description to know what is going on.

-

Alex: Spot on. ARIA is the audio describer for your web application. It does not change how the application looks visually, and it does not change how the application behaves when you click on things. It only changes what is announced to the accessibility tree, which is what screen readers read from. ARIA whispers in the screen reader's ear, telling it the hidden context.

-

Jamie: That is a great way to think about it. It only affects the accessibility tree. So, if I add ARIA to a completely broken, unclickable div, it does not magically make it a working button.

-

Alex: Correct. Which brings us to the first rule of ARIA. This is so important I want you to remember it above everything else today. The first rule of ARIA is: Do not use ARIA if native HTML suffices.

-

Jamie: Do not use ARIA if native HTML works. Why is that?

-

Alex: Because native HTML elements come with built-in keyboard support and built-in screen reader support. If you use a native button element, the browser automatically knows it is a button, it automatically makes it focusable with the Tab key, and it automatically lets you activate it with the Enter key or the Spacebar.

-

Jamie: But if I use a generic div element, and I just add role equals button to it, what happens?

-

Alex: If you add role equals button to a div, your screen reader will announce it as a button. But that is all it does. It does not make it focusable. You would have to manually add a tabindex equals zero attribute. And it does not add keyboard support. You would have to write custom JavaScript to listen for the Enter key and the Spacebar.

-

Jamie: Okay, that sounds like a massive amount of extra work just to reinvent a button. I see why the first rule is to just use the native HTML tag.

-

Alex: Exactly. You only use ARIA when you are building something custom that HTML cannot handle. Now, ARIA is broken down into three categories. Roles, States, and Properties.

-

Jamie: Let us break those down. What is a Role?

-

Alex: A Role defines what an element actually is. It is the core identity of the component. We mentioned role equals button. There is also role equals dialog, for pop-up modal windows. Role equals navigation, for a block of navigation links. Once you set a role on an element, it does not change.

-

Jamie: Okay, so Role is the identity. What about States?

-

Alex: States describe the current condition of the element, and unlike Roles, States are meant to change as the user interacts with the app. For example, if you have a custom accordion menu, it might have aria dash expanded equals false when it is closed. When the user activates it, your JavaScript needs to update that state to aria dash expanded equals true.

-

Jamie: Ah, got it. Other states would be things like aria dash checked for a custom checkbox, or aria dash disabled if a button cannot be pressed right now. My screen reader reads those out automatically. It will say, "Submit, button, dimmed" or "button, disabled".

-

Alex: Exactly. And the third category is Properties. Properties are stable characteristics that provide extra context, but they do not change like States do. The most common property you will use is aria dash label. You use this to give an accessible name to an element when there is no visible text on the screen.

-

Jamie: Like an icon button! On GitHub, there is a button that just looks like a little gear icon to open the repository settings. There is no text that says "Settings". So they use aria dash label equals "Settings", and my screen reader reads that instead of just saying "unlabeled button".

-

Alex: Perfect example. Another extremely important set of ARIA roles are the Landmark roles. Landmarks let screen reader users jump directly to major sections of a page, bypassing all the clutter.

-

Jamie: Yes! I use landmarks constantly. In NVDA or JAWS, I just press the D key to jump from landmark to landmark. Or if I am on my Mac using VoiceOver, I open the Rotor and navigate by landmarks. It is how I get around complex pages like a GitHub repository.

-

Alex: GitHub uses landmarks beautifully. The main ones you will encounter are the banner role, which is the site-wide header at the top. The navigation role, for menus. The main role, for the primary content of the page. And the contentinfo role, which is usually the footer.

-

Jamie: I have noticed that on GitHub, there are often multiple navigation landmarks on the same page. There is the main site navigation, the repository navigation, the sidebar. How do I know which is which?

-

Alex: That is a great point, and it is a W C A G requirement. When you have multiple landmarks of the same type on a single page, each one must have a unique aria dash label to distinguish them. So GitHub will label one as "Site navigation" and another as "Repository navigation". When you press the D key, your screen reader announces the label along with the landmark role.

-

Jamie: That is incredibly helpful. Before we move on to code reviews, I want to ask about one more ARIA feature. Live regions. I have heard developers talk about aria dash live. What does that do?

-

Alex: Live regions are magic for single-page applications. Imagine you are filling out a form, and you type in a username. A little message pops up on the screen dynamically that says "Username is available." If you are sighted, you see it appear. But if you are using a screen reader, your focus is still inside the text box. You do not know that new text appeared somewhere else on the page.

-

Jamie: Right. Unless I manually navigate around the whole page looking for changes, which is tedious.

-

Alex: So, you wrap that message container in an attribute called aria dash live. When you inject new text into an aria-live region, the browser automatically sends that new text straight to the screen reader to be announced aloud, without moving the user's focus.

-

Jamie: Oh, that is how that works! I love when applications do that. It makes it feel so snappy. I type my name, and I just hear "Username is available" in the background. Are there different types of live regions?

-

Alex: Yes, there are two main settings. Aria dash live equals polite, and aria dash live equals assertive. Polite means the screen reader will wait until it finishes its current sentence before announcing the update. This is what you should use 95 percent of the time. Assertive means the screen reader will immediately interrupt whatever it is currently saying to announce the update. You should only use assertive for critical, urgent errors.

-

Jamie: Okay, so we have covered W C A G and the POUR principles. We have covered ARIA, including Roles, States, Properties, Landmarks, and Live Regions. Now, let us make this practical. I am working on an open source project on GitHub. I get assigned to review a pull request, or PR, from another contributor. How do I review their code for accessibility?

-

Alex: Reviewing a PR for accessibility is just like reviewing it for security or performance. It is a checklist. And it is completely normal to feel a little intimidated when you are checking someone else's code. But you already know the fundamentals.

-

Jamie: So what is on the PR Accessibility Checklist? What are the red flags I should be looking for before I approve and merge someone's code?

-

Alex: First, check the HTML structure. Did they add any new images? If yes, verify that every single image tag has an alt attribute. Even if it is a purely decorative image, it needs an empty alt attribute, literally just alt equals quote quote. That tells the screen reader to safely ignore it.

-

Jamie: Got it. Check for alt text. What next?

-

Alex: Next, look at any new interactive elements. Did they add a new button, a dropdown, or a custom widget? If so, you must verify that it is fully keyboard accessible. Can you reach it with the Tab key? Can you activate it with the Enter key or the Spacebar? And does it have a visible focus indicator when you tab to it?

-

Jamie: Okay, so I am checking for the Operable principle. What about forms?

-

Alex: If the PR adds any new form fields, check that every input has an associated label element. The HTML label tag needs a "for" attribute that exactly matches the "id" attribute of the input field. This is what guarantees that when a screen reader lands on the text box, it reads the correct label aloud.

-

Jamie: I will also check for color reliance. If the PR notes say "Error states are now highlighted in red," I am immediately going to flag that and ask, "Is there also a text explanation or an icon for the error?" Because color cannot be the only indicator.

-

Alex: That is fantastic, Jamie. That is exactly the right mindset. And finally, check for dynamic content. If the PR introduces a feature that updates the page without a full reload, like a search filter or a shopping cart counter, check if they used an aria-live region to announce those updates to screen reader users.

-

Jamie: Okay, let us say I find an issue. The contributor created a custom toggle switch using a div, and there is no keyboard support and no ARIA role. How do I write that feedback in the PR review without sounding like the accessibility police?

-

Alex: The best way to leave feedback is to be specific, objective, and reference the standard. Do not just say, "This toggle is not accessible." Instead, say something like, "This custom toggle switch cannot be operated with a keyboard, which is a barrier for screen reader and keyboard-only users. This fails W C A G 2 point 1 point 1 Keyboard. Could we update this to use a native HTML checkbox, or add role equals switch and keyboard event listeners?"

-

Jamie: I like that. It removes the emotion from it. You are not saying they wrote bad code, you are just pointing out that it misses a specific, documented requirement, and you are offering a path to fix it.

-

Alex: Exactly. And while you can catch a lot of things by reading the code, you should also test it. There are automated tools you can use, like the axe DevTools browser extension, which will scan the rendered page and catch about 30 to 40 percent of W C A G violations automatically.

-

Jamie: Only 30 to 40 percent? That is lower than I expected.

-

Alex: It is. Automated tools are great for catching missing alt text or missing labels, but they cannot tell if the alt text actually makes sense, and they cannot test keyboard flow. That is why manual testing is required. The best way to test a PR is to pull the branch to your local machine, unplug your mouse, turn on your screen reader, and try to use the new feature. If you can complete the task smoothly, it is likely in good shape.

-

Jamie: Wow, we covered a massive amount of ground today. I actually feel like I have a solid grasp on W C A G and ARIA now. It is not just alphabet soup anymore.

-

Alex: You absolutely do. Let us recap the concrete takeaways from today's episode. First, W C A G is the global standard for web accessibility, built on four principles: Perceivable, Operable, Understandable, and Robust. Or POUR.

-

Jamie: Second takeaway: The standard target for GitHub and most open source projects is W C A G 2 point 2 Level AA compliance.

-

Alex: Third, ARIA is a set of attributes that fills the gaps in native HTML by providing Roles, States, and Properties to the accessibility tree. But remember the first rule of ARIA: Do not use ARIA if native HTML suffices.

-

Jamie: And finally, when reviewing a pull request, use your accessibility checklist. Look for alt text, verify keyboard accessibility, ensure forms have labels, and check that dynamic updates use aria-live regions. Unplug your mouse and test it yourself.

-

Alex: Perfect summary. You do not need to be an accessibility expert to make a huge impact on an open source project. Just keeping these fundamentals in mind during your code reviews will make the web better for everyone.

-

Jamie: So what is up next?

-

Alex: In Episode 21, we are moving from theory to practice. We will be diving into the GitHub Interface Deep Dive. We will explore exactly how GitHub's web interface is structured, how to navigate its complex landmark architecture, and the specific keyboard shortcuts that will make you incredibly fast at triaging issues and reviewing code.

-

Jamie: I cannot wait for that one. Thanks for listening to Gitt Going with GitHub. We will see you in the next episode!

-
- - -

Episode 21: Git Authentication

-

Personal access tokens, SSH keys, credential storage, and commit signing.

-

Based on: Appendix D: Git Authentication

- - -

Download Episode 21 (MP3)

-
-Read Transcript - Episode 21: Git Authentication - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode twenty-one, Git Authentication. I am Alex, and as always, I am here to help you navigate the world of Git, GitHub, and open source collaboration.

-

Jamie: And I am Jamie! I am here to ask the questions, share my own learning bumps, and hopefully make this journey a little smoother for you. And Alex, today we are talking about a topic that caused me more stress than learning Git itself when I started two years ago. Authentication. Proving to GitHub that I am who I say I am.

-

Alex: You are definitely not alone in that, Jamie. Authentication is a major hurdle for a lot of developers. You spend all this time writing code, you make your commit, you type your push command, and then the terminal just throws up an error and refuses to let your code through. It feels like getting stopped at the door of a party you were invited to.

-

Jamie: Exactly! The bouncer is just standing there shaking their head. So, to set the stage for everyone, why is authentication needed in the first place? We can read repositories and clone open source projects without ever logging in, right?

-

Alex: That is exactly right. If a repository on GitHub is public, you do not need to authenticate to clone it to your machine, or to read the issues and pull requests. Think of a public repository like a public library. Anyone can walk in off the street, pull a book off the shelf, and read it. You do not need a library card just to browse.

-

Jamie: But if I want to write a chapter in that book, or bring a new book to the library, that changes things.

-

Alex: Precisely. When you want to push commits to a repository, clone a private repository, or access an organization's internal code, GitHub needs to know who you are. You need to prove your identity. You need to show your ID badge to get behind the front desk. That is what authentication is: proving you are who you say you are.

-

Jamie: Okay, so I need an ID badge. When I first started, I thought I could just type in my GitHub username and my GitHub account password in the terminal. But that does not work anymore, does it?

-

Alex: No, it does not. A few years ago, GitHub removed the ability to use your account password for command line operations. It was a security risk. If someone stole your password, they had the master key to your entire account. So today, we have two primary ways to authenticate with GitHub from the command line: HTTPS and SSH.

-

Jamie: HTTPS versus SSH. Let us break those down. Which one should we start with?

-

Alex: Let us start with HTTPS, because it is the method we recommend for our two-day workshop. It is generally easier to set up using a screen reader because you do it entirely through the GitHub web interface, without needing to configure complex terminal files. When you use HTTPS, you authenticate using something called a Personal Access Token, or a PAT.

-

Jamie: A Personal Access Token. I love analogies, so tell me if this works. If my GitHub password is the master key to my entire house, a Personal Access Token is like a valet key for my car. I can give it to the valet, and it lets them drive the car to park it, but it will not unlock the glovebox or the trunk. And if the valet loses it, I can just deactivate that specific key without changing the locks on my whole house.

-

Alex: That is a brilliant analogy, Jamie. That is exactly what a Personal Access Token is. It is a password-like string of characters that you generate on GitHub. When Git asks for your password in the terminal, you paste this token instead. And just like the valet key, you can give it specific permissions, which we call scopes, and you can set it to expire automatically.

-

Jamie: So how do we create one of these tokens? What is the workflow like for a screen reader user?

-

Alex: First, you will log into GitHub, open your account menu, and navigate to the Settings page. From there, you move to the section called Developer Settings, and you will find Personal Access Tokens. Now, when you get there, you are going to see two options: Fine-grained tokens, and Tokens classic.

-

Jamie: Oh right, the classic versus fine-grained dilemma. What is the difference?

-

Alex: A classic token is like a hotel keycard that opens your room, the gym, and the pool, regardless of what time it is. It applies to all the repositories you have access to. A fine-grained token is much stricter. It is a keycard that only opens your specific room, and maybe only between two and four in the afternoon. You can restrict fine-grained tokens to single repositories.

-

Jamie: Fine-grained sounds more secure, but classic sounds easier to deal with when you are just starting out.

-

Alex: Exactly. For the workshop, we recommend generating a classic token. It is much faster to set up. So, you select Generate new token classic. First, it asks for a note. Give it a descriptive name, like Workshop Laptop Token. Then, you set an expiration. I highly recommend setting it to thirty or sixty days. Never set a token to no expiration.

-

Jamie: Because if you forget about it and it gets leaked months from now, someone has access to your account. Thirty days is perfect for a workshop. And then we set the scopes, right? The permissions.

-

Alex: Yes. The scopes are presented as a list of checkboxes. For our workshop, you only need to check two boxes. First, check the box labeled repo. This gives the token full control of private and public repositories, which means you can push your code. Second, check the box labeled workflow. You only need this if you are going to be updating GitHub Actions workflows, but we do touch on that, so it is good to have.

-

Jamie: Okay, so I check repo, I check workflow, and I activate the Generate token button. What happens next? This is the part that always catches people off guard.

-

Alex: This is critical. When the page reloads, GitHub displays your new token. It is a long string of random letters and numbers. This is the one and only time GitHub will ever show you this token. If you navigate away from this page, you cannot get it back.

-

Jamie: You have to copy it right then and there. For our screen reader users, how is this token presented on the page?

-

Alex: It appears in a standard read-only text field. You can navigate to it, press Control plus A to select all the text in the field, and press Control plus C to copy it.

-

Jamie: And then where do I put it? I know I should not just leave it on my clipboard.

-

Alex: You need to store it securely. The absolute best option is a password manager, like 1Password, Bitwarden, or your operating system's built-in keychain. Create a new secure note or password entry and paste the token there.

-

Jamie: What should we absolutely avoid doing with this token?

-

Alex: Do not paste it into a plain text document that syncs to your cloud storage. Do not email it to yourself. And please, do not save it in a file inside your Git repository, because you might accidentally commit it and push it to GitHub for the world to see. Treat it exactly like your bank password.

-

Jamie: Okay, token is generated and safely stored in my password manager. Now, how do I actually use it?

-

Alex: The next time you try to push a commit to GitHub, the terminal will pause and prompt you. It will ask for your Username. You type your GitHub username and press Enter. Then it asks for your Password. This is where you paste your Personal Access Token.

-

Jamie: And when you paste it in the terminal, it might not read the characters out loud, or even show asterisks on the screen, right? That is a standard terminal security feature.

-

Alex: Correct. The terminal hides your input so someone looking over your shoulder cannot see the length of your token. Just paste it, press Enter, and if everything is correct, your push will succeed.

-

Jamie: But wait. Do I have to go into my password manager, copy that huge string of text, and paste it into the terminal every single time I want to push a commit? That sounds exhausting.

-

Alex: It would be! But thankfully, you do not have to. This is where credential helpers come in. A credential helper is a piece of software that securely remembers your token for you. Think of it like the bouncer at the club remembering your face. You showed your ID once, and now they just wave you through when you come back.

-

Jamie: Oh, thank goodness. How do we get one of those bouncers?

-

Alex: If you are on Windows and you installed Git for Windows, it comes with something called Git Credential Manager. It is a fantastic, cross-platform credential helper. The first time you push, it will actually pop up a secure window asking you to authenticate, and once you provide your token, it saves it securely in the Windows Credential Manager. You never have to type it again until the token expires. On macOS, it integrates similarly with the macOS Keychain.

-

Jamie: Alright, so that is HTTPS and Personal Access Tokens. Generate the token, save it in a password manager, paste it once, and let Git Credential Manager handle the rest. But you mentioned there is a second method. SSH keys. What are those, and why would someone choose SSH over a Personal Access Token?

-

Alex: SSH stands for Secure Shell. It is a protocol for securely communicating between two computers. While a Personal Access Token is like a password you type in, SSH uses something called public-key cryptography. It relies on a pair of keys: a private key and a public key.

-

Jamie: Okay, time for another analogy. How does public-key cryptography work?

-

Alex: Imagine you buy a very special kind of padlock. This padlock comes with a key, but it works in reverse of a normal lock. You keep the physical key on your keychain. That is your private key. You take the padlock itself, make a hundred copies of it, and hand them out to your friends, or in this case, you give one to GitHub. That padlock is your public key.

-

Jamie: So I give GitHub the open padlock, and I keep the key.

-

Alex: Exactly. When you want to talk to GitHub, GitHub snaps your padlock onto a box of data and sends it to you. Because you are the only person in the world who has the physical key that opens that specific padlock, only you can open the box. That is how the authentication happens. It proves you are you, because only you hold the private key.

-

Jamie: That sounds incredibly secure. And the best part is, there is no password to type at all, right? The terminal just uses the key file sitting on my hard drive.

-

Alex: Right. Once it is set up, it is completely invisible. You just push, and it works. SSH keys are considered more secure than tokens, and they do not expire unless you tell them to. However, the initial setup requires running several commands in the terminal, which can be a bit more tedious with a screen reader.

-

Jamie: Let us walk through that terminal setup. How do I actually make this lock and key?

-

Alex: First, you open your terminal and use a command called ssh dash keygen. The full command we recommend is ssh dash keygen space dash t space ed25519 space dash capital C space followed by your email address in quotes.

-

Jamie: Let me break that down. Ssh dash keygen is the program. Dash t tells it what type of key to make, and we are using e d two five five one nine. I remember that used to be r s a, but e d two five five one nine is the newer, more secure standard. And then dash capital C is just adding a comment, like our email, so we know whose key it is.

-

Alex: Perfect breakdown. When you press Enter, the terminal will ask where you want to save the key. Just press Enter again to accept the default location, which is a hidden folder in your user directory called dot ssh. Then, it will ask if you want to enter a passphrase.

-

Jamie: A passphrase? I thought the whole point was to avoid passwords.

-

Alex: A passphrase adds an extra layer of security. If someone steals your laptop and extracts your private key file, they still cannot use it without the passphrase. It is highly recommended, but optional. If you do not want one, you can just press Enter twice to leave it blank.

-

Jamie: Okay, so the command finishes, and it tells me it saved my keys. What exactly did it create?

-

Alex: It created two files in that dot ssh folder. One is called id underscore ed25519. That is your private key. Never share that with anyone. Ever. The other file is called id underscore ed25519 dot pub. Dot pub stands for public. That is the padlock you are going to give to GitHub.

-

Jamie: So how do we give it to GitHub?

-

Alex: You need to copy the contents of that dot pub file. On Windows, if you are using PowerShell, you can type Get dash Content space tilde slash dot ssh slash id underscore ed25519 dot pub space pipe space Set dash Clipboard. That reads the file and copies it directly to your clipboard.

-

Jamie: Oh, that is a fantastic trick. On macOS, you would use pbcopy. So you type p b copy space less than sign space tilde slash dot ssh slash id underscore ed25519 dot pub. It does the exact same thing. The contents of the public key are now on my clipboard.

-

Alex: Once it is on your clipboard, you navigate to GitHub in your browser. Go to Settings, then select SSH and GPG keys from the sidebar. Activate the button that says New SSH key. Give it a title, like Workshop Laptop SSH Key. Make sure the Key type is set to Authentication Key, and then paste your clipboard into the Key field. It will look like a long string of gibberish starting with ssh dash ed25519. Finally, activate Add SSH key.

-

Jamie: Okay, the padlock is officially registered at GitHub. How do I know if it actually worked? How do I test the connection?

-

Alex: You go back to your terminal and type ssh space dash capital T space git at github dot com. This tells your computer to attempt an SSH connection to GitHub. The first time you do this, your computer might say it does not recognize GitHub's fingerprint and ask if you want to continue connecting. You type yes and press Enter.

-

Jamie: And what is the success message we are listening for?

-

Alex: Your screen reader should read out: Hi followed by your username! You have successfully authenticated, but GitHub does not provide shell access. That means the handshake worked perfectly. You are authenticated.

-

Jamie: That is a great feeling when you hear that message. Now, if I originally cloned my repository using HTTPS, but I just set up SSH, do I need to delete the repository and clone it again?

-

Alex: No, you do not need to start over. You just need to change the remote URL. Remember from our earlier episodes, the remote is just the address book entry for GitHub. You can change it by typing git space remote space set dash url space origin space followed by the new SSH URL. The SSH URL always looks like git at github dot com colon your dash username slash the dash repository dot git.

-

Jamie: Okay, so we have covered authenticating to prove who we are so we can push code. But there is another layer to this that is becoming really important in open source. Commit signing. I have noticed on GitHub, when I review pull requests, some commits have a little green badge next to them that says Verified, and others say Unverified. What is that about?

-

Alex: That is a great observation. This is where people often get confused. Authenticating proves you have the right to push code to a repository. Commit signing proves that a specific commit was actually authored by you, and has not been altered by anyone else.

-

Jamie: Why do we need to prove that? If I pushed it, didn't I author it?

-

Alex: Not necessarily. Remember that in Git, you configure your name and email using git config. I could configure my local Git to say my email is jamie at example dot com. I could write a terrible piece of code, commit it, and if I have push access to a repository, I could push it. The history would say Jamie wrote it, even though Alex actually wrote it. Git does not verify email addresses by default.

-

Jamie: Oh, wow. That is a huge loophole. So someone could spoof my identity in the commit history.

-

Alex: Exactly. Commit signing fixes that. When you sign a commit, you are applying a cryptographic signature to it. It is like a notary public stamping a legal document, or putting a wax seal on an envelope. GitHub checks that signature, verifies it against the keys you have uploaded to your account, and if it matches, it slaps that Verified badge on the commit. Many open source projects now require signed commits to prevent identity spoofing.

-

Jamie: So how do I get that Verified badge? How do I sign my commits?

-

Alex: There are two main methods: GPG signing and SSH signing. GPG stands for GNU Privacy Guard. It is the traditional method. You generate a completely separate set of GPG keys, export them, upload them to GitHub, and configure Git to use them. It is highly secure, but it involves a lot of complex terminal commands and key management.

-

Jamie: I remember trying to set up GPG years ago and getting so lost in the terminal output. You said there are two methods. What is the other one?

-

Alex: The newer, much simpler method is SSH signing. If you already set up an SSH key for authentication, like we just discussed, you can reuse that exact same key to sign your commits.

-

Jamie: Wait, really? I can use the same key for both? That is amazing. How do I turn that on?

-

Alex: It takes three simple terminal commands. First, you tell Git to use SSH for signing by typing git space config space dash dash global space gpg dot format space ssh. Second, you tell Git which key to use. You type git space config space dash dash global space user dot signingkey space followed by the path to your public key, like tilde slash dot ssh slash id underscore ed25519 dot pub.

-

Jamie: And the third command?

-

Alex: You tell Git to automatically sign everything. Type git space config space dash dash global space commit dot gpgsign space true.

-

Jamie: That is it on the terminal side? What about on GitHub?

-

Alex: You just need to upload that same public key to GitHub one more time, but this time, when you add the new SSH key in settings, you change the Key type dropdown from Authentication Key to Signing Key. Once you do that, every commit you make will be signed, and GitHub will display the Verified badge.

-

Jamie: For our screen reader users, how do we check if a commit has that Verified badge on GitHub?

-

Alex: When you navigate to a repository's commit history, each commit is presented in a list or table row. If you are using NVDA or JAWS, you can use your down arrow to read through the commit row, and it will read the badge text, Verified or Unverified, inline with the commit details. With VoiceOver, you use VO plus Right Arrow through the row, and the badge is read as a button with the text Verified. You can even activate that button to see the signature details.

-

Jamie: That is incredibly helpful to know. And there is a setting on GitHub called Vigilant Mode, right? What does that do?

-

Alex: Vigilant Mode is an optional setting in your GitHub account. If you enable it, GitHub will actively mark any unsigned commit associated with your account with a yellow Unverified badge. It is a way of telling the world, Hey, I sign all my work. If you see a commit with my name on it that does not have a Verified badge, it is a fake. Do not trust it.

-

Jamie: This has been so enlightening, Alex. Before we wrap up, let us do a quick troubleshooting round. What happens when things go wrong? Let us say I try to push, and the terminal says Authentication failed. What is the most likely culprit?

-

Alex: If you are using HTTPS, an Authentication failed error almost always means your Personal Access Token has expired. Tokens have a shelf life. When they expire, they stop working silently. The solution is to go back to GitHub, generate a new token, clear your credential manager cache, and try pushing again. Git will prompt you for the new token.

-

Jamie: What if I am using SSH, and the terminal says Permission denied publickey?

-

Alex: That means GitHub received an SSH connection, but it did not recognize the key. First, verify that you actually added the public key to your GitHub settings. Second, make sure your local SSH agent is running and has your key loaded. You can check this by typing ssh dash add space dash l.

-

Jamie: And what if it says Host key verification failed? That sounds scary.

-

Alex: It sounds scary, but it usually just means your computer has never connected to GitHub before, and it wants you to explicitly trust GitHub's server. You can fix it by typing ssh dash keyscan space github dot com space two greater than signs space tilde slash dot ssh slash known underscore hosts. That command grabs GitHub's public fingerprint and adds it to your trusted list.

-

Jamie: Okay, that makes it feel much more manageable. Authentication errors look intimidating, but they usually just boil down to an expired token or a missing key.

-

Alex: Exactly. Do not let the terminal errors panic you. Take a breath, read the error, and remember the core concepts.

-

Jamie: Let us summarize our key takeaways for this episode. First, you need authentication to push code to GitHub. Reading public code is free, but writing requires proving who you are. Second, for this workshop, we recommend using HTTPS with a Personal Access Token. It is easier to set up with a screen reader.

-

Alex: Third, treat your Personal Access Token or your SSH private key like your bank password. Never share them, and store them in a secure password manager. And fourth, if you want that coveted Verified badge on your commits, set up SSH commit signing. It takes five minutes and adds a tremendous layer of trust to your open source contributions.

-

Jamie: I love that. We are all about building trust in open source. So, we are authenticated, our commits are verified, and we are ready to actually start moving code around. What is up next?

-

Alex: In Episode twenty-two, we are diving into Forking and Cloning. We will explain how to make your own personal copy of an open source project, bring it down to your local machine, and get it ready for your first real contribution. You will not want to miss it.

-

Jamie: I cannot wait. Thanks for listening, everyone, and we will catch you in the next episode!

-
- - -

Episode 22: GitHub Flavored Markdown

-

Markdown syntax, GitHub extensions, and writing accessible documentation.

-

Based on: Appendix E: GitHub Flavored Markdown

- - -

Download Episode 22 (MP3)

-
-Read Transcript - Episode 22: GitHub Flavored Markdown - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode 22, GitHub Flavored Markdown.

-

Jamie: We are officially halfway through our two-day workshop material! If you have been following along, you already know how to clone repositories, navigate branches, and make commits. But today, we are talking about how we actually write the text that goes into our documentation, our pull requests, and our issues.

-

Alex: Exactly. Before we dive in, the only prerequisite for this episode is being comfortable opening a file in your editor. If you are using VS Code, that means knowing how to use the command palette with Control plus Shift plus P, or Command plus Shift plus P on a Mac, to navigate to your files.

-

Jamie: So Alex, when I first started learning GitHub about two years ago, I kept hearing the word Markdown. People would say, just write it in Markdown, or check the Markdown file. And I realized that almost every project has a file called read me dot M D. The M D stands for Markdown. But what actually is it?

-

Alex: At its core, Markdown is a lightweight markup language. And to define that, think about how you might write a document in Microsoft Word. In a heavy word processor, the formatting is hidden. You press a button to make text bold, and the software handles the underlying code. A lightweight markup language flips that. You write in plain text, using standard punctuation marks to indicate formatting, and then a program translates those symbols into a beautifully formatted document.

-

Jamie: I love the analogy of writing a plain text email, but you are sprinkling in secret codes that a machine later translates. It is just text. You do not need any special software to read or write it. A screen reader reads it perfectly because it is just letters and punctuation.

-

Alex: Exactly. And today we are specifically talking about GitHub Flavored Markdown, often abbreviated as G F M. Standard Markdown has been around for decades, but GitHub added their own special extensions to make it perfect for software development. Things like task lists, alert callouts, and code blocks.

-

Jamie: Let us start with the absolute basics. How do we give our document structure?

-

Alex: Structure comes from headings. In Markdown, you create a heading by typing a number sign, also known as a hash symbol, followed by a space, and then your text. One hash mark creates a heading level one, or H 1. Two hash marks create a heading level two, or H 2. And this goes all the way down to six hash marks for an H 6.

-

Jamie: This is so important for screen reader users. Think of headings like a nested folder structure on your computer, or an outline for a term paper. When I navigate a long read me file, the very first thing I do is press the letter H in my screen reader to jump from heading to heading.

-

Alex: Which brings up a critical rule for writing accessible Markdown. You must respect the heading hierarchy. Never skip heading levels just because you want the text to render at a certain size. Do not jump from a heading level two straight to a heading level four. If you do, a screen reader user navigating by heading will think they missed an entire section of your document.

-

Jamie: I definitely made that mistake when I started. I thought, oh, heading level three is too big, let me use heading level five. But headings are for structure, not style.

-

Alex: Exactly. Now, what about the regular text under those headings? Paragraphs in Markdown are incredibly simple. You just type your text. When you want a new paragraph, you press the Enter key twice to leave a blank line. If you do not leave a blank line, Markdown will just combine the text into the same paragraph.

-

Jamie: And if I want to emphasize a word? Say I am writing instructions and I really want to stress the word "not".

-

Alex: You have two main types of emphasis: italic and bold. Think of these like vocal inflection. Italic is like leaning in to emphasize a point, while bold is like shouting to ensure it is heard. To make a word italic, you wrap it in single asterisks. Asterisk, the word, asterisk. To make it bold, you use double asterisks. Asterisk, asterisk, the word, asterisk, asterisk.

-

Jamie: Screen readers handle this quite well, depending on your verbosity settings. Some will change their pitch slightly when reading emphasized text.

-

Alex: Let us move on to something that connects our documents together: links. Markdown gives us a few ways to create hyperlinks.

-

Jamie: The standard way is called an inline link. The syntax always tripped me up at first because it uses two different types of brackets.

-

Alex: It takes practice! For an inline link, you wrap the clickable text in square brackets, immediately followed by the U R L in parentheses. No spaces between the closing square bracket and the opening parenthesis.

-

Jamie: So left bracket, the words GitHub Home, right bracket, left parenthesis, H T T P S colon slash slash github dot com, right parenthesis.

-

Alex: Perfect. Think of an inline link like a direct flight. The destination is written right there next to the text. But sometimes, if you have a lot of links in a paragraph, reading the raw Markdown gets very noisy. That is where reference links come in.

-

Jamie: Reference links are brilliant. They are exactly like endnotes in a printed book. Instead of putting the U R L right there in the sentence, you put a number or a label in square brackets. So you write, left bracket, GitHub Home, right bracket, left bracket, the number one, right bracket. Then, anywhere else in the document, usually at the very bottom, you define what number one means.

-

Alex: You define it by typing left bracket, the number one, right bracket, a colon, a space, and then the U R L. When GitHub renders the document, it turns the text into a standard link. This makes the raw plain text much cleaner to read with a screen reader.

-

Jamie: And what about autolinks?

-

Alex: Autolinks are the easiest. If you just paste a full U R L that starts with H T T P or H T T P S, GitHub automatically turns it into a clickable link. It is like the internet recognizing a U R L automatically. But be careful here. For accessibility, pasting raw U R Ls is usually a bad idea.

-

Jamie: Right, because a screen reader will read out every single character of a messy U R L. It is always better to use an inline or reference link to provide descriptive link text. Instead of a link that says "click here" or a raw U R L, your link text should say "Review the setup instructions."

-

Alex: Let us talk about images, because the syntax is almost identical to links, but with one crucial addition.

-

Jamie: The exclamation mark! Or as programmers like to call it, the bang.

-

Alex: Yes. To embed an image, you start with an exclamation mark, then square brackets containing the alt text, then parentheses containing the U R L or file path of the image.

-

Jamie: So, exclamation mark, left bracket, Alt Text goes here, right bracket, left parenthesis, image dot P N G, right parenthesis.

-

Alex: This is where we need to talk about writing descriptive alt text. Alt text is alternative text. If an image cannot load, or if a person is using a screen reader, the alt text is what gets read aloud.

-

Jamie: Think of alt text like an audio description track for a movie. You need to convey the meaning and context of the image, not just a literal description of every pixel. And please, do not start your alt text with the words "Image of" or "Picture of". The screen reader already announces that it is an image.

-

Alex: Exactly. If the image is a screenshot of a command line showing an error message, your alt text should actually include the text of the error message. If the image is a chart showing performance going up, say "Line chart showing a twenty percent increase in performance over three months."

-

Jamie: Okay, so we have headings, paragraphs, links, and images. What about lists? I feel like half of my time on GitHub is spent writing lists.

-

Alex: Lists are incredibly common. You have unordered lists, which are just bullet points, and ordered lists, which are numbered.

-

Jamie: An unordered list is like a grocery list. The order does not strictly matter. To make one, you just start a line with a dash or an asterisk, followed by a space, and then your item.

-

Alex: And an ordered list is like a recipe. The steps must happen in sequence. For these, you start the line with a number, a period, a space, and your text. Like, one dot space preheat the oven.

-

Jamie: One thing I love about Markdown is that for ordered lists, you can actually just use the number one for every single item. One dot space do this. On the next line, one dot space do that. When GitHub renders it, it automatically numbers them one, two, three. That way, if you insert a new step in the middle, you do not have to renumber everything manually.

-

Alex: That is a great tip. And you can nest lists, too. If you are on an item and you want to create a sub-list, you just move to the next line and indent the dash or the number by two spaces. The screen reader will announce the change in list level, telling you that you have entered a nested list.

-

Jamie: Speaking of lists, can we talk about task lists? Because this is a specific GitHub Flavor feature that changed my life.

-

Alex: Task lists are fantastic. They create interactive checkboxes right inside your pull requests and issues.

-

Jamie: Think of a task list like a digital clipboard hanging on a wall. Anyone with permission can walk up and check a box without having to rewrite the whole list.

-

Alex: To create a task list item, you write a regular list item using a dash, then a space, then open and close square brackets with a space between them, then another space, and your text.

-

Jamie: So it is dash, space, left bracket, space, right bracket, space, "Write tests." That creates an unchecked box.

-

Alex: If you want the box to be checked by default, you replace the space inside the brackets with a lowercase letter X. Dash, space, left bracket, X, right bracket, space.

-

Jamie: When you view this in a GitHub issue, it renders as a real HTML checkbox. If you are navigating with N V D A or JAWS, it will read as "checkbox, not checked" or "checkbox, checked". And here is the best part: if you have write access to the repository, you do not have to edit the Markdown file to check the box. You can just navigate to the checkbox in the rendered view, switch to focus mode, and press the Spacebar. It updates the Markdown for you automatically.

-

Alex: And in a pull request, GitHub actually reads those checkboxes to create a progress bar. It will tell reviewers, "two of seven tasks completed." It is a brilliant way to manage a release checklist.

-

Jamie: Let us pivot to writing code in our Markdown. We are developers, after all. We need to document our code.

-

Alex: You have two ways to format code: inline code and code blocks. Inline code is for when you want to format a single word, like a variable name or a keystroke, right in the middle of a sentence.

-

Jamie: To do this, you wrap the word in single backticks. The backtick key is usually located in the top left of your keyboard, right under the Escape key. Think of inline code like quoting a single phrase from a foreign language in the middle of your English sentence. It tells the reader, "this specific word is code."

-

Alex: For larger chunks of code, you use a code block. This is like setting up a dedicated translation booth. You start by putting three backticks on their own line. Then you paste all your code on the following lines. Finally, you close the block by putting three more backticks on their own line at the end.

-

Jamie: And you can enable syntax highlighting by typing the name of the programming language immediately after the first three backticks. So three backticks, the word python, and then press Enter.

-

Alex: Syntax highlighting is mostly a visual feature. It changes the font colors based on whether a word is a variable, a string, or a function. For screen reader users, the code block is announced as a "code region", but the text itself is read normally. This is why writing clean, well-named variables is the true key to accessible code. The syntax highlighting does not convey any structural information to the screen reader that the raw text does not already provide.

-

Jamie: Okay, what if I need to organize data? Can I build a table in Markdown?

-

Alex: You can, using pipes and dashes. The pipe character is usually typed by pressing Shift and the Backslash key.

-

Jamie: I always describe Markdown tables as drawing a spreadsheet with sticks. The vertical pipes act as the walls between the columns, and a row of dashes acts as the floor separating the header row from the data rows.

-

Alex: Exactly. You start a row with a pipe, type your column header, type another pipe, type the next header, and so on. On the second line, you use pipes to separate dashes. This tells Markdown that the first row was a header. Then you fill in your data on the following lines, separated by pipes.

-

Jamie: When GitHub renders this, it builds a proper HTML table. Screen readers like VoiceOver or JAWS will announce it as a table, tell you the number of columns and rows, and let you navigate cell by cell using your standard table commands, reading the column headers as you move.

-

Alex: Now let us get into some of the newer, advanced GitHub extensions. Starting with Alert blocks, which were introduced in 2023.

-

Jamie: I love these. Sometimes you write documentation and there is a critical warning, like "Do not delete this database," but it just gets lost in the paragraphs. Alerts let you pull that text out into a dedicated callout box.

-

Alex: Think of an alert block like an intercom announcement interrupting the regular broadcast. To create one, you use the standard Markdown syntax for a blockquote, which is the greater-than sign followed by a space. But then, you add a special tag in square brackets, starting with an exclamation mark.

-

Jamie: So to make a Note alert, you type greater-than sign, space, left bracket, exclamation mark, the word NOTE in all capital letters, right bracket.

-

Alex: GitHub supports five types of alerts: Note, Tip, Important, Warning, and Caution. You put that tag on the first line, and then on the next line, you type another greater-than sign and write your message.

-

Jamie: From an accessibility perspective, these are handled really well. GitHub renders them as a blockquote, but it adds a strong heading with the alert type. So your screen reader will announce "blockquote," and then read the word "Warning," before reading your message. You get the full semantic meaning without needing to rely on visual styling.

-

Alex: Another advanced feature you will encounter is Mermaid diagrams. Have you worked with these, Jamie?

-

Jamie: I have, and they are a double-edged sword. Mermaid is a tool that lets you generate flowcharts and graphs using plain text. You create a code block, use the word "mermaid" as the language tag, and then write out relationships. Like, A dash dash greater-than B.

-

Alex: It is like a text-based blueprint that automatically draws a house. It is incredibly popular in architecture documentation because developers can version control their diagrams just like code.

-

Jamie: But here is the massive accessibility catch. When GitHub renders a Mermaid diagram, it turns it into an S V G image. And GitHub does not automatically generate alt text for that image. To a screen reader, it is often just a locked door. It might announce a generic container, or it might skip it entirely.

-

Alex: This is a critical point. If you use Mermaid diagrams, you must take responsibility for the accessibility. The rule is simple: always provide a plain text equivalent before or after the diagram.

-

Jamie: Right. If your flowchart shows a five-step pull request workflow, just write out those five steps as an ordered list right before the diagram. The diagram is great for visual learners, but the text list ensures no one is blocked from the information.

-

Alex: While we are talking about specialized code, GitHub also supports LaTeX for math equations.

-

Jamie: LaTeX is like musical notation, but for numbers and complex algorithms. If you are writing documentation for data science or machine learning, you need a way to show formulas.

-

Alex: You use the dollar sign. A single dollar sign on each side of your equation renders it inline, right in the middle of a sentence. Two dollar signs on their own lines create a display block, centering the math and making it larger.

-

Jamie: GitHub uses a tool called MathJax to render this. The good news is that MathJax includes an aria-label with the spoken form of the equation. So if you write E equals M C squared in LaTeX, most screen readers will actually read out "E equals M C squared". But for incredibly complex equations, it is still best practice to explain the formula in plain English right after it.

-

Alex: Let us wrap up with a few features that help with document navigation. Specifically, footnotes and heading anchors.

-

Jamie: Footnotes are brilliant for keeping your main text clean. They work like a two-way portal. You drop a marker in your text, and it creates a link that jumps down to the reference.

-

Alex: To create a footnote reference, you use square brackets, a caret symbol, which is Shift plus the number six, and an identifier. So left bracket, caret, the number one, right bracket.

-

Jamie: Then at the bottom of your document, you type that same marker, a colon, and your footnote text. When GitHub renders it, the marker becomes a clickable superscript number. And down at the footnote, it automatically adds a back-link, which the screen reader reads as "return to footnote reference". It is so seamless.

-

Alex: And finally, heading anchors. Every single heading you create in a GitHub Markdown file automatically gets an anchor I D. This means you can link to any specific section of a document.

-

Jamie: Think of an anchor like dropping a pin on a specific paragraph. If I have a heading that says "Getting Started", GitHub takes that text, converts it to all lowercase, and replaces the spaces with hyphens. So the anchor becomes "getting-dash-started".

-

Alex: You can then create a link anywhere else in the document that points exactly to that heading by using a hash symbol followed by the anchor name. Left bracket, Go to setup, right bracket, left parenthesis, hash getting-dash-started, right parenthesis.

-

Jamie: This is exactly how people build Tables of Contents at the top of really long read me files.

-

Alex: One last quick tip before we summarize. Markdown allows you to use basic H T M L inside your files. The most useful one is the details element.

-

Jamie: Oh, the details element is a lifesaver. If you are filing a bug report and you have a massive stack trace that is five hundred lines long, do not just paste it into the issue. It makes navigating with a screen reader exhausting.

-

Alex: Instead, you write the H T M L tag, less-than sign, the word details, greater-than sign. Inside that, you use a summary tag to write a title, like "Click to expand stack trace". Then you paste your massive code block, and close the details tag.

-

Jamie: A screen reader will announce this as a collapsed button. You just press Enter or Space to expand it, and the content appears immediately without reloading the page. It keeps the issue clean while still providing all the data.

-

Alex: We have covered a massive amount of syntax today. Jamie, what are the top takeaways our listeners should focus on?

-

Jamie: First, Markdown is just plain text with punctuation. Headings use hashes, emphasis uses asterisks, and links use brackets and parentheses. Second, always write accessible Markdown. That means respecting your heading hierarchy, writing descriptive link text instead of pasting raw U R Ls, and always, always providing alt text for your images. And third, when using advanced features like Mermaid diagrams, remember that they render visually. You must include a text equivalent so screen reader users get the same information.

-

Alex: Perfect summary. Take some time to practice these in VS Code. Create a file called practice dot M D and try building a table, adding a task list, and linking to an anchor.

-

Jamie: In our next episode, we are moving away from writing text and getting back to the repository. We will be covering the Pull Request workflow, specifically how to review code and handle merge conflicts.

-

Alex: It is going to be a great one. Until then, keep practicing, and happy coding.

-
- - -

Episode 23: GitHub Gists

-

Lightweight code sharing: creating, editing, forking, and embedding Gists.

-

Based on: Appendix F: GitHub Gists

- - -

Download Episode 23 (MP3)

-
-Read Transcript - Episode 23: GitHub Gists - -

Transcript

-

Alex: Welcome back to Gitt Going with GitHub. I am Alex, and this is episode twenty three of our audio series. Today, we are talking about a feature called GitHub Gists. That is spelled G I S T S. We will cover what they are, how to create them using both the web interface and the command line, the difference between public and secret Gists, and how to embed them.

-

Jamie: Hi everyone, I am Jamie. And I have to say, I see links to Gists all the time when I am searching for coding answers on the web, but for the longest time, I did not really understand what made them different from a regular GitHub repository. Two years ago when I was first starting out, I thought a Gist was just a funny name for a text file.

-

Alex: You were not entirely wrong, Jamie. A Gist at its core is a lightweight way to share code snippets, notes, or small files without going through the trouble of creating a full repository. Think of it as a version controlled digital sticky note.

-

Jamie: A version controlled sticky note. I like that. So a snippet, just to define that for everyone, is exactly what it sounds like. A small piece of code. Maybe it is ten lines of Python, or a quick configuration file, rather than a whole software program.

-

Alex: Exactly. When you are building a full project, you want a standard GitHub repository. A repository is like a heavy duty filing cabinet. It has folders, multiple branches, an issue tracker for bugs, pull requests for code review, and automated testing. It is built for collaboration. But sometimes, you just do not need all of that heavy machinery.

-

Jamie: Right, because creating a whole repository just to share a five line script feels like renting a moving van to transport a single piece of mail. It is way too much overhead.

-

Alex: That is a perfect analogy. You use a Gist when you want to share a single code snippet, post a configuration example, share error logs with a colleague, or just save some quick documentation for yourself. Gists do not have issues, they do not have pull requests, and they do not have project boards. They are streamlined specifically for sharing small bits of information quickly.

-

Jamie: So how do we actually create one? Do I start from my normal GitHub dashboard?

-

Alex: You can, but Gists actually live on their own subdomain. To get started, you will open your browser and navigate to gist dot github dot com.

-

Jamie: Got it. Gist dot github dot com. What does that page look like with a screen reader?

-

Alex: It is a very clean interface. When the page loads, you can press the letter D to cycle through your landmarks until you hear Main landmark. From there, you can press the letter F to navigate through the form fields. The first thing you will land on is the Gist description text box.

-

Jamie: What should I put in the description? Is this like a commit message?

-

Alex: It is more like the title of your sticky note. You want to be brief but descriptive. For example, you might type, NVDA configuration for GitHub web navigation.

-

Jamie: Okay, so I type my description, and then I press Tab to move to the next field?

-

Alex: Yes. The next field is the Filename text box. And this part is actually really important. You do not just want to type a name, you need to include the file extension. So instead of just typing nvda config, you should type nvda config dot txt. Or if it is a Python script, script dot py.

-

Jamie: Why is the extension so important?

-

Alex: Because GitHub uses that extension to determine how to format the text. If you type dot py, GitHub automatically applies Python syntax highlighting. If you type dot md, it knows to treat it as a Markdown file. It makes reading the code much easier for anyone who comes across it.

-

Jamie: Oh, that is incredibly smart. I wish I had known that when I started. I used to just leave the filename blank and wonder why my code looked like a giant wall of plain text.

-

Alex: It is a very common mistake! So, after you enter your filename, you press Tab again to move into the main content text box. This is where you actually paste or type your code.

-

Jamie: And if I am sharing an error log from my terminal, I just copy it from my terminal window and paste it right into that text box.

-

Alex: Exactly. Once your content is in there, you have a choice to make about visibility. If you Tab past the content area, you will reach the visibility options. You can choose either Create secret gist or Create public gist.

-

Jamie: Let us talk about those visibility options, because I remember being very confused by the word secret. Secret means private, right? Only I can see it?

-

Alex: That is a massive misconception, and I am so glad you asked. No. Secret does not mean private.

-

Jamie: Okay, warning bells are going off in my head. Please explain.

-

Alex: A public Gist is completely open. It appears on your public GitHub profile, it shows up in GitHub search results, and it gets indexed by search engines like Google. Anyone can find it, view it, and leave comments on it.

-

Jamie: Like a public post on a message board.

-

Alex: Exactly. A secret Gist, on the other hand, is hidden from search engines. It does not appear on your GitHub profile, and it will not show up if someone searches GitHub for keywords. However, anyone who has the exact URL can view it.

-

Jamie: So it is like having an unlisted phone number. Or an unlisted video on YouTube. You will not find it in the phone book, but if I hand you a slip of paper with the number on it, you can call it. It is not locked behind a password.

-

Alex: That is the perfect way to understand it. Because it is not locked behind a password or tied to user permissions, you must never put sensitive data in a Gist. Not even a secret one.

-

Jamie: So no passwords, no API keys, no personal user data.

-

Alex: Never. If you need to share proprietary code or secure credentials, you should use a private GitHub repository with strict access controls, or a dedicated secure password manager. If you accidentally paste an API key into a Gist, you need to delete that Gist immediately and go revoke that key with whatever service issued it.

-

Jamie: That is really good to know. So if secret Gists are not truly secure, what is the point of them? When would I use one?

-

Alex: They are great for sharing things you just do not want cluttering up your public profile. If you and I are troubleshooting a bug, and I want to send you a massive, messy error log, I will make it a secret Gist. I send you the link in our chat, you read it, we fix the bug. The log does not need to be searchable by the whole internet, but I also do not need military grade security for it.

-

Jamie: Okay, so let us go back to our form. I have my description, my filename, my code, and I choose Create public gist. I activate that button, and then what happens?

-

Alex: GitHub saves the Gist and loads a new page. This page has a unique URL in your browser address bar. It will look something like gist dot github dot com slash your username slash a long string of random letters and numbers. That URL is what you share with people.

-

Jamie: What if I need to share two files? Let us say I have a script, but I also have a small configuration file that goes with it. Do I have to make two separate Gists?

-

Alex: You do not. You can absolutely add multiple files to a single Gist. When you are on the creation page, right after the main content text box, there is a button called Add file. If you activate that button, it generates a new filename field and a new content text box right below your first one.

-

Jamie: Oh, that is clever! So I could share my HTML file, my CSS file, and my JavaScript file all in one single link.

-

Alex: Exactly. It keeps related snippets bundled together perfectly.

-

Jamie: Now, Alex, you know I am a huge fan of the command line. Doing all of this in the browser sounds fine, but switching windows, navigating form fields, pasting things in. Is there a way to create a Gist directly from my terminal?

-

Alex: There is, and it is incredibly fast. If you have the GitHub CLI installed, which is the command line interface we talked about in a previous episode, you can use the command g h space gist space create.

-

Jamie: G h gist create. How does that work in practice?

-

Alex: Let us say you have a file on your computer called notes dot txt. In your terminal, you just type g h space gist space create space notes dot txt. You press Enter, and the CLI uploads the file to GitHub and prints the brand new Gist URL right there in your terminal.

-

Jamie: That is amazing. I do not even have to open my browser. Does it make it public or secret by default?

-

Alex: By default, the CLI creates a secret Gist. If you want to make it public, you just add a flag to your command. You would type g h space gist space create space notes dot txt space dash dash public.

-

Jamie: I love that. That saves so many steps.

-

Alex: So, earlier we called a Gist a version controlled sticky note. Let us talk about what that actually means under the hood.

-

Jamie: Right, because what happens if I create my Gist, share the link, and then realize I made a typo in my code? Can I fix it?

-

Alex: You can. When you navigate to the page for your Gist, there is an Edit button near the top of the main content area. If you activate that, it opens the form fields back up. You can fix your typo, and then activate the Update button.

-

Jamie: Does it change the URL when I update it?

-

Alex: No, the URL stays exactly the same, which is great because any links you have already shared will still work. But here is the really cool part. Every single Gist is actually a tiny, fully functional Git repository behind the scenes.

-

Jamie: Wait, really? I thought we just said it was not a repository.

-

Alex: It is not a full GitHub project repository with issues and actions. But the underlying technology storing your file is Git. That means every time you edit your Gist, Git records a commit. If you navigate to your Gist page, you will find a link called Revisions. If you open that, you can read the entire history of changes made to that file, just like a commit history.

-

Jamie: That blows my mind a little bit. If it is a real Git repository, does that mean I can clone it to my computer?

-

Alex: Yes, you can! Every Gist page has a clone URL. You can open your terminal, type git clone, and paste that URL. It will download the Gist to your local machine as a folder. You can open it in your code editor, make changes, type git commit, and type git push to send the changes back to GitHub.

-

Jamie: That is wild. I had no idea they were that powerful. So if it is a Git repo, can I fork someone else's Gist? Like, if I find a really cool script that someone else wrote, but I want to customize it for my own workflow?

-

Alex: Absolutely. Forking is a fundamental concept in open source. To fork means to create a personal copy of someone else's project under your own account. If you are reading a Gist that belongs to another developer, you can navigate to the Fork button and activate it. GitHub instantly creates a duplicate of that Gist in your account.

-

Jamie: So it is like taking a recipe card from a friend's kitchen, copying it onto a blank card, and putting it in my own recipe box. Now I can cross out ingredients and add my own notes without messing up their original recipe.

-

Alex: That is a wonderful analogy. And because it is connected through Git, your forked copy will always link back to the original author, so they get credit for the initial work.

-

Jamie: What if I do not want to copy it, I just want to bookmark it so I can find it later?

-

Alex: For that, you use the Star feature. Starring a Gist is exactly like bookmarking it. There is a Star button right next to the Fork button. When you activate it, that Gist is added to your starred list.

-

Jamie: How do I find my list of starred Gists, or even just a list of all the Gists I have created myself?

-

Alex: You navigate to gist dot github dot com slash your username. That is your personal Gist dashboard. It lists all of your public Gists, your secret Gists, and there is a navigation tab to view the ones you have starred.

-

Jamie: What is the screen reader experience like on that dashboard? If I have twenty different Gists, how do I find the one I am looking for?

-

Alex: GitHub structures that page very well. Each Gist in your list is marked up as a level two heading, and the heading text is the description you provided when you created it.

-

Jamie: Oh, perfect. So I can just press the number 2, or the letter H, to jump from heading to heading until I hear the description I want.

-

Alex: Exactly. And right below each heading, you will find links to Edit, Delete, or Star that specific Gist.

-

Jamie: You mentioned deleting. If I delete a Gist, is it gone forever?

-

Alex: Yes. Deletion is permanent. To do it, you navigate to the Gist, activate the Edit button, and then look for the Delete button. GitHub will ask you to confirm, and once you do, it is removed entirely. But keep in mind, if someone else has already forked your Gist, their forked copy will not be deleted. They own their copy.

-

Jamie: Let us talk about comments. You mentioned earlier that people can leave comments on public Gists. How does that work?

-

Alex: It works beautifully for collaboration. Let us say you write a script to automate a task, and you publish it as a Gist. I find it, but I notice a small bug. I can scroll to the bottom of your Gist page, press the letter F to find the comment text box, and type out a message. I can even use Markdown to format code blocks in my comment. Then I press Control plus Enter to submit it.

-

Jamie: And I get a notification that you commented?

-

Alex: Yes, you will be notified. It turns the Gist into a mini discussion forum. It is incredibly common to see popular Gists with long comment threads where developers are suggesting improvements or sharing how they adapted the code for different operating systems.

-

Jamie: Speaking of popular Gists, is there a way to browse what other people are sharing? Like a trending page?

-

Alex: There is. You can navigate to gist dot github dot com slash discover. The Discover page shows you a feed of public Gists that are currently popular. It is a fantastic place to find useful utilities, learn new coding techniques, and see how other developers structure their configuration files. You can even filter the Discover page by programming language.

-

Jamie: Okay, there is one more concept from the checklist we need to cover. Embedding a Gist. What does it mean to embed a Gist, and why would I want to do it?

-

Alex: To embed means to place the content of your Gist directly inside another webpage, like your personal blog or a documentation site.

-

Jamie: Why wouldn't I just copy and paste the code straight into my blog post?

-

Alex: You could, but then your code is static. If you find a bug in your code a week later, you have to go log into your blog, find the post, and edit the text. If you embed a Gist instead, you only ever have to update the code on GitHub. The moment you update the Gist, your blog automatically displays the new, corrected code. Plus, GitHub provides all the beautiful syntax highlighting automatically.

-

Jamie: Oh, that makes so much sense. It is like hanging a picture frame on the wall of your blog. The frame stays in the same place, but you can swap out the painting inside it anytime you want, just by updating GitHub.

-

Alex: Exactly. To do this, you navigate to your Gist page. Near the top, there is a section called Embed. It provides a small snippet of HTML code that looks like a script tag. You just copy that script tag and paste it into the HTML of your blog post.

-

Jamie: How does an embedded Gist behave for someone using a screen reader who is reading my blog?

-

Alex: That is a great accessibility question. Technically, the embed script generates an HTML iframe. So when a screen reader user lands on it, they will hear the word frame, followed by the title of the Gist. They can then navigate into the frame to read the code line by line, just like they would on GitHub. It is a very seamless reading experience.

-

Jamie: This has been incredibly helpful. I feel like I finally understand where Gists fit into the ecosystem. They are not just plain text files, and they are not full repositories. They are the perfect middle ground for sharing.

-

Alex: They really are. So, let us recap our main takeaways for today. First, use a Gist when you want to share a lightweight code snippet, a configuration file, or an error log without the overhead of a full repository.

-

Jamie: Second, secret Gists are not strictly private. They are unlisted. Anyone with the link can view them, so never ever put passwords or API keys in a Gist.

-

Alex: Third, every Gist is a Git repository under the hood. That means you get version history, and you can clone, fork, and edit them just like a normal project.

-

Jamie: And fourth, you can create them incredibly fast straight from your terminal using the command g h space gist space create.

-

Alex: Perfect summary. That wraps up episode twenty three. In our next episode, we are going to dive into GitHub Pages, which allows you to host a static website directly from a repository for free. It is one of the most exciting features for showcasing your work. Until then, keep practicing, and happy coding.

-
- - -

Episode 24: GitHub Discussions

-

Forum-style conversations, Q&A, polls, and navigation with screen readers.

-

Based on: Appendix G: GitHub Discussions

- - -

Download Episode 24 (MP3)

-
-Read Transcript - Episode 24: GitHub Discussions - -

Transcript

-

Alex: Welcome to episode twenty four of Gitt Going with GitHub, the audio learning series designed specifically for blind and low vision developers who are navigating the world of open source collaboration. I am your host, Alex.

-

Jamie: And I am your cohost, Jamie! Today, we are diving into a feature that I honestly wish I understood two years ago when I first started my GitHub journey. We are talking all about GitHub Discussions.

-

Alex: It is a fantastic topic, Jamie, and one that can save new open source contributors a lot of frustration. In this episode, we are going to cover what Discussions are, how they differ from Issues, the different categories of conversations you will find, and how to effectively navigate, create, and participate in these discussions using a screen reader. We will also talk about polls, marking answers, and when a discussion should actually become an issue.

-

Jamie: Before we jump into the deep end, let us do a quick refresher on our prerequisites. To get the most out of today's episode, it helps to be familiar with a few core GitHub concepts we covered earlier in the workshop. First is a repository, which is simply the central storage location or folder where a project's code and files live on the internet.

-

Alex: Correct. You also need to know about issues. An issue is essentially a tracking ticket. It is where you report bugs, which are errors in the code, or request specific new features. Issues are highly structured and action oriented.

-

Jamie: Right. And finally, we have talked about pull requests. So a pull request, and I love that name because you are literally requesting that someone pull your changes into their project, is the actual mechanism you use when you have written new code and you want the maintainers to merge it into the main repository.

-

Alex: Perfectly summarized. So, we have repositories for storage, issues for tracking tasks, and pull requests for merging code. But what happens when you just want to ask a question? What happens when you want to brainstorm an idea, or the project maintainer wants to announce a new version? That is where GitHub Discussions comes in.

-

Jamie: So Alex, let us start with the most basic question. What exactly is a GitHub Discussion?

-

Alex: At its core, GitHub Discussions is a built in community forum for a repository or an organization. It is where open ended conversations live. Think of it as a dedicated space for questions, ideas, announcements, and community support. It is completely separate from the action oriented world of issues and pull requests.

-

Jamie: I remember when I first started using GitHub, I did not even know Discussions existed. I ran into a problem where I could not figure out how to configure a project I had downloaded. So, I navigated to the Issues tab, activated the New Issue button, and asked my question there. About ten minutes later, a bot automatically closed my issue and labeled it as invalid. I felt terrible! I thought I had broken some unspoken rule.

-

Alex: That is such a common experience, Jamie. And you did break an unspoken rule, but it is one that nobody explains to beginners! Not every conversation belongs in an issue. Issues are for actionable work. When you open an issue, it signals to the maintainers that there is a task to be done. It might trigger automated testing workflows, send email alerts to dozens of contributors, and inflate the project's to do list.

-

Jamie: Wow, I had no idea I was setting off alarms just by asking for help.

-

Alex: Exactly. Let us use a real world analogy. Think of a restaurant. Issues are the ticket line in the kitchen. When a ticket comes in, the cooks have to take action. They have to chop vegetables, cook the meal, plate it, and send it out. If you walk into the kitchen and hand the chef a ticket that just says, what is your favorite vegetable, you are going to disrupt the entire workflow.

-

Jamie: That makes so much sense. So where do I ask about their favorite vegetable?

-

Alex: You ask in the dining room! And that is what GitHub Discussions is. It is the dining room of the repository. It is a space designed for people to sit down, chat, ask what is on the menu, and share their experiences without interrupting the cooks in the kitchen.

-

Jamie: I love that analogy. So to break it down, we should use issues when we find a bug, when we want to request a specific feature, or when there is actionable work that needs to be tracked, assigned to someone, and eventually closed.

-

Alex: Exactly right. And on the flip side, we use Discussions when we have a question about how something works, when we want to brainstorm ideas before we file a formal feature request, or when we just want community input on a topic that might not have one single right answer.

-

Jamie: Okay, so if I am in a repository and I want to visit the dining room, how do I find these discussions?

-

Alex: Navigating to Discussions is straightforward, but there is a catch. Discussions is an opt in feature. The repository maintainer has to actively enable it in their settings. So, not every repository you visit will have a Discussions tab.

-

Jamie: Good to know. But assuming they do have it enabled, how do we get there with a screen reader?

-

Alex: When you navigate to a repository page, you will find a main navigation tab list near the top. This tab list contains links for Code, Issues, Pull Requests, Actions, Projects, and Discussions. If you are using standard screen reader commands, you can press the letter T to navigate through tab items, or simply press the letter K to navigate through links until you hear Discussions. Then, just press Enter to open it.

-

Jamie: And what about organization level discussions? I have heard that is a thing now too.

-

Alex: Yes, it is! Let us define what an organization is first. On GitHub, an organization is a shared account where businesses or large open source communities can manage multiple repositories at once. Some large organizations enable Discussions at the organization level, completely separate from any specific repository.

-

Jamie: Why would they do that?

-

Alex: Think of the organization level discussion as the town square, while the repository discussion is a specific building. The town square is for organization wide announcements, community introductions, cross project feature brainstorming, and community spotlights. You find them by navigating to the organization's main page and looking for the Discussions tab there.

-

Jamie: Okay, so I have successfully navigated to the Discussions tab on a repository. What am I going to hear as I read down the page? Is it just a giant list of random posts?

-

Alex: Not at all. The Discussions home page is highly organized into categories. When you land on the page, the main content area lists the most recent or popular discussions, but they are grouped by these categories. Each category is a section with its own heading.

-

Jamie: What kind of categories are we talking about?

-

Alex: GitHub provides a few default categories that most repositories use. First is General, which is for exactly what it sounds like, everything that does not fit anywhere else. Second is Q and A, which stands for Questions and Answers. This is for support questions. Third is Ideas, which is for feature brainstorming. Fourth is Show and Tell, where community members can show off projects they built using the repository's code. And finally, Announcements, which is usually restricted so only maintainers can post things like new release details or breaking changes.

-

Jamie: That sounds like the channels in a Slack or Discord server. You have your general chat, your help channel, your announcements channel. It keeps things tidy.

-

Alex: That is a perfect comparison. To navigate these categories with a screen reader, you can rely heavily on your heading navigation. If you press the number 3 on your keyboard, you will jump directly to the category headings. Once you are under a category heading, you can press the letter K to navigate through the discussion titles within that category, because those titles are links. When you find one that sounds interesting, press Enter to open it.

-

Jamie: Is there a way to see all the categories at once?

-

Alex: Yes. There is a side panel, which might be on the left or the right depending on your browser width, that shows a list of all categories along with item counts. It also has a section for pinned announcements at the top. This is a great place to start if you want to filter the view to only show discussions from a specific category.

-

Jamie: Alright, let us say I have searched through the existing discussions, and I cannot find the answer to my question. By the way, how do I search?

-

Alex: Great question. You should always search before posting! You can use the search bar at the top of the Discussions page. Or, if you are using GitHub's global search from anywhere on the site, you can type repo colon owner slash name, space, in colon discussions, followed by your search terms.

-

Jamie: Okay, so I have searched, and nobody has asked my question yet. I need to create a new discussion. How do I do that?

-

Alex: From the main Discussions tab, you want to navigate to the button labeled New discussion and activate it by pressing Enter.

-

Jamie: Okay, that sounds like a lot of steps. I have to find the right tab, search, find a button, pick categories. It feels a bit intimidating for someone just trying to ask a question.

-

Alex: It does! But here is the thing, Jamie. You have already done most of this on day one when we learned about creating issues. It is the exact same workflow, just with a different label at the top. You are going to use the exact same text editor, the exact same markdown formatting, and the exact same keyboard shortcuts.

-

Jamie: Oh, well that is a relief. So what happens after I activate the New discussion button?

-

Alex: The first thing you have to do is select a category.

-
- - -

Episode 25: Releases, Tags, and Insights

-

Semantic versioning, GitHub Releases, and repository analytics.

-

Based on: Appendix H: Releases, Tags, and Insights

- - -

Download Episode 25 (MP3)

-
-Read Transcript - Episode 25: Releases, Tags, and Insights - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. I am Alex, and this is episode 25 of our audio series for blind and low-vision developers. Today, we are talking about Releases, Tags, and Repository Insights.

-

Jamie: I am Jamie, and I am so excited for this one. Up until now, we have spent a lot of time talking about how to get your code into a project. We have covered making commits, opening pull requests, and getting those pull requests merged. But today is about what happens next. How does that merged code actually get to the people who use the software?

-

Alex: Exactly. And as a prerequisite, if you are fuzzy on the pull request workflow, you might want to revisit our previous episodes on creating and merging pull requests, because today builds right on top of that foundation. Today, we will explore how maintainers package up a bunch of merged pull requests into an official version, and how you can explore a repository to understand how active and healthy it is before you even decide to contribute.

-

Jamie: I remember when I first started learning GitHub about two years ago. I would get my pull request merged, and I would immediately run over to my terminal, update the software I was using, and my new feature would not be there. I was so confused. I thought merging meant it was instantly available to the world.

-

Alex: That is a very common misconception. When your pull request gets merged, it just becomes part of the code on the default branch. But most people who use the software do not download the raw, bleeding-edge default branch every day. They wait for an official release.

-

Jamie: Right. And that is exactly what we are going to demystify today. We will cover Git tags, semantic versioning, creating GitHub releases, and then we will switch gears to talk about the Insights tab, which is basically the heartbeat of a repository.

-

Alex: Let us dive right in with the fundamental building block of a release. Before we can talk about GitHub releases, we have to talk about Git tags. Jamie, how would you describe a branch compared to a tag?

-

Jamie: Well, a branch is a movable pointer. We have talked about this before. When you add a new commit to a branch, the branch pointer moves forward to include that new commit. It is always pointing to the latest work. But a tag is entirely different. A tag is a fixed pointer to one single, specific commit. It never moves.

-

Alex: That is spot on. I like to use the analogy of a bookmark in a really long, constantly growing book. The author keeps adding new pages to the end of the book. A branch is like a bookmark that you always keep moving to the very last page you read. But a Git tag is a bookmark you glue onto page 100, and you write chapter one on it. No matter how many more pages the author writes, that bookmark will always point exactly to page 100.

-

Jamie: I love that. So when a project reaches a stable point, the maintainer glues a bookmark onto that exact commit and names it something like version 1 point 0. That way, anyone can jump back to that exact state of the code at any time.

-

Alex: Precisely. Now, within Git, there are two types of tags you can create. There are lightweight tags, and there are annotated tags.

-

Jamie: I know the difference here! A lightweight tag is literally just a name attached to a commit. It is like taking a blank sticky note, writing version 1 point 0 on it, and slapping it on the page. It does not store any extra information. But an annotated tag is much richer.

-

Alex: Yes, an annotated tag is stored as a full object in the Git database. Returning to our analogy, an annotated tag is like a formal library index card. It includes the tag name, but it also records the name and email of the person who created the tag, the date it was created, and a tagging message. It can even be cryptographically signed. If you are tagging a public release of software, you almost always want to use an annotated tag.

-

Jamie: So we have this tag, and we are going to name it with a version number. But version numbers can be really confusing when you are new. You see things like version 2 point 1 point 4. What do all those numbers actually mean?

-

Alex: Most open source projects use a system called Semantic Versioning, often shortened to semver. In semantic versioning, the number is broken into three parts separated by periods. Major, minor, and patch. So in version 2 point 1 point 4, the major version is 2, the minor version is 1, and the patch version is 4.

-

Jamie: Okay, so how do I know when to change which number? Let us say I am the maintainer. When do I bump the major, minor, or patch version?

-

Alex: Let us use an analogy of a car model to make this concrete. The last number, the patch version, is for backward-compatible bug fixes. If you fix a typo in the code, or resolve a crash without changing how the software is used, you bump the patch number. In our car analogy, this is like fixing a flat tire or replacing a faulty windshield wiper. The car still drives exactly the same way. The user does not have to learn anything new. You would go from version 2 point 1 point 4 to version 2 point 1 point 5.

-

Jamie: Got it. Patch means bug fix. What about the middle number, the minor version?

-

Alex: You bump the minor version when you add new features, but they are backward-compatible. This means existing users can upgrade without breaking their current setup. In the car analogy, bumping the minor version is like adding a brand new Bluetooth stereo system or heated seats. You added new functionality, but the steering wheel and the gas pedal are exactly where they have always been. The driver can just get in and drive. If you add a new command to your software, you bump the minor version. You would go from version 2 point 1 point 4 to version 2 point 2 point 0. Notice that when you bump the minor version, the patch number resets to zero.

-

Jamie: Okay, that makes sense. So that leaves the first number, the major version. I am guessing this is the big one.

-

Alex: It is. You bump the major version when you make breaking changes. This means you have changed the existing behavior in a way that is incompatible with previous versions. Users might need to rewrite their own code or change their configurations to use the new version. In our car analogy, a major version bump is like replacing the gas engine with a manual transmission electric engine, and moving the steering wheel to the back seat.

-

Jamie: Oh wow, yeah, the driver is going to need a new manual for that.

-

Alex: Exactly. If someone tries to drive it exactly like the old car, they are going to crash. So you signal that danger by bumping the major version. You would go from version 2 point 2 point 0 all the way to version 3 point 0 point 0. The minor and patch numbers reset to zero.

-

Jamie: That is a really helpful way to think about it. Patch is a fix, minor is a safe new feature, and major means read the instructions because things have changed.

-

Alex: So now we understand Git tags and semantic versioning. But a Git tag is just a raw marker in your code history. GitHub takes that concept and builds a whole feature around it called a GitHub Release.

-

Jamie: This is an important distinction. A tag is a Git concept. It exists on your local machine and in the terminal. But a Release is a GitHub concept. It only exists on the GitHub platform.

-

Alex: Exactly. If a tag is the bookmark glued to a specific page, a GitHub Release is the fancy gift box you hand to your users. Every GitHub Release is backed by a Git tag, but the Release adds extra things. It adds formatted release notes explaining what changed, and it can include downloadable release assets.

-

Jamie: Let us talk about those release notes first. When I navigate to a repository on GitHub, how do I actually find the releases with my screen reader?

-

Alex: From any repository home page, you can use your screen reader's heading navigation. Press the letter H, or specifically the number 3, to navigate through the level 3 headings in the right sidebar. You will find a heading called Releases. Right below that heading, there is usually a link to the latest release, like version 2 point 1 point 0. You can activate that link to go straight to it. Or, you can navigate slightly further down to a link that says something like Five Releases, which will take you to a list of all historical releases.

-

Jamie: And when I open that releases page, what is the structure like? How do I read it?

-

Alex: The main releases page lists everything in reverse chronological order. Each release is enclosed in its own section. You can press the number 2 to jump between the major section headings, and the number 3 to jump to individual release titles. Once you are on a release title, you can use your down arrow to read the release notes.

-

Jamie: I love reading good release notes. A well-maintained project will categorize the changes. They will have a heading for Breaking Changes, a heading for New Features, and a heading for Bug Fixes. It makes it so easy to skim. And usually, each bullet point mentions the pull request number and the username of the person who contributed it.

-

Alex: That is one of the best feelings as a new contributor. You open the release notes for a major project, and right there under Bug Fixes, you hear your own username read aloud. It is tangible proof that your code is out in the world.

-

Jamie: At the bottom of the release notes, there is usually a section for downloading release assets. What exactly are release assets?

-

Alex: Assets are the actual files the user needs. GitHub automatically generates two source code archives for every release, a zip file and a tar dot gz file. This is just the raw code at that specific tag. But maintainers can also attach custom assets. If it is a desktop application, the assets might be the compiled executable file for Windows, and the dot app file for Mac. You can use the letter K to navigate through the links in the release section to find the asset downloads.

-

Jamie: Okay, so that is how we consume releases. But what if I am a maintainer, or I am volunteering on an open source project, and they ask me to create the new release? That sounds like a lot of pressure. Do I have to manually write out every single thing that changed?

-

Alex: You used to have to do that, and it was tedious. But GitHub has made this incredibly smooth now. Let us walk through creating a release from the GitHub web interface. First, you navigate to the main releases page, and you activate the link called Draft a new release.

-

Jamie: OK that sounds like a lot of steps, but I am guessing it is mostly a form to fill out?

-

Alex: It is! You are just filling out a web form. The first thing you do is choose a tag. You can type in a brand new version number, like v 2 point 1 point 0. If the tag does not exist yet, GitHub will automatically create it for you when you publish. Next, you choose the target branch, which is usually your main branch. Then you give the release a title, which is often just the version number again.

-

Jamie: And then comes the release notes text area. This is where the magic happens, right?

-

Alex: Exactly. Right above the text area, there is a button called Generate release notes. When you activate this, GitHub automatically looks at every single pull request that has been merged since the previous release. It grabs the titles, the author names, and the links, and it formats them perfectly into markdown inside the text area. It is like having a personal assistant summarize a month's worth of meeting notes in two seconds.

-

Jamie: Oh that is clever! I wish I had known that when I started. I definitely spent hours manually copying and pasting pull request titles into a text document.

-

Alex: We have all been there. Once the notes are generated, you can manually edit them. You might want to group them into headings or add a friendly introductory paragraph. Then, you have the option to attach any binary files if you have them. Finally, you choose whether to publish it, or save it as a draft.

-

Jamie: Let us talk about drafts and pre-releases. There are checkboxes for those on the form. A draft release is just what it sounds like, right? It is saved, but only repository collaborators can see it. It is great for preparing the notes a few days before the actual launch.

-

Alex: Exactly. And a pre-release is slightly different. A pre-release is published and visible to the public, but it is not marked as the Latest release. When users visit the repository, GitHub will not automatically direct them to a pre-release.

-

Jamie: Why would you use a pre-release?

-

Alex: You use a pre-release for early testing versions. In semantic versioning, you might append a suffix, like version 2 point 1 point 0 dash alpha point 1, or dash beta point 2. It signals to users, hey, this is available to test, but it might still have bugs. Only adventurous users should download it.

-

Jamie: Before we move on from creating releases, I want to mention a massive shortcut for screen reader users who use VS Code. If you are using the Accessibility Agents extension we have talked about in previous episodes, you do not even need to navigate the web form to write your notes.

-

Alex: That is right. You can open the GitHub Copilot chat in VS Code, and type the command slash draft dash release, followed by the version number. The agent will analyze your repository, categorize all your merged pull requests into Features, Bug Fixes, and Dependencies, and output perfectly formatted markdown right in your chat window. You can just copy it and paste it wherever you need it.

-

Jamie: Alright, so releases tell us what a project has shipped. But what if I am evaluating a new repository, and I want to know if it is actually healthy? I want to know if the maintainers are active, if people are contributing, and if it is a welcoming place. How do I find that out?

-

Alex: That is where the Insights tab comes in. The Insights tab is a dedicated section of the repository that shows quantitative activity data. To get there, you navigate to the main repository tab bar by pressing the letter T, and then navigate through the tabs until you find the link called Insights.

-

Jamie: Now, I have to be honest here. As a screen reader user, the Insights tab used to be my least favorite place on GitHub. It is heavily visual. It is full of line charts, bar charts, and scatter plots that are rendered in HTML canvas elements. When my screen reader hits those, it just says graphic or image, and I get absolutely zero information.

-

Alex: That is a very fair critique, and it is a common frustration. But here is the secret to navigating the Insights tab with a screen reader. Almost every single visual chart on those pages has a fully accessible HTML data table located directly below it. The strategy is to completely ignore the canvas graphics. When the page loads, just press the letter T to jump straight to the data tables. All the exact same information is right there in text format.

-

Jamie: That is a lifesaver. Okay, so when I open the Insights tab, the left sidebar has a sub-navigation menu with several different views. The first one, which is the default landing page, is called Pulse. What is Pulse?

-

Alex: Pulse is exactly what it sounds like. It is the heartbeat of the project. It gives you a summary of all the activity over a specific time period, usually the last week or the last month. You will find headings for Merged pull requests, Open pull requests, and Closed issues. Under each heading is a plain text list of the actual work that happened, with links to the items.

-

Jamie: This is my go-to page when I am looking for an open source project to contribute to. If I look at the Pulse for the last month, and I find zero merged pull requests, and fifty open issues, that is a zombie project. The maintainer is gone. I am not going to waste my weekend writing a pull request that will never get reviewed.

-

Alex: That is exactly how you should use it. Conversely, if you see that ten pull requests were merged by five different authors, that tells you the project is alive, active, and welcoming to multiple contributors.

-

Jamie: What about the Contributors view? That is another link in the Insights sidebar.

-

Alex: The Contributors view shows who is building the project. Visually, it is a big timeline chart, but again, jump down to the table. The table lists every person who has contributed to the default branch. It shows their username, their total number of commits, and how many lines of code they have added and deleted. You can use your Tab key to navigate the column headers and sort the table.

-

Jamie: I remember the day my name finally appeared in one of those contributor tables. It was such a proud moment. And it is actually really useful because you can link directly to your section of the contributor page to prove your involvement in a project to potential employers.

-

Alex: Absolutely. Next in the sidebar is the Traffic view. Now, you can only access the Traffic view if you are a repository owner or a collaborator with push access. It shows you who is visiting the repository. It tracks total page views, how many times the repository has been cloned, and referring sites, which tells you if people are finding your project from Google, or Twitter, or a specific blog post.

-

Jamie: Why does traffic matter for developers? We are not marketing people.

-

Alex: It matters for documentation and community growth. The Traffic view has a table called Popular Content that shows exactly which files get the most views. If you see that a specific tutorial file in your repository is getting thousands of views a week, you know that file is critical. You should probably spend time making sure that specific tutorial is perfectly accessible and up to date, because it is the front door to your project.

-

Jamie: Let us talk about a view in the Insights tab that has major security implications. The Dependency graph.

-

Alex: The dependency graph is crucial. Modern software is rarely built from scratch. We rely on dozens, sometimes hundreds, of external libraries and packages. The dependency graph reads your configuration files and creates a list of everything your project relies on.

-

Jamie: I like to think of the dependency graph as a recipe's ingredient list. If I am baking a cake, the dependency graph lists the flour, the sugar, and the eggs. But why is it in the Insights tab?

-

Alex: Because it feeds one of GitHub's most important security features, called Dependabot. Let us stick with your recipe analogy. Imagine there is a national recall on the specific brand of flour you use because it is contaminated. Dependabot acts like a grocery store manager who constantly monitors recall lists. Because the manager has your exact ingredient list, your dependency graph, they can immediately tap you on the shoulder and say, hey, your flour is bad. Here is a safe brand to use instead.

-

Jamie: And Dependabot actually does more than just tap you on the shoulder. It will automatically open a pull request in your repository to update the vulnerable dependency to a safe version. All you have to do is review the pull request and merge it. It is incredible.

-

Alex: It really is. There is one more section in the Insights area we need to cover, and that is Community Standards. You can usually find this in the Insights sidebar, or sometimes linked directly from the main repository page in the right sidebar.

-

Jamie: The Community Standards page is essentially a checklist of community health files. It lists things like a README, a Code of Conduct, a Contributing guide, a License, and Issue templates. Next to each item is a simple status of either a checkmark or an X.

-

Alex: A fully green checklist signals a mature, well-maintained project. It means the maintainers have taken the time to set rules and provide instructions for newcomers.

-

Jamie: And here is a pro-tip for our listeners. If you are looking for an easy way to make your first contribution to an open source project, check their Community Standards page. If they are missing a Code of Conduct or a Contributing guide, those are fantastic good first issues. You can draft the text, open a pull request, and help them turn that X into a checkmark. Maintainers love that kind of help.

-

Alex: That is a brilliant suggestion. Now, before we wrap up, I want to offer one more alternative for our screen reader users. If you do not want to navigate the Insights tab in the web browser at all, the Accessibility Agents extension in VS Code has commands for this, too.

-

Jamie: Yes! You can open Copilot chat and type slash my dash stats. It will output a beautifully formatted text summary of your personal contributions across all your tracked repositories. It tells you how many pull requests you opened, how many reviews you completed, and how many commits you pushed.

-

Alex: And if you are working on a team, you can type slash team dash dashboard. It generates a text-based report of team-wide activity, showing who is reviewing code, what issues are open, and overall project health. It gives you the power of the Insights tab without ever leaving your code editor or fighting with a canvas graphic.

-

Jamie: We covered a huge amount of ground today. From gluing bookmarks onto pages, to ingredient lists, to checking the heartbeat of a project.

-

Alex: Let us summarize the key takeaways. First, a Git tag is a fixed, named pointer to a specific commit, while a GitHub Release wraps that tag with release notes and downloadable assets.

-

Jamie: Second, semantic versioning uses three numbers. Major, minor, and patch. Remember the car analogy. Patch is a bug fix like a new tire. Minor is a new feature like a stereo. And Major is a breaking change like an entirely new engine.

-

Alex: Third, when reading the Insights tab with a screen reader, remember to skip past the visual canvas charts by pressing the letter T, and use the accessible data tables located immediately below them to read the exact same information.

-

Jamie: And fourth, use the Pulse view to check a project's heartbeat before you contribute. Look for recently merged pull requests to ensure the maintainers are actually active and reviewing code.

-

Alex: That brings us to the end of episode 25. Now that we understand how releases and insights work, we are ready to take on larger responsibilities. In our next episode, we will be shifting gears to talk about repository management. We will cover protecting your main branch, setting up rulesets, and managing collaborator access.

-

Jamie: I cannot wait. Thanks for listening, everyone. Happy coding!

-

Alex: See you next time on Gitt Going with GitHub.

-
- - -

Episode 26: GitHub Projects Deep Dive

-

Project boards, table and roadmap views, custom fields, cross-repo management.

-

Based on: Appendix I: GitHub Projects Deep Dive

- - -

Download Episode 26 (MP3)

-
-Read Transcript - Episode 26: GitHub Projects Deep Dive - -

Transcript

-

Alex: Welcome back to Gitt Going with GitHub. I am Alex, and today we are diving into Episode 26, which is our GitHub Projects Deep Dive.

-

Jamie: Hello everyone, I am Jamie! I am very excited for this one. I know we touched on the basics of projects back in Episode 8, along with labels and milestones. But today we are going all in, right?

-

Alex: Exactly. Back in Episode 8, we covered the prerequisites. We learned how to attach a project to a single repository and how to find it. Today, we are looking at GitHub Projects version two as a complete project management system. We will cover the different layouts like tables and boards, how to create custom fields, tracking work across multiple repositories at once, and my absolute favorite part, built-in automations.

-

Jamie: Automations! That sounds amazing, but also a little intimidating. I remember when I first started learning GitHub about two years ago, just managing a single repository felt like a lot. Now we are talking about automating work across multiple repositories?

-

Alex: It does sound like a lot! But here is the thing, you have already done most of this on Day 1 of your journey. You already know how to open an issue, how to close a pull request, and how to assign a label. This is the exact same workflow, just with GitHub handling the heavy lifting of organizing it all for you.

-

Jamie: That is a relief. So, before we get into the how-to, you mentioned Projects version two. What happened to version one? And why do I sometimes see older forum posts talking about Projects Beta?

-

Alex: Great question. GitHub has two generations of project tooling. The current generation is officially called Projects version two, but you will just see it labeled as Projects everywhere on the platform today. The older version, Classic Projects, was basically just a simple Kanban board. It was like having a basic corkboard on your wall where you could pin up index cards. It was fine, but very limited.

-

Jamie: And let me guess, version two is the upgrade?

-

Alex: A massive upgrade. If Classic Projects was a simple corkboard, Projects version two is like a smart digital spreadsheet that updates itself. You can add custom fields, switch between different views, and pull in work from anywhere in your organization. When it was first being tested, it was called Projects Beta, but it is fully stable now and it is the default.

-

Jamie: So let us start at the very beginning. How do I actually create a new project?

-

Alex: You can create a project at two different levels. The repository level, which scopes the project to just one repository, or the organization level, which lets you share the project across all repositories in that organization.

-

Jamie: I usually work in an organization with a few different repositories for the frontend, backend, and documentation. So I would probably want an organization-level project, right?

-

Alex: Exactly. To do that, you navigate to your organization page. You will activate the tab called Projects. From there, you just tab to the button called New project and press Enter.

-

Jamie: Does it just give me a blank slate?

-

Alex: It opens a template menu first. You can use your arrow keys to browse through template cards, like a blank table, a blank board, or a feature release template. Once you press Enter on a template, you just type in a name for your project, tab to the Create project button, and you are in.

-

Jamie: Okay, so I have created my project. What does it actually feel like to navigate? You mentioned different layouts earlier.

-

Alex: Yes, there are three main layouts in Projects version two. The Table view, the Board view, and the Roadmap view. Every concept we talk about today revolves around these three views. Let us start with the Table view, because it is the default, and honestly, it is the most robust for screen reader users.

-

Jamie: Table view sounds like a spreadsheet.

-

Alex: That is the perfect analogy. The Table view is a massive spreadsheet-style grid. Each row represents a single item, which could be an issue or a pull request. And we should define a pull request again really quickly. I love that name because you are literally requesting that someone pull your code changes into their project.

-

Jamie: And so the rows are the issues or pull requests. What are the columns?

-

Alex: The columns are fields. Title, Status, Assignee, Labels, Priority, and any custom fields you create. The Table view is best for bulk editing, sorting, and seeing many items at once.

-

Jamie: How do I move around this giant spreadsheet with my screen reader?

-

Alex: You can press the letter T to jump straight to the table data region. From there, you use your Up and Down arrow keys to move between rows, and your Left and Right arrow keys to move between columns in that row.

-

Jamie: What does the screen reader actually announce when I am moving through the rows?

-

Alex: If you are arrowing down through the rows, your screen reader will read a summary of that row. It might say something like, Fix keyboard trap in modal dialog, Status In Progress, Assignee Alice, Priority High.

-

Jamie: That is really efficient. But what if I want to actually edit one of those cells, like change the priority?

-

Alex: If you are using NVDA, you will want to use Browse mode to read the cell content, which you toggle with NVDA plus Space. When you find a cell you want to edit, you press NVDA plus Space again to switch to Application mode, and then press Space or Enter to activate the editor for that cell. If you are using JAWS, you press Enter to switch to application mode in the table.

-

Jamie: Oh, I love a good keyboard shortcut. Are there any others for the Table view?

-

Alex: Yes! If you are focused on the Title cell of an issue, you can press F 2 to edit the title inline, without ever leaving the table. But the most important key is Enter. If you press Enter on any row, it opens the item detail panel in a right sidebar. You can tab through all the fields for that issue in one vertical list, make your changes, and then press Escape to close the panel and pop right back into your table.

-

Jamie: Okay, so Table view is our heavy duty spreadsheet. What is the Board view?

-

Alex: The Board view uses Kanban-style columns. Kanban is a project management framework that focuses on visualizing work. Think of it like having three physical baskets on your desk. One basket is labeled To Do, one is In Progress, and one is Done. Each issue is a piece of mail. As you work on an issue, you move it from one basket to the next.

-

Jamie: That makes sense for visualizing a workflow. But wait, visually moving cards between columns usually means drag-and-drop. Drag-and-drop is notoriously terrible for accessibility. How do we handle that?

-

Alex: You hit the nail on the head. Drag-and-drop is not keyboard accessible in this view. But you do not need to drag anything. Remember that right sidebar detail panel I just mentioned?

-

Jamie: Yes, the one you open by pressing Enter.

-

Alex: Exactly. To move a card to a different column, you just tab to the card, press Enter to open the detail panel, and navigate to the Status field. You activate the Status dropdown, select your new column like In Progress, and press Escape. The card instantly moves to the new column.

-

Jamie: Oh, that is clever! You are just updating the underlying data, and the visual board updates automatically to match it.

-

Alex: Precisely. The columns in Board view are just visual representations of a specific field, usually the Status field. Change the field, change the column.

-

Jamie: That brings us to the third layout, the Roadmap view. What is that?

-

Alex: The Roadmap view is a horizontal timeline. Items appear as blocks spanning across their start and due dates. It is heavily used by product managers for release planning, or communicating timelines to stakeholders. If we stick to our analogies, the Roadmap is like a train schedule. It shows you when things are supposed to depart and arrive.

-

Jamie: How accessible is a visual timeline like that?

-

Alex: To be completely transparent, the Roadmap view is chart-based. While there is some basic navigation, the underlying data is what matters. For screen reader users, I always recommend treating the Roadmap as a visual summary for sighted colleagues, while you use the Table view for all of your actual planning and editing. Any dates you set in the Table view will automatically populate the Roadmap chart.

-

Jamie: Okay, so we have our views. But a project is useless without actual work in it. How do I add my issues and pull requests to this project?

-

Alex: From any project view, you can navigate to the bottom of a table or column and activate the button called Add item. When you do that, a text field appears. If you type the number sign, also known as the hash symbol, it instantly triggers a search of your repository issues and pull requests. You just type a keyword or the issue number, arrow down to the one you want, and press Enter.

-

Jamie: And that pulls the issue out of the repository and into the project?

-

Alex: Not quite! It links the issue to the project. The issue still lives in its home repository. If someone comments on it in the repository, you will see those updates. The project is just a lens for viewing the work.

-

Jamie: What if I have an idea for a feature, but I am not ready to create a formal issue in the repository yet? Sometimes I just want to jot down a quick note during a meeting.

-

Alex: That is the perfect time to use a Draft Issue.

-

Jamie: A draft issue? I have never heard of that.

-

Alex: Draft issues are unique to Projects. They live only inside the project board and do not belong to any repository. It is exactly like scribbling an idea on a napkin before you write the official document. To make one, you activate the Add item button, but instead of typing a hash symbol, you just type your idea in plain text and press Enter.

-

Jamie: So it just creates a text row in my table?

-

Alex: Yes. And later, when you are ready to make it official, you can open that draft row, navigate to the button called Convert to issue, and select which repository it should live in. It instantly transforms into a real GitHub issue.

-

Jamie: I love that napkin analogy. Okay, earlier you mentioned custom fields. You said this is where Projects version two really shines. What kind of fields can we create?

-

Alex: You can add fields far beyond the GitHub defaults. There are five main types of custom fields. Text fields for free-form notes, Number fields for things like story points or estimates, Date fields for deadlines, Single select fields for dropdown menus, and Iteration fields.

-

Jamie: Let us talk about Single select fields. I assume that is for things like priority levels?

-

Alex: Exactly. Let us say you want to categorize bugs. In the Table view, you scroll all the way right to the last column header, which is a Plus button. You activate that, choose Single select, and name the field Priority. Then you type your options, like P 0, P 1, and P 2, pressing Enter after each one. You save it, and now every item in your project has a Priority dropdown.

-

Jamie: That is so much cleaner than creating a dozen different labels for every possible priority. What about that last field type you mentioned, the Iteration field? What is an iteration?

-

Alex: An iteration is a time-boxed cycle of work. Many software teams call these Sprints. You might work in two-week sprints, where the goal is to finish a specific set of tasks before the cycle ends.

-

Jamie: So how does the Iteration field handle that? Do I have to manually type in the dates for every single sprint?

-

Alex: Nope, GitHub handles the math. You create an Iteration field, tell it your sprints are two weeks long, and pick a start date. GitHub automatically generates the current sprint, the next sprint, and the ones after that. Then you just assign your issues to an iteration using that field, just like you would assign a priority.

-

Jamie: Okay, so if I have a massive project board with custom fields, priorities, and sprints, it is going to get really crowded. How do I find exactly what I need without reading through a hundred rows?

-

Alex: That is where Views and Filters come in. A view is a saved configuration of your layout, your filters, and your sorting. You can have many different view tabs at the top of your project.

-

Jamie: Like asking a librarian for exactly the books you need, and having them keep that specific stack on a desk for you?

-

Alex: Perfect analogy. Let us say you only want to see your own work. You can navigate to the filter bar and type a query. The syntax is very similar to standard GitHub search. You would type assignee colon, followed by the at symbol, and the word me. Assignee colon at me.

-

Jamie: Oh, I use that all the time in issue searches. Can I combine them? Like, show me only the bugs assigned to me that are currently in progress?

-

Alex: Absolutely. You would type assignee colon at me, space, status colon quote In Progress quote. You can also filter by custom fields, labels, or item types. For example, typing is colon issue will hide all the pull requests so you can just focus on issues.

-

Jamie: And if I get this filter perfectly tuned, I can save it as a View?

-

Alex: Yes. You navigate to the button called New view in the tab bar, set up your layout and filters, and it saves automatically. You can rename the tab to something like My Active Bugs. Every time you open the project, that tab is waiting for you.

-

Jamie: Alright, Alex, you promised we would talk about tracking work across multiple repositories. How does that work?

-

Alex: This is called a cross-repository project, and it is a game changer for open source maintainers or teams working on complex software. A single project can link to multiple repositories. It is like having a master control room that monitors several different factories at once.

-

Jamie: How do I set that up?

-

Alex: You navigate to the project overflow menu, which is labeled with three dots in the top right. You select Settings, then Manage access, and then Add repository. You can search for and link as many repositories as you need.

-

Jamie: But if I have issues from five different repositories in one table, how do I know where an issue came from?

-

Alex: You use the Repository field! In your Table view, you can make the Repository column visible. Then, you can filter by it or even group by it. You can tell the table to visually group all the rows by repository, so you have a section for the frontend repository, a section for the backend, and so on.

-

Jamie: Okay, we have reached the part I have been waiting for. Automations. You said I could hire a virtual assistant to move my papers around.

-

Alex: I did! Projects version two has native automation rules built right in. You do not need to write any complex scripts. You find them by opening that same project overflow menu and selecting Workflows.

-

Jamie: What kind of workflows are we talking about?

-

Alex: The built-in ones handle the repetitive status updates. For example, there is a workflow called Item closed. If you enable it, anytime you close an issue or merge a pull request in your repository, GitHub automatically finds that item in your project and changes its status field to Done.

-

Jamie: That is amazing. I always forget to update my project boards after I merge code. What else can it do?

-

Alex: The most powerful built-in workflow is called Auto-add to project. This is a lifesaver for cross-repository projects. Let us say you are tracking accessibility bugs across your entire organization.

-

Jamie: Okay, so I have a project board set up.

-

Alex: Right. You go to Workflows, select Auto-add to project, and turn it on. You configure a filter, like label colon accessibility. From that moment on, anytime anyone files a new issue with the label accessibility in any of your linked repositories, GitHub automatically adds it to your project board. No manual triage required.

-

Jamie: Wow. That literally does save hours of work. I wish I had known that when I started managing my first open source repository. Does it integrate with GitHub Actions for even more complex stuff?

-

Alex: It does. Projects version two has a full GraphQL API. Using GitHub Actions, which we cover deeply in the advanced appendices, you can do things like automatically assign issues to specific people based on which repository they came from, or automatically set due dates. The possibilities are endless.

-

Jamie: Before we wrap up, I want to ask about our favorite coding companion. Does GitHub Copilot know anything about our project boards?

-

Alex: It absolutely does, through Accessibility Agents. There is a specific command you can use in VS Code Copilot Chat called slash project dash status.

-

Jamie: Slash project dash status. What happens when I type that?

-

Alex: You type slash project dash status followed by the repository name. Copilot will reach out to GitHub and give you a live text overview of the project board directly in your VS Code editor, without you ever needing to open a browser.

-

Jamie: What kind of information does it give me?

-

Alex: It gives you a breakdown of how many items are in each column, who they are assigned to, and their average age. It is incredibly smart. It will specifically flag attention items, like issues that are blocked, or stale items that have been sitting in the In Progress column for more than seven days with no activity.

-

Jamie: That sounds perfect for checking what I need to work on on a Monday morning, or preparing for a standup meeting.

-

Alex: Exactly. It keeps you in the flow of your coding environment while still staying on top of project management.

-

Jamie: Alex, this has been an incredible deep dive. I feel like I am ready to upgrade my entire workflow from Classic to version two.

-

Alex: I am glad to hear it! Let us summarize with a few concrete takeaways for our listeners. First, remember that the Table view is your best friend. It is a highly accessible, spreadsheet-style interface where you can use keys like T to jump to the table, and Enter to open the item details panel to edit fields quickly.

-

Jamie: Second takeaway: you do not need to use drag-and-drop on a Kanban board! If you are in the Board view, just press Enter on a card and change its Status field in the sidebar to move it to a different column.

-

Alex: Third, take advantage of Custom Fields. Do not limit yourself to standard labels. Use single-select fields for priorities, number fields for estimates, and iteration fields to manage your two-week sprints.

-

Jamie: And fourth, turn on those Workflows! Set up the Auto-add workflow to automatically pull issues into your project based on their labels, and use the Item closed workflow to automatically mark things as Done. Let the robots do the busy work.

-

Alex: Perfectly said. That wraps up Episode 26. In our next episode, we are shifting gears slightly to talk about something crucial for every open source contributor: Code Reviews and Pull Request Etiquette. We will learn how to leave accessible review comments, how to request changes, and how to handle feedback on your own code.

-

Jamie: I definitely need that one. Thanks for listening, everyone! We will catch you in the next episode.

-

Alex: Keep coding, and keep collaborating. See you next time.

-
- - - -

GitHub search query language, qualifiers, and filtering for issues, PRs, and code.

-

Based on: Appendix J: Advanced Search

- - -

Download Episode 27 (MP3)

-
-Read Transcript - Episode 27: Advanced Search - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode 27, Advanced Search. I am Alex, and I am thrilled to be back with you for another deep dive into making GitHub work for us, rather than the other way around. Today, we are unlocking what I consider to be a developer superpower.

-

Jamie: And I am Jamie. I am so ready for this one. When I started learning GitHub about two years ago, I spent so much time just tabbing through endless lists of issues, trying to find the one bug I was supposed to be working on.

-

Alex: That is a nearly universal experience, Jamie. Most people start by navigating to a repository, moving to the section called Issues, and then tabbing through the pagination links at the bottom of the page. Next page, next page, next page. It is tedious.

-

Jamie: Extremely tedious. Especially when you have your screen reader reading out every single issue title, author, and timestamp along the way.

-

Alex: Exactly. And that brings us to today's topic. We are going to learn how to bypass all of that navigation by using GitHub's advanced search query language. For screen reader users in particular, using the search bar with precise text commands is exponentially faster and more accessible than navigating filter dropdowns, checking boxes, and waiting for the page to dynamically reload.

-

Jamie: I love anything that saves me keystrokes. Before we jump in, let us quickly remind everyone of the prerequisites. You should be familiar with the basic concepts of issues and pull requests, which we covered back in episodes 12 and 15. If you know what an issue is, and you know what a pull request is, you are perfectly positioned for today.

-

Alex: Let us start with the interface. The global search bar is located at the top of nearly every page on GitHub. But you do not need to manually navigate your cursor to it. From almost anywhere on the site, you can simply press the forward slash key.

-

Jamie: Just the forward slash?

-

Alex: Just the forward slash key. When you press it, your focus is instantly moved into the search input field. You can then type your query and press the Enter key. When the results load, they are organized into different categories.

-

Jamie: Right, and those categories are called search scopes, correct?

-

Alex: That is right. GitHub does not just search one bucket of data. It searches across multiple scopes. The main scopes are repositories, code, issues, pull requests, users, and topics. When you run a global search, GitHub searches across everything, but the results page lets you navigate to specific sections to narrow down what you are looking for.

-

Jamie: So how does global search differ from in-repository search? Because I have noticed that if I am already inside a project, the search behaves differently.

-

Alex: That is a great observation. Think of global search like walking into a massive department store and shouting, where are the shoes. You might get directed to men's shoes, women's shoes, athletic shoes, or children's shoes across the entire building. That is global search. But if you are already standing in the athletic department, and you ask the same question, the system assumes you only want athletic shoes.

-

Jamie: So if I navigate to the accessibility-agents repository, and then I press the forward slash key to focus the search bar, it automatically scopes my search to just that repository.

-

Alex: Exactly. GitHub automatically inserts a piece of text into the search bar for you. It will say repo, a colon, and then the name of the repository. This brings us to the core concept of today's episode, which is qualifier syntax.

-

Jamie: Qualifier syntax. That sounds like something out of a grammar textbook.

-

Alex: It sounds a bit dry, but it is actually very simple. A qualifier is just a filter. And the syntax, or the rules for typing it, always follows a specific pattern. It is a key, followed immediately by a colon, followed immediately by a value. No spaces in between.

-

Jamie: Key, colon, value. So if I want to search for a specific language, language is the key, and python is the value. I would type language, colon, python.

-

Alex: Spot on. And that rule about no spaces is the single most common stumbling block. If you type language, colon, space, python, GitHub thinks you are searching for the literal word python in the text, rather than filtering the results by the programming language.

-

Jamie: Oh, I have definitely done that. I would type author, colon, space, Jamie, and wonder why nothing showed up.

-

Alex: We have all been there. So, key, colon, value, no spaces. Let us look at how we apply this to issues. Issues are essentially the to-do list of a GitHub project. When you are participating in a workshop or a hackathon, finding the right issue is step one.

-

Jamie: What are the most common issue qualifiers we should know?

-

Alex: The most fundamental ones define the state of the issue. You will use the key called is. So you type is, colon, open, to find only open issues. Or is, colon, closed, to find issues that have already been resolved.

-

Jamie: That makes sense. What about finding issues that have a specific tag, like the good first issue tag we use in the workshop?

-

Alex: For that, we use the label qualifier. You type label, colon, and then the name of the label. Now, if the label name has spaces in it, like good first issue, you must wrap the value in quotation marks. So you type label, colon, quote, good first issue, quote.

-

Jamie: Okay, let me recap that. If I want to find an open issue that is a good first issue, I type is, colon, open, space, label, colon, quote, good first issue, quote.

-

Alex: Perfect. Notice how you put a space between the two different qualifiers. That is exactly right. You string them together with spaces to combine the filters.

-

Jamie: What if I want to find issues that I created? Or issues that someone else is working on?

-

Alex: You have two great qualifiers for people. The first is author, which filters by who created the issue. The second is assignee, which filters by who is currently assigned to work on it.

-

Jamie: So I could type author, colon, and my username?

-

Alex: You could, but GitHub gives us a brilliant shortcut. Instead of typing your username, you can type the at symbol followed by the word me. So author, colon, at sign, me. This is fantastic because you can share that exact query with anyone, and it will automatically filter for whoever is currently logged in.

-

Jamie: Oh that is clever! I wish I had known that when I started. I used to type my full username out every single time. So if I want to find open issues assigned to me, I type is, colon, open, space, assignee, colon, at sign, me.

-

Alex: Exactly. You can also use the milestone qualifier. A milestone is a way to group issues together for a specific release or a sprint. If you are working on the summer release, you might type milestone, colon, quote, summer release, quote.

-

Jamie: OK that sounds like a lot of steps and a lot of syntax to memorize.

-

Alex: It does! But here is the thing, you do not have to memorize them all at once. You are just learning a new way to ask for what you want. Think of it like ordering at a restaurant. You do not just say food. You say, item, colon, burger. Temperature, colon, medium. Side, colon, fries. You are just giving GitHub your exact order.

-

Alex: Let us move over to pull requests. A pull request, and I love that name because you are literally requesting that someone pull your changes into their project, has its own set of qualifiers.

-

Jamie: Because pull requests are basically issues that contain code, right?

-

Alex: Exactly. In fact, under the hood, GitHub treats a pull request as a type of issue. That means all the issue qualifiers we just talked about, like is, colon, open, and author, colon, at sign, me, work for pull requests too. But to ensure you only get pull requests and not regular issues, you add the qualifier is, colon, pr. P R stands for pull request.

-

Jamie: So if I want to find my open pull requests, I type is, colon, pr, space, is, colon, open, space, author, colon, at sign, me.

-

Alex: You got it. Now, let us look at qualifiers unique to pull requests. Often, you want to know if a pull request is ready to be merged, or if it is still a work in progress. You can use draft, colon, true, to find pull requests that are marked as drafts.

-

Jamie: And if I am a maintainer, and I want to find pull requests that have been reviewed and approved, how do I do that?

-

Alex: You use the review qualifier. You type review, colon, approved. This filters the list to only show pull requests where another developer has formally approved the code.

-

Jamie: That is incredibly useful for clearing out a backlog. What about the branches? I know when I make a pull request, I am asking to merge my feature branch into the main branch. Can I search based on those branch names?

-

Alex: Yes, and this brings us to two important technical terms, head and base. Let us define head and base using an analogy. Think of a pull request like a train arriving at a train station. The head is the moving train. It contains the new passengers, or in our case, the new code commits. The base is the station platform. It is the destination where the train is arriving.

-

Jamie: So the head is my feature branch, and the base is the main branch.

-

Alex: Exactly. If you want to find all pull requests that are targeting the main branch, you type base, colon, main. If you want to find pull requests coming from a specific feature branch, you type head, colon, feature dash accessibility.

-

Jamie: Alright, we have covered issues and pull requests. But what if I am looking for actual code? Like, what if I want to find every time a specific function is used in a project, so I can see an example of how to write it?

-

Alex: Searching code is where this system truly shines. GitHub recently completely overhauled their code search engine, and it is blazingly fast. To search code, you usually want to scope it to a specific repository or organization first, otherwise you will search all the public code in the world.

-

Jamie: Which is a lot of code.

-

Alex: A massive amount. So you start with the repo qualifier. You type repo, colon, followed by the organization name, a forward slash, and the repository name. For example, repo, colon, community dash access, forward slash, accessibility dash agents. Then, you can just type the word or function name you are looking for.

-

Jamie: So if I am looking for the term aria dash hidden, I just type repo, colon, community dash access, forward slash, accessibility dash agents, space, aria dash hidden.

-

Alex: Exactly. But we can get much more precise. We can use the language qualifier to only search inside specific programming languages. Language, colon, javascript, or language, colon, python.

-

Jamie: What if I only want to search inside markdown files, like documentation?

-

Alex: Then you use the extension qualifier. You type extension, colon, m d. M d is the file extension for markdown. You can also use the path qualifier to only search inside a specific folder. For example, path, colon, docs, forward slash. That restricts your search to only files located inside the docs directory.

-

Jamie: Let me put that all together. If I want to find the word keyboard inside any markdown file in the docs folder of my repository, I would type repo, colon, my name, forward slash, my project, space, extension, colon, m d, space, path, colon, docs, forward slash, space, keyboard.

-

Alex: That is a perfect query. You are narrowing the funnel step by step. First the repository, then the file type, then the folder, and finally the keyword. Your screen reader will then announce the number of code results found, and you can navigate through the actual snippets of code directly from the search results page.

-

Jamie: This is making so much sense. We have talked about states, labels, people, and code. What about time? Sometimes I want to find issues that have been sitting around for a long time, or maybe pull requests that were opened just this week.

-

Alex: Date range qualifiers are incredibly powerful, but they do require a specific format. You use the keys created, updated, or closed. And the value must be a date formatted as year, dash, month, dash, day. Four digits for the year, two for the month, two for the day.

-

Jamie: So for January first, twenty twenty five, I would type twenty twenty five, dash, zero one, dash, zero one.

-

Alex: Exactly. But you usually do not want things from exactly one day. You want things before or after a date. To do this, we use the greater than and less than mathematical symbols.

-

Jamie: Oh, this is where the syntax gets really strict.

-

Alex: It does, but once you type it a few times, it becomes muscle memory. If you want to find issues created after January first, twenty twenty five, you type created, colon, the greater than sign, twenty twenty five, dash, zero one, dash, zero one.

-

Jamie: And the greater than sign means after, because the dates are moving forward in time.

-

Alex: Correct. And if you wanted issues updated before January first, twenty twenty six, you would type updated, colon, the less than sign, twenty twenty six, dash, zero one, dash, zero one.

-

Jamie: What if I get hundreds of results? Can I change the order they are displayed in? Because by default, GitHub seems to show the most relevant ones, but sometimes I just want the newest ones at the top.

-

Alex: You absolutely can. And this is another huge time saver for screen reader users, because you do not have to navigate to a sort dropdown menu. You just add a sort qualifier to your text. You type sort, colon, the field you want to sort by, a dash, and then either asc for ascending, or desc for descending.

-

Jamie: Ascending means going up, and descending means going down. So if I want the newest items first, I want the creation dates going down from newest to oldest.

-

Alex: Right. So you type sort, colon, created dash desc. If you wanted the oldest items first, you would type sort, colon, created dash asc.

-

Jamie: Okay, Alex, I have to ask. I know a lot of our listeners, myself included, spend a lot of time in the terminal using the command line interface. Can we do all of this search magic without ever opening a web browser?

-

Alex: I am so glad you asked. Yes. The GitHub command line tool, which you access by typing g h in your terminal, has a dedicated search command. You just type g h, space, search, space, issues, and then you can pass in all the same qualifiers we just discussed.

-

Jamie: Wait, really? So I can type g h, space, search, space, issues, space, assignee, colon, at sign, me, space, is, colon, open?

-

Alex: Yes, exactly like that. And it will print a beautifully formatted list right in your terminal, which your screen reader will read out instantly. For many blind developers, using g h search is the absolute fastest way to find an issue, grab its identification number, and start working on it, entirely bypassing the web interface. You can search issues, pull requests, and repositories right from the command line.

-

Jamie: That is a game changer. But whether I am using the web browser or the terminal, typing out these massive queries every single day seems like it would get tiring. Is there a way to save a search? Like building a personal search library?

-

Alex: This is an area where GitHub's web interface is slightly lacking. They do not have a native, built in button that says save this search to your profile. However, there is a very simple workaround. Every time you run a search on the GitHub website, your entire query is encoded into the web address, the URL, at the top of your browser.

-

Jamie: Oh, so I can just use my web browser's bookmark feature!

-

Alex: Precisely. You construct your perfect, complex query once. Maybe it is finding all open, unassigned accessibility bugs in your organization. You run the search, ensure the results look right, and then you just bookmark that page in your browser. You can name the bookmark Open Accessibility Bugs. The next time you want to run that search, you just open your bookmarks and activate that link. It will run the search live against the current data.

-

Jamie: That is so practical. I am definitely going to create a bookmark folder just for my daily GitHub workflows. I will have one for my open pull requests, one for issues I need to review, and one for good first issues in the workshop repository.

-

Alex: That is a fantastic strategy, Jamie. And that brings us to the end of our deep dive into advanced search. We covered a massive amount of ground today, but remember, you do not need to memorize every single qualifier right now.

-

Jamie: Right, the goal is just to know what is possible, so when you are stuck looking for something, you know there is a better way to find it.

-

Alex: Exactly. Let us summarize our key takeaways for today. First, you can jump directly to the global search bar from almost anywhere on GitHub by simply pressing the forward slash key. Second, all qualifiers use a strict key, colon, value syntax with absolutely no spaces. Third, you can use shortcuts like the at symbol followed by the word me to easily find your own issues and pull requests.

-

Jamie: Fourth, code search lets you find specific functions or keywords across an entire project, and you can narrow it down using the language and path qualifiers. And fifth, you can save your most complex searches by simply bookmarking the results page in your web browser.

-

Alex: Perfectly summarized. I highly encourage everyone to spend ten minutes today just experimenting with the search bar. Try finding an issue you worked on last month. Try finding a piece of code you wrote. The more you use these qualifiers, the more natural they will feel.

-

Jamie: I am going to go set up my bookmarks right now. What are we covering in the next episode?

-

Alex: In episode 28, we are moving from finding things to reviewing things. We will be covering the pull request review interface, including how to navigate inline code comments, how to leave a review, and how to read a diff efficiently with a screen reader. It is a critical skill for open source collaboration.

-

Jamie: I cannot wait. I always find reviewing code a bit intimidating, so I am looking forward to breaking it down.

-

Alex: We will make it approachable, I promise. Thank you all for listening to Gitt Going with GitHub. Keep practicing your queries, and we will see you in the next episode.

-
- - -

Episode 28: Branch Protection and Rulesets

-

Required reviews, status checks, rulesets, and diagnosing blocked merges.

-

Based on: Appendix K: Branch Protection and Rulesets

- - -

Download Episode 28 (MP3)

-
-Read Transcript - Episode 28: Branch Protection and Rulesets - -

Transcript

-

Alex: Welcome back to Gitt Going with GitHub. This is episode 28, Branch Protection and Rulesets. I am Alex, here to guide you through the wonderful, and sometimes slightly rigid, world of repository security.

-

Jamie: And I am Jamie. I am so glad we are talking about this today because I vividly remember the first time I tried to contribute to an open source project. I did all the work, I pushed my branch, I created my pull request, and then I navigated to the bottom of the page to merge it. But I could not. The merge button was just completely unavailable to me. There were all these messages about failing checks and required reviews. I honestly panicked. I thought I had broken their entire repository.

-

Alex: I promise you, you did not break anything. What you ran into is exactly what we are covering today. That was branch protection doing its job. Think of branch protection like the velvet rope at a museum. You are absolutely welcome to come in, look around, and even sketch your own copy of the artwork. But if you want to actually alter the painting on the wall, there is a very strict process you have to follow, and a curator has to approve it. Branch protection exists to prevent accidental changes to the main branch of a repository.

-

Jamie: That makes so much sense. Because the main branch is usually the production code, right? It is the version of the software that people are actually downloading or the website that is live right now. If I could just push my experimental changes straight into main, I could take down the whole project.

-

Alex: Exactly. Before branch protection existed, if you had write access to a repository, you could just push directly to main. And people make mistakes. We type the wrong command, or we push a branch that is not finished yet. Branch protection is a safety net. It is a set of rules, configured by the repository administrators, that dictate exactly what must happen before code is allowed to be merged into a protected branch.

-

Jamie: So let us break down what those rules actually look like. We mentioned the classic approach to branch protection rules. How does that work?

-

Alex: In the classic approach, a repository administrator creates a rule for a specific branch, usually main. You can think of this rule like a pre-flight checklist on a clipboard. The pilot cannot take off until every single item on that clipboard is checked off.

-

Jamie: And the most common item on that checklist is probably a required pull request review, right?

-

Alex: Yes, absolutely. A pull request, as a quick reminder, is when you are literally requesting that the maintainers pull your changes into their project. When a branch has a required review rule, it means another human being has to look at your code and explicitly approve it. The rule might say you need one approving review, or maybe two or three for a really critical project.

-

Jamie: I have definitely seen that. I will navigate to the merge box at the bottom of the pull request page, and my screen reader will read something like, one review required. So I know I have to request a review from someone on the team. But I have a question about this. What happens if I get an approval, but then I realize I made a typo, so I push a new commit to fix it. Does my approval stay?

-

Alex: That depends on how the maintainer configured the rule, but usually, the answer is no. There is a setting called dismiss stale reviews. If that is turned on, the moment you push a new commit, any existing approvals are wiped out, and you have to get a fresh review.

-

Jamie: Oh, that is clever. Frustrating if you are in a hurry, but clever.

-

Alex: It is a great security feature. Think about it like having a co-pilot double-check your flight coordinates. If they approve the coordinates, but then you go in and change the destination by a few degrees, you want them to verify the new coordinates too. Otherwise, someone could get an approval on a perfectly safe piece of code, and then sneak in a malicious change right before merging.

-

Jamie: Okay, so required reviews are one part of the checklist. What else is on there? I know I always run into status checks.

-

Alex: Required status checks are huge. This is where Continuous Integration, or CI, comes in. CI refers to automated scripts that run every time you push code. The branch protection rule can say, these specific automated tests must pass before this pull request can be merged.

-

Jamie: So this is like an automated grammar checker that runs before you are allowed to publish an article. Or an automated car wash that your car has to go through before it goes on the showroom floor.

-

Alex: Perfect analogies. You might have a status check that compiles the code to make sure there are no syntax errors. You might have a check that runs the entire automated test suite. You might even have an accessibility-check that scans your user interface changes for basic accessibility violations. If the rule says those checks are required, the merge button will literally be blocked until every single one of them reports back with a success status. If even one test fails, you cannot merge.

-

Jamie: Okay, what about keeping things up to date? I sometimes get a message that says my branch is out of date with the base branch.

-

Alex: Right. That is another very common branch protection rule. It requires your branch to be entirely up to date with the main branch before you can merge. Let us say you created your branch on Monday. You work on it for a few days. But on Tuesday and Wednesday, other people merged their own changes into main. By Thursday, your branch is missing all the new stuff that was added.

-

Jamie: And if I just merge my code anyway, I might accidentally overwrite their changes, or introduce a bug because my code was not tested alongside their new code.

-

Alex: Precisely. So this rule blocks you from merging until you bring those new changes from main into your branch. You usually do this by activating the Update branch button in the merge box, which brings all the new main commits into your working branch. Then your automated status checks will run one more time to make sure your code still works with the new updates.

-

Jamie: That makes a lot of sense. Now, there is another rule we should talk about, because we covered the prerequisite for it back in our authentication episode. Requiring signed commits.

-

Alex: Yes, requiring signed commits is becoming very common, especially in open source. A signed commit includes cryptographic proof of your identity, usually using an SSH key or a GPG key. It proves that you are actually the person who wrote the code, and not someone impersonating you.

-

Jamie: Like putting a heavy wax seal with your family crest on an envelope, instead of just writing your return address on it.

-

Alex: Exactly. Anyone can write an address, but only you have the stamp for the wax seal. If a repository has a rule requiring signed commits, and you push a commit without a signature, the merge will be blocked. The error will say commits must have verified signatures. You will have to go back to your command line, configure commit signing, and rewrite those commits to include your signature.

-

Jamie: Which, speaking from experience, can be a little tricky if you are new to Git. If you ever run into that, definitely go back and listen to our episode on Git Authentication for a refresher. Okay, is there anything else in the classic branch protection rules?

-

Alex: There is one more major one, which is restricting who can push to the branch. You can set a rule that says, absolutely nobody is allowed to push directly to main, except for the lead maintainer, or maybe a specific release bot.

-

Jamie: Like having keycard access to the server room. Everyone can work in the building, but only the IT administrators have the badge that opens that specific door.

-

Alex: Exactly. For everyone else, they must use a pull request.

-

Jamie: Okay, so that is classic branch protection. But the title of this episode is Branch Protection and Rulesets. What is a ruleset, and how is it different?

-

Alex: Repository Rulesets are the modern, next generation approach to protecting your code. GitHub introduced them recently because classic branch protection, while great, had some limitations as companies and projects grew larger.

-

Jamie: What kind of limitations?

-

Alex: Well, classic branch protection rules are applied on a single repository, to a single branch name. If your company has five hundred repositories, and you want to ensure every single one of them requires two reviews before merging to main, you used to have to go into all five hundred repositories individually and set up that rule.

-

Jamie: Oh wow. That sounds like an absolute nightmare for a system administrator.

-

Alex: It was. And if the company policy changed to require three reviews, you had to do it all over again. Rulesets solve this by operating at the organization level. You can create one organization ruleset that says, require two reviews on the main branch for every repository we own.

-

Jamie: That is so much better. It is like upgrading from having a physical padlock on every single door in an office building, where you have to manually change the lock on every door if someone loses a key. Upgrading to a programmable smart building system where you can just update the access policy from one central computer.

-

Alex: That is a brilliant analogy. Centralized control is a huge benefit of rulesets. Another major difference is how rulesets target branches. With rulesets, you can use tag and branch patterns. Instead of just protecting the branch named exactly main, you can create a pattern using an asterisk as a wildcard.

-

Jamie: So I could write a rule for release dash asterisk, and it would automatically protect branches named release dash version one, release dash version two, and so on?

-

Alex: Exactly. Any branch that starts with the word release and a dash will automatically inherit all the protections in that ruleset. You do not have to create a new rule every time you cut a new release branch.

-

Jamie: That is incredibly powerful. Are there other differences between classic rules and the new rulesets?

-

Alex: Yes, two very important ones. Bypass lists and enforcement modes. Let us talk about bypass lists first. In classic branch protection, a rule is a rule. If you require a status check to pass, it must pass. But sometimes, you have a special automated bot that manages your releases, and you want that bot to be able to bypass the rules and merge directly.

-

Jamie: Like a VIP list at a club. The bouncer makes everyone else wait in line and check their coats, but the VIPs get to walk right past the rope. Or an emergency override key for the fire department.

-

Alex: Exactly. Rulesets allow you to configure a bypass list. You can specify exact users, teams, or automated apps that are allowed to bypass the rules. And when they do bypass a rule, GitHub logs it in an audit trail so you can see exactly who bypassed the system and when.

-

Jamie: And what about enforcement modes? You mentioned that was the other big difference.

-

Alex: Right. With classic rules, the rule is always active. It always blocks you. With rulesets, you have three modes. Active, Evaluate, and Disabled. Active means the rule is fully enforced and will block merges. Disabled means the rule is turned off. But Evaluate mode is the really interesting one.

-

Jamie: Evaluate mode? Does that mean it just watches what happens without actually blocking anything?

-

Alex: Exactly. It is essentially a testing mode. Let us say you want to introduce a new rule requiring all commits to be signed, but you are worried it might disrupt your team's workflow because people do not have their keys set up yet. You can turn the ruleset on in Evaluate mode. It will not block anyone from merging. But it will quietly log every time someone merges a pull request with unsigned commits.

-

Jamie: Oh, I love that. So you can look at the logs after a week and say, okay, fifty percent of our team is still pushing unsigned commits. We need to do a training session before we switch this rule to Active. It gives you data without causing a crisis.

-

Alex: Exactly. It makes rolling out security changes much less stressful for administrators. Now, keep in mind, as a contributor or a workshop participant, you will probably encounter both systems. Many repositories still use classic branch protection rules because they have been around forever. Newer repositories, or large enterprise organizations, are moving toward rulesets. But for you, as the developer trying to merge a pull request, the experience is largely the same. The merge button will be blocked until you meet the requirements.

-

Jamie: Okay, let us talk about that experience. Because that is the most stressful part for a learner. You open your pull request, you think you are done, and then you hit a wall. If my merge is blocked, how do I actually figure out what is wrong, especially using a screen reader?

-

Alex: This is such an important skill. The first thing to know is that GitHub tells you exactly what is wrong. It does not hide it. All the diagnostic information is located in the merge box, which is near the bottom of the pull request page.

-

Jamie: So if I am using my screen reader, how do I get there efficiently? The pull request page can be really long if there is a big conversation happening.

-

Alex: There are a few ways. The quickest way is often to use the H key to jump through the headings on the page until you hear something related to merging. The merge box is contained within a section that usually has a heading like, Merging is blocked, or This branch has no conflicts.

-

Jamie: If I am using NVDA, I will sometimes press NVDA plus F7 to open the elements list, filter by headings, and just type the word merge to jump straight to that section.

-

Alex: That is a fantastic technique. Once your focus is on that heading, you can just use your down arrow key to read the contents of the merge box. GitHub provides a checklist of exactly what is passing and what is failing. As you arrow down, you might hear, Review required. At least one approving review is required. Or you might hear, Some checks were not successful.

-

Jamie: Okay, so let us say I hear that some checks were not successful. How do I find out which test failed? Because just knowing a test failed does not help me fix my code.

-

Alex: Right. You need to read the diagnostic codes, just like a mechanic reading the engine light on a dashboard. In that same merge box area, you can press the Tab key until you reach a button or link that says, Show all checks. Press Enter to activate it. This expands a list of every single status check that ran against your pull request.

-

Jamie: And then I just tab through that list?

-

Alex: Yes. As you tab or arrow through the expanded list, your screen reader will announce the name of each check, and its status. It will say something like, build process, successful. Linting, successful. Unit tests, failing.

-

Jamie: And when I find the failing one, how do I see why it failed? Is there a log file?

-

Alex: Yes. Right next to the status of the failing check, there is a link that says Details. When you press Enter on the Details link, you will navigate away from the pull request page and into the specific log page for that check.

-

Jamie: I have found those log pages can be a bit overwhelming. They are basically just giant text dumps of terminal output.

-

Alex: They can be, but they follow a predictable structure. When the log page loads, press the H key to jump to the Summary heading. Arrow down from there to read a high-level overview of what failed. If you need to read the raw log output, it is usually presented in a pre-formatted text block or a series of expandable accordions. You can tab to the specific step that failed, press Enter to expand it, and then use your down arrow key to read the terminal output line by line. Look for words like error or exception.

-

Jamie: That is super helpful. It sounds like a lot of steps, but it really is just a process of elimination. Jump to the merge box, read the checklist, expand the checks, find the failure, open the details, read the log.

-

Alex: Exactly. And I want to normalize this. Having a blocked pull request does not mean you are a bad developer. It happens to senior engineers every single day. A linting check fails because they forgot a semicolon. A test fails because they missed an edge case. Branch protection is not a punishment. It is an automated assistant helping you catch things before they become real problems in production.

-

Jamie: I love that reframing. It is not a bouncer kicking you out of the club. It is a friendly assistant saying, hey, your tie is crooked, let us fix that before you go on stage.

-

Alex: Exactly! Now, what if you check the merge box, and all the automated checks are passing, but the merge is still blocked. What else could it be?

-

Jamie: Well, based on what we talked about earlier, it could be that I need a review. I would hear, review required. In that case, I need to navigate to the right sidebar, find the Reviewers section, and request a review from a maintainer.

-

Alex: Correct. What else?

-

Jamie: It could be the out of date warning. The screen reader would say, this branch is out of date with the base branch. I would just need to find the Update branch button in that same merge box and activate it.

-

Alex: Spot on. And if you hear, commits must have verified signatures, you know you need to go back to your terminal and sign your work. The merge box is your single source of truth for understanding exactly what the repository rules require from you.

-

Jamie: So, as we wrap up, I am curious about how these rules look in the real world. Do most repositories have all of these rules turned on?

-

Alex: It completely depends on the context. Let us look at a few common configurations. If you are working on a small team, maybe three or four developers building a startup product, the rules are usually pretty light. It is like a local coffee shop. You might have a rule that requires one approving review, and maybe a basic status check to make sure the code compiles. You want to move fast, and you trust your small team.

-

Jamie: That makes sense. You do not need a massive security apparatus for four people sitting in the same room. What about an open source project?

-

Alex: An open source project is more like a busy public library. Anyone in the world can walk in and suggest changes. So the rules are much stricter. You will almost certainly see requirements for multiple reviews from core maintainers. You will see extensive automated testing, because the code has to work on many different operating systems. And you will very often see a requirement for signed commits, to prevent bad actors from submitting malicious code under someone else's name.

-

Jamie: Right, because you do not personally know the people submitting the pull requests. You have to rely on the automated rules to verify their identity and their code quality.

-

Alex: Exactly. And finally, you have the enterprise configuration. Think of a massive banking network. Thousands of developers, strict regulatory compliance, and huge financial risk. In an enterprise, you will see complex organization-level Rulesets. They will enforce multiple reviews, extensive security scanning, accessibility checks, and strict branch naming conventions. They will use bypass lists heavily to allow their automated deployment bots to do their jobs, while strictly locking down human access.

-

Jamie: It is amazing how flexible the system is. It scales from a tiny startup to a massive bank, all using the exact same underlying concepts.

-

Alex: It really is. And as a developer, your job is not necessarily to configure all of these rules, unless you are the repository administrator. Your job is simply to understand that these rules exist, respect the velvet rope, and know how to read the merge box to satisfy the requirements.

-

Jamie: This has been incredibly clarifying. I feel like I understand the why behind all those blocking messages now. Let us summarize the key takeaways for our listeners today. First, branch protection exists to prevent accidental or unverified changes from entering the main branch. It is a safety net, not a punishment.

-

Alex: Second, classic branch protection uses rules tied to a specific branch in a single repository. Common rules include requiring pull request reviews, requiring automated status checks to pass, forcing branches to be up to date, and requiring signed commits.

-

Jamie: Third, Repository Rulesets are the modern upgrade. They allow administrators to apply rules across entire organizations, use wildcards to protect multiple branches at once, set up bypass lists for VIP access, and use Evaluate mode to test rules before enforcing them.

-

Alex: And finally, when your merge is blocked, do not panic. Navigate to the merge heading using your screen reader, read the checklist, expand the status checks, and read the logs. The merge box will always tell you exactly what you need to do to move forward.

-

Jamie: I am definitely going to be less intimidated the next time I see a grayed out merge button. So, what are we covering in the next episode?

-

Alex: Next time, we are going to dive deeper into the actual review process. We have talked about requiring reviews, but how do you actually leave one? We will cover how to navigate a pull request diff, leave inline comments, and officially approve or request changes on someone else's code.

-

Jamie: That is going to be great. I cannot wait to learn how to be a good reviewer. Thanks for listening, everyone, and we will catch you in the next episode of Gitt Going with GitHub.

-
- - -

Episode 29: GitHub Security Features

-

Dependabot, secret scanning, code scanning, and private security advisories.

-

Based on: Appendix L: GitHub Security Features

- - -

Download Episode 29 (MP3)

-
-Read Transcript - Episode 29: GitHub Security Features - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode twenty nine, GitHub Security Features. I am Alex, and today we are talking about how GitHub helps keep your code, your contributors, and your users safe.

-

Jamie: And I am Jamie. I have to be honest, Alex, the word security always makes me a little nervous. It feels like one of those areas where making a mistake has massive consequences. When I first started learning GitHub a couple of years ago, I was terrified I would accidentally break something or leak something important.

-

Alex: That is a completely normal way to feel. Security can be intimidating. It sounds like a lot of high stakes pressure. But here is the thing, GitHub has built a massive safety net directly into the platform. You do not have to be a cryptography expert to write secure code. Today, we are going to learn how GitHub automates most of this heavy lifting for you.

-

Jamie: That is a huge relief. As a reminder for our listeners, we are at the end of day two of our workshop. We already know how to open pull requests, which we call PRs, and we know how GitHub Actions work. So, what is on the agenda for today?

-

Alex: We are going to cover five main areas. First, why security matters so much in open source, specifically supply chain risks. Second, Dependabot, which is your automated dependency assistant. Third, secret scanning, which catches passwords before they leak. Fourth, code scanning using a tool called CodeQL. And finally, private security advisories, which is how you responsibly report a vulnerability if you find one.

-

Jamie: Let us start with that first one. Supply chain risks. When I hear supply chain, I think of cargo ships and grocery stores. What does that mean in software?

-

Alex: It is a great analogy, actually. Think about baking a cake. If you bake a cake, you probably do not mill your own flour, churn your own butter, and extract your own vanilla. You buy those ingredients from different suppliers. If the flour factory has a contamination issue, your cake is contaminated, even if you did everything perfectly in your own kitchen.

-

Jamie: Oh, I see. In software, the ingredients are our dependencies. The libraries and packages we pull into our projects so we do not have to write everything from scratch.

-

Alex: Exactly. Modern software is built on thousands of open source dependencies. If an attacker finds a vulnerability in a popular logging library, and your project uses that library, your project is now vulnerable. This is called a supply chain attack. You are only as secure as your weakest dependency.

-

Jamie: That sounds terrifying. How am I supposed to know if one of the hundred packages I am using has a security flaw? I cannot read all their code every day.

-

Alex: You absolutely cannot, and you should not try. That is exactly where the GitHub Security tab comes in. Every repository has a Security tab. It is your central dashboard for all these features.

-

Jamie: How do we navigate to the Security tab using a screen reader?

-

Alex: If you are on any repository page, you can move to the secondary navigation landmark. From there, you can tab through the links. You will pass Code, Issues, Pull Requests, Actions, Projects, Wiki, and then you will reach the Security link. Press Enter there.

-

Jamie: Is there a keyboard shortcut? I love skipping the tab navigation.

-

Alex: There is. If you turn on your screen reader's focus mode or forms mode, you can press G, and then S. G for go, S for security. That will jump you straight to the Security tab.

-

Jamie: Okay, so I am on the Security tab. What is the first thing I am going to find there to help with those supply chain risks we talked about?

-

Alex: You will find Dependabot. Dependabot is GitHub's automated dependency monitoring system. I like to think of Dependabot as a building inspector who constantly checks the foundation of your house. If it finds a crack, it lets you know. Dependabot does this by issuing what we call Dependabot alerts.

-

Jamie: How does it know there is a crack?

-

Alex: It checks your project's dependencies against a massive database of known vulnerabilities. When a security researcher discovers a flaw in a package, they publish a Common Vulnerability and Exposure report, or CVE. If Dependabot sees that your project uses a version of a package that has a CVE, it creates an alert.

-

Jamie: Are all alerts equally urgent? Because sometimes I feel like I get a lot of them.

-

Alex: They are not. Every alert comes with a severity level based on a CVSS score. That stands for Common Vulnerability Scoring System. It is a scale from zero to ten. Critical alerts are nine to ten. Those mean an exploit is likely and the impact is wide. You need to fix those immediately.

-

Jamie: What about the other levels?

-

Alex: High alerts are seven to eight point nine. You should fix those in your current sprint. Medium alerts are four to six point nine. There is some risk, usually requiring specific conditions to exploit, so you can schedule those fixes. And low alerts are anything under four. The likelihood of an attack is very low, so you can fix them when it is convenient.

-

Jamie: Okay, so Dependabot gives me an alert. Let us say it is a High severity alert for a package called lodash. How do I actually read this alert with my screen reader?

-

Alex: When you navigate to the Dependabot alerts section in the Security tab, the alerts are presented in a table. If you are using NVDA or JAWS, you can press the T key to jump to the table, and then use your up and down arrow keys to navigate the rows. Each row is an alert. When you find the one for lodash, you can tab to the link and press Enter to open the full details.

-

Jamie: What will I find inside the details page?

-

Alex: The page is well structured with headings. You can press the H key to move through the Alert title, the Package details, the Description of the vulnerability, and the References. It will tell you exactly which version of lodash is vulnerable, and more importantly, which version includes the fix.

-

Jamie: So to fix it, I just need to update my package file, commit the change, and open a pull request?

-

Alex: You could do that manually, yes. But Dependabot has a second feature called Dependabot Security Updates. If the repository maintainer has this enabled, Dependabot does not just warn you. It actually opens a pull request for you, automatically updating the dependency to the secure version.

-

Jamie: Wait, so the building inspector does not just point out the crack in the foundation, they actually bring a contractor over with the cement and say, here, just sign this paperwork and we will fix it?

-

Alex: Exactly. Dependabot writes the branch, updates the package file, and opens the PR. All you have to do as a contributor is review the PR, make sure the tests pass, and merge it. Reviewing and merging Dependabot PRs is honestly one of the highest value, lowest risk ways you can contribute to an open source project.

-

Jamie: That is brilliant. Does Dependabot only update packages when there is a security emergency? What if I just want to keep my packages up to date so I do not fall too far behind?

-

Alex: That is the third flavor of Dependabot. It is called Dependabot Version Updates. You can configure Dependabot to routinely check for any new versions of your dependencies, regardless of whether there is a security issue.

-

Jamie: How do I set that up? Do I use the GitHub website interface?

-

Alex: You set it up using a configuration file in your repository. You create a folder called dot github, and inside it, a file called dependabot dot y m l. In that yaml file, you tell Dependabot which package ecosystems to check, like npm for JavaScript or pip for Python, and how often to check, like daily or weekly. Dependabot will then automatically open PRs to keep your project fresh.

-

Jamie: Okay, so Dependabot handles the ingredients we bring into our project. But what about the code we write ourselves? I mentioned earlier that I was terrified of leaking something. When I was first learning to code, I accidentally committed an API key to a public repository. It was a nightmare. I had to scramble to figure out what to do.

-

Alex: You are definitely not the first person to do that, Jamie. We call things like API keys, database passwords, and authentication tokens, secrets. They are the keys to your digital house. If you hardcode a secret into your project and push it to a public GitHub repository, anyone in the world can find it and use it.

-

Jamie: And there are actually bots out there constantly scraping GitHub looking for leaked secrets, right?

-

Alex: Yes. If you push an active Amazon Web Services key to a public repo, attackers can find it and spin up thousands of dollars of servers on your account within minutes. That is why GitHub created Secret Scanning.

-

Jamie: How does Secret Scanning work? Does it read my code after I push it?

-

Alex: It does, but it also does something even better called Push Protection. Push Protection works in real time. When you type git push in your terminal, your code travels to GitHub. Before GitHub accepts the code, it scans it for known patterns of secrets from hundreds of service providers.

-

Jamie: What happens if it finds one?

-

Alex: It literally bounces your push back to you. Your terminal will display an error message saying Push cannot contain secrets. It will tell you the exact commit, the file name, the line number, and what kind of secret it found, like a GitHub Personal Access Token.

-

Jamie: That is like a bouncer at the club checking your pockets, finding your house key, and saying, hey, you cannot bring this inside, you are going to lose it on the dance floor.

-

Alex: That is a perfect analogy. Push Protection stops the leak before it ever happens.

-

Jamie: But what if I am working on an older project, and someone leaked a secret a year ago, before Push Protection was turned on?

-

Alex: That is where Secret Scanning Alerts come in. GitHub continuously scans the entire history of public repositories. If it finds a leaked secret in an old commit, it generates an alert in the Security tab under the Secret scanning section.

-

Jamie: Okay, so let us say I am navigating the Security tab, I open the Secret scanning section, and I find an active alert for a leaked token. What is the proper procedure? Do I just delete the token from the file and make a new commit?

-

Alex: No, and this is a critical point. Deleting the secret from the file is not enough. Remember, Git keeps a history of every change. Even if you remove it from the latest version of the file, the secret still exists in the older commits. Anyone can look at the commit history and find it.

-

Jamie: Oh, right. So the secret is permanently out there. What do I do?

-

Alex: You must revoke and rotate the secret. Revoking means you go to the service provider that issued the secret. Let us say it is a Stripe API key. You log into your Stripe dashboard and you delete or disable that specific key. This makes the leaked key completely useless. Even if an attacker has it, it will not work anymore.

-

Jamie: And rotating?

-

Alex: Rotating just means generating a brand new key to replace the old one, and putting that new key into your secure production environment. Once you have revoked and rotated, you can safely close the alert on GitHub.

-

Jamie: How do I avoid hardcoding secrets in the first place? I need my code to talk to databases and APIs.

-

Alex: The best practice is to use environment variables. Instead of typing the actual password in your code, you write a variable name, like process dot env dot DATABASE PASSWORD. Then, you store the actual password securely on the server where your code runs, completely outside of Git.

-

Jamie: Alright, we have secured our dependencies, and we have made sure we are not leaking passwords. But what if the logic of my code itself has a security flaw? Like, what if I write a function that accidentally allows a hacker to run their own code on my server?

-

Alex: That brings us to our fourth topic, Code Scanning. GitHub uses a technique called static analysis to find vulnerabilities in your code. Static analysis means evaluating the code without actually running it.

-

Jamie: Like a spellchecker, but for security logic?

-

Alex: Exactly. The engine behind GitHub's code scanning is called CodeQL. Q L stands for Query Language. CodeQL essentially treats your codebase like a database. It allows GitHub to write queries that search for common security vulnerabilities, like SQL injection, cross site scripting, or command injection.

-

Jamie: How does it know the difference between a safe piece of code and a dangerous one?

-

Alex: CodeQL is incredibly smart because it understands data flow. It traces how information moves through your program from a source to a sink.

-

Jamie: Source to a sink? Can you explain that?

-

Alex: A source is anywhere your program takes in untrusted data from the outside world. Like a user typing into a search box, or a parameter in a web request. A sink is a dangerous function that executes code or interacts with a database. CodeQL looks for paths where untrusted data travels from a source to a sink without being properly sanitized or checked along the way.

-

Jamie: I love analogies, so let me try one. It is like a water pipe inspector. The source is where the water enters the house. The sink is the drain. The inspector drops green dye into the water at the source, and then walks through the house to see if any green dye leaks out of the pipes before it safely reaches the drain.

-

Alex: That is exactly how data flow analysis works. CodeQL traces the green dye. If the untrusted data hits a dangerous execution function, CodeQL flags it as a vulnerability.

-

Jamie: How are these alerts presented to us? Are they easy to read with a screen reader?

-

Alex: They are excellent for screen reader users. When you navigate to Code scanning in the Security tab, you will find a table of alerts. You can open an alert by pressing Enter. Inside, you can use the H key to jump through the headings. There is a heading called Code flow. Under that, it gives you a step by step list of exactly how the data travels from the source to the sink.

-

Jamie: So it tells me exactly which file and which line number the problem starts on, and where it ends up?

-

Alex: Yes. It will say, step one, user input enters at line twelve. Step two, input is passed to the logger function at line forty seven. It makes fixing the vulnerability much easier because you know exactly where to intercept the bad data. Fixing these alerts is a fantastic way to contribute to open source projects.

-

Jamie: How do we turn CodeQL on? Is it automatic like Dependabot?

-

Alex: You have to set it up, but GitHub makes it very easy. You set it up using a GitHub Action. If you navigate to the Security tab and find the Code scanning section, GitHub will offer to configure CodeQL for you. It will generate a yaml workflow file for GitHub Actions. Once you commit that file, the GitHub Action will automatically run the CodeQL scan every time someone pushes new code or opens a pull request.

-

Jamie: Okay, so we have covered all these automated tools. But what happens if the automated tools miss something, and a human being, like me or one of our listeners, discovers a security vulnerability in an open source project? Do I just go to the Issues tab and open a new issue?

-

Alex: No. Please, never do that. If you find a security vulnerability, never report it as a public issue.

-

Jamie: Why not? I want the maintainers to fix it as fast as possible.

-

Alex: Think about it. A public issue is visible to everyone on the internet immediately. If you write down exactly how to crash a server or bypass a login screen in a public issue, you are handing a recipe to every malicious actor in the world. You are shouting that the back door is unlocked using a megaphone, before the owner has a chance to change the locks.

-

Jamie: Oh. I did not think about that. So how do I tell the maintainer without telling the whole world?

-

Alex: You use a process called responsible disclosure. On GitHub, this is handled through Private Vulnerability Reporting. It allows you to slip a note under the door directly to the security team, without the public ever seeing it.

-

Jamie: How do I find out if a project accepts private reports?

-

Alex: You should always check the project's security policy first. This is a file in the repository called SECURITY dot m d. You can usually find a link to it in the Security tab under the Policies section. The SECURITY dot m d file will tell you exactly how the maintainers want to be contacted. Sometimes they list a specific email address. But increasingly, they use GitHub's private reporting form.

-

Jamie: How do I access the private reporting form?

-

Alex: Navigate to the Security tab. If the maintainers have enabled it, you will find a button that says Report a vulnerability. Press Enter on that button.

-

Jamie: What does the form look like for a screen reader user?

-

Alex: It is a standard web form. You can use your F key or E key to jump between the form fields. First is the Title field, where you provide a short summary. Next is the Description text area. Here you need to be very detailed. Explain exactly how to reproduce the vulnerability, step by step, and what the impact is.

-

Jamie: Are there other fields?

-

Alex: Yes. There is a dropdown menu for Severity, where you can assess if it is low, medium, high, or critical. There is a field to list the affected versions of the software. And there is an optional field to provide a CVSS score if you know how to calculate one. Once you are done, you navigate to the Submit report button and press Enter.

-

Jamie: What happens after I submit it? Do I just wait?

-

Alex: The maintainers will receive a private notification. They will review your report, and they might ask you follow up questions in a private advisory thread. They will develop a fix, test it, and publish a new release of the software. Once the fix is public and users have had time to update, the maintainers will publish a public security advisory, and they will often credit you as the person who discovered it.

-

Jamie: That sounds like a great way to build a reputation in the open source community. But what if the maintainer ignores me? What if I submit a private report and I do not hear back for a month?

-

Alex: The industry standard window for a response is usually thirty to ninety days. If you do not hear back after a reasonable amount of time, you can send a polite follow up in the private thread. If the issue is absolutely critical and the project seems abandoned, you can actually contact GitHub directly, and their security team can assist with coordinated disclosure. But you must give the maintainers a fair chance to fix it first.

-

Jamie: Alex, before we wrap up, I saw a strange acronym in the reading materials for this chapter. S B O M. What is an SBOM?

-

Alex: SBOM stands for Software Bill of Materials. It is a machine readable inventory of every single component, library, and dependency in a software project.

-

Jamie: Like the ingredients list on the side of a cereal box?

-

Alex: Exactly. When enterprise companies or government agencies adopt open source software, they need to know exactly what ingredients are inside to ensure they meet compliance and security standards.

-

Jamie: How do I make an SBOM for my project? Do I have to type out every single dependency manually?

-

Alex: Thankfully, no. GitHub can generate it for you. You navigate to your repository's Insights tab, then move to the Dependency graph section. At the end of the main region, past the graph data, you will find a button called Export SBOM. When you activate that, GitHub generates a standardized JSON file in what is called the SPDX format. It lists all your dependencies, their exact versions, and their open source licenses. It is a very handy feature if you ever work in corporate environments.

-

Jamie: That is so easy. One last question. During this workshop, we are working out of a repository called community-access slash accessibility-agents. Do we have to navigate through the web interface to check its security status?

-

Alex: You do not. As a special feature for our workshop, the Accessibility Agents repository has a custom slash command. You can type slash security-dashboard in any issue or PR comment. A bot will instantly reply with a clean, accessible text summary of the repository's security health. It will list the number of active Dependabot alerts, confirm if there are any secret scanning alerts, tell you when the last CodeQL scan ran, and even list any open Dependabot pull requests that need reviewing.

-

Jamie: Oh, that is clever! I wish I had known that when I started. It puts all the critical information right in front of you without having to dig through multiple tabs and tables. I am definitely going to try running slash security-dashboard on my fork today.

-

Alex: That brings us to the end of our deep dive into GitHub Security Features. Let us summarize the key takeaways. First, security is largely about managing your supply chain. Dependabot is your best friend. It alerts you to vulnerabilities in your dependencies and can even open automated pull requests to fix them.

-

Jamie: Second, never hardcode passwords, API keys, or tokens in your code. Use environment variables. If you do accidentally commit a secret, Push Protection will try to block it. If a secret does leak, remember that deleting it is not enough. You must revoke the key at the source and rotate it to a new one.

-

Alex: Third, use Code scanning with CodeQL to automatically catch logic flaws and vulnerabilities in your own code before they are merged. It traces untrusted data from the source to the sink.

-

Jamie: And finally, if you discover a vulnerability in an open source project, be a good citizen. Never open a public issue. Check the project's SECURITY dot m d file and use the Private Vulnerability Reporting form to disclose it responsibly.

-

Alex: Perfectly summarized. In our next episode, episode thirty, we are going to shift gears and talk about GitHub Pages. We will learn how to take a repository and turn it into a live, accessible website hosted directly on GitHub for free. You will not want to miss it. Until then, keep practicing, and we will talk to you soon.

-
- - -

Episode 30: VS Code Accessibility Reference

-

Complete accessibility settings, audio signals, diff viewer, and screen reader configs.

-

Based on: Appendix M: VS Code Accessibility Reference

- - -

Download Episode 30 (MP3)

-
-Read Transcript - Episode 30: VS Code Accessibility Reference - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub, the podcast where we make version control and open source collaboration accessible to everyone. I am Alex, and I am thrilled to be here with you today.

-

Jamie: And I am Jamie! I am so excited for this one. We are on episode thirty! Episode thirty, Alex. That feels like a massive milestone.

-

Alex: It really is. Today's episode is titled VS Code Accessibility Reference. If you have been following along with our two-day workshop material, you already know the basics of the VS Code interface from our earlier episodes. But today, we are going deep. We are handing you the complete manual.

-

Jamie: I love that. When I was learning GitHub about two years ago, I knew enough to get by. I knew how to open a file and type. But I did not understand how to make the editor actually work for me. I was just fighting the default settings every single day.

-

Alex: Exactly. And you should not have to fight your tools. Today, we are going to cover every accessibility-related setting in VS Code. We will talk about audio cues, the accessible diff viewer, terminal accessibility, and specific configurations for NVDA, JAWS, and VoiceOver. We will even cover troubleshooting when things go wrong.

-

Jamie: Just a quick reminder for our listeners. If you are joining us for the first time, you might want to review our previous episode on VS Code Setup and Accessibility Basics. That will give you the lay of the land. But if you are ready to dive into the deep end of the settings pool, stick right here.

-

Alex: Let us jump right in.

-

Alex: Everything in VS Code accessibility starts with one master switch. It is a setting called editor dot accessibility support.

-

Jamie: The big breaker switch for the house!

-

Alex: That is a perfect analogy. Just like the main breaker controls the power to your entire house, the editor dot accessibility support setting controls whether VS Code optimizes its interface for a screen reader. By default, this is set to auto. That means VS Code tries to detect if NVDA, JAWS, or VoiceOver is running when it starts up.

-

Jamie: But auto can sometimes fail, right? I remember times when my screen reader updated, or I started VS Code before my screen reader was fully running, and VS Code just acted like it had no idea I needed accessibility features.

-

Alex: Exactly. That is why I always recommend changing this setting from auto to on. When you force it to on, VS Code will always provide screen reader optimizations, no matter what.

-

Jamie: What actually happens when that switch is flipped on? What are the screen reader mode behavior changes?

-

Alex: A few critical things happen behind the scenes. First, it disables the visual minimap. The minimap is a zoomed-out visual outline of your code that sighted developers use to scroll quickly. For a screen reader, it is just useless noise that eats up computer memory. So, screen reader mode turns it off. It also changes how word wrap behaves, ensuring that when your screen reader reads a line of code, it reads the whole logical line, not just what visually fits on the screen.

-

Jamie: That is so important. If word wrap is handled visually, your screen reader might pause awkwardly in the middle of a variable name just because the window was resized.

-

Alex: Right. And while we are talking about customizing the interface, I want to mention high contrast themes and zoom levels. Even if you rely entirely on a screen reader, or if you are a low-vision developer who uses a combination of screen reading and visual tracking, these are essential.

-

Jamie: Oh, absolutely. I have low vision, and before I transitioned to using a screen reader full time, I relied heavily on high contrast. VS Code has built-in high contrast themes. You do not have to download anything extra.

-

Alex: Yes, you can open the Command Palette by pressing Control plus Shift plus P on Windows, or Command plus Shift plus P on Mac. Then type Preferences Color Theme. You can navigate through the list, and there are specific themes labeled High Contrast Dark and High Contrast Light. These themes add solid borders around panels and increase text contrast significantly.

-

Jamie: And for zoom, you can just press Control plus the Equals sign to zoom in, and Control plus the Dash key to zoom out. Or Command on a Mac. It scales the entire interface, not just the text in the editor. The sidebar, the terminal, the menus, everything gets bigger.

-

Alex: It is a huge help. Now, let us move from the visual to the audible. I want to talk about how VS Code communicates with you non-verbally.

-

Alex: Let us talk about Audio Cues. VS Code has a brilliant system of sounds that play when certain things happen.

-

Jamie: I am obsessed with the audio cues. They completely changed how fast I can write code. When I first started, I had to arrow through every single character of a line to figure out if I made a typo. Now, VS Code just plays a tiny little error chord when my cursor lands on a broken line.

-

Alex: That is the perfect way to explain it. Think of audio cues like the dashboard warning lights in your car, but for your ears. Instead of your screen reader verbosely announcing Error on line forty two every single time you arrow past it, you just hear a subtle, quick sound.

-

Jamie: What kind of sounds are we talking about?

-

Alex: There are dozens of them. They are controlled by settings that start with accessibility dot signals. For example, accessibility dot signals dot line has error. There is a sound for when a terminal task completes successfully, a different sound for when a task fails, and sounds for when you hit a breakpoint in a debugger.

-

Jamie: My favorite is the sound for folded code. Sometimes I am navigating a huge file, and I do not realize someone collapsed a massive function. The audio cue lets me know there is hidden code under my cursor.

-

Alex: You can configure these cues to be on, off, or auto. Auto means they only play if screen reader mode is active. You can find all of these by opening your Settings with Control plus Comma, or Command plus Comma, and searching for audio cue.

-

Jamie: But what if I want the editor to actually speak to me instead of just playing a chime? Like, a chime is great for an error, but what if I need to know exactly what the error is?

-

Alex: That brings us to Accessibility Announcements. If audio cues are your dashboard warning lights, accessibility announcements are your GPS voice navigation. They give you the specific text details.

-

Jamie: How do we control those? Because sometimes VS Code talks way too much.

-

Alex: It really can. The announcements are controlled by settings that start with accessibility dot verbosity. You can set the verbosity for different parts of the editor. For example, accessibility dot verbosity dot hover controls whether your screen reader automatically reads the pop-up information when your cursor lands on a function.

-

Jamie: Oh, I always turn that off. Or at least to minimal. If I am just arrowing through my code quickly, I do not want the screen reader to suddenly start reading a massive paragraph of documentation just because my cursor paused for half a second.

-

Alex: Exactly. You can set these verbosity settings to verbose, minimal, or off. If you set hover verbosity to off, you can still read that documentation whenever you want. You just press Alt plus F2, or Option plus F2 on Mac. That shortcut opens the Accessible View, which takes whatever visual pop-up is on the screen and puts it into a nice, plain text window that you can navigate at your own pace.

-

Jamie: Alt plus F2 is a lifesaver. I use it for reading long error messages, hover documentation, and even Copilot suggestions.

-

Alex: Speaking of navigating complex information, we need to talk about the Accessible Diff Viewer. This is arguably the most important feature we will cover today.

-

Jamie: Yes! A diff, short for difference, is how Git shows you what changed in a file. It compares the old version to the new version. But visually, diffs are usually displayed side-by-side. The old file is on the left, the new file is on the right, and the changes are highlighted in red and green.

-

Alex: Which is an absolute nightmare for a screen reader. If you try to navigate a visual side-by-side diff with a screen reader, you will just hear a jumbled mess of old code and new code mashed together.

-

Jamie: So how does the Accessible Diff Viewer fix this?

-

Alex: It completely restructures the information. Instead of two columns, it presents the changes as a single, vertical list. To access it, when you are in a diff view, you just press F7.

-

Jamie: F7. Got it. And what exactly does it show me?

-

Alex: It breaks the file down into what are called hunks. A hunk is just a block of related changes. Let us use an analogy. Imagine you are updating a recipe for chocolate chip cookies. You decide to change the amount of sugar, and you also add a step at the very end to sprinkle sea salt on top.

-

Jamie: Sounds delicious.

-

Alex: Right? In a visual diff, you would have to scan the whole recipe to find those two changes. But the Accessible Diff Viewer just gives you the hunks. Hunk one shows the sugar change. Hunk two shows the sea salt addition. It skips all the unchanged steps in the middle.

-

Jamie: That saves so much time. How does it tell me what was added or removed within that hunk?

-

Alex: It prefixes every line. If a line was removed, it announces Removed, or reads a minus sign before the line. If a line was added, it announces Added, or reads a plus sign. It also includes about three lines of unchanged code before and after the change, just to give you context. It will prefix those with Unchanged.

-

Jamie: So if I changed the sugar from one cup to two cups, it would say something like: Unchanged: butter. Removed: one cup sugar. Added: two cups sugar. Unchanged: vanilla extract.

-

Alex: Exactly like that. And you can jump forward to the next hunk by pressing F7 again, or jump backward by pressing Shift plus F7. It is incredibly efficient.

-

Alex: Let us transition to the command line. We need to talk about Terminal accessibility. The integrated terminal in VS Code is where you will run your Git commands, start your servers, and run your tests.

-

Jamie: The terminal used to be a really frustrating place for screen reader users. It is essentially a live feed of text that is constantly updating.

-

Alex: It was. But VS Code has made massive improvements. There is a setting called terminal dot integrated dot screen reader mode. Just like the editor, you should ensure this is turned on. When it is on, VS Code intercepts the raw terminal output and formats it so your screen reader can navigate it line by line using your standard arrow keys.

-

Jamie: One of my favorite settings in the terminal is the terminal bell. It is terminal dot integrated dot enable bell.

-

Alex: Yes, explain how you use that.

-

Jamie: So, if I run a really long command, like installing a bunch of packages for a project, I do not want to just sit there listening to my screen reader read out hundreds of lines of installation logs. I want to go check my email. When you enable the terminal bell, it is like the ding of a microwave. When the command finishes, it plays a sound. You know exactly when to switch back to VS Code.

-

Alex: That is a fantastic productivity tip. And if you ever need to read the output of a command that scrolled way off the screen, you can use that same Alt plus F2 shortcut we mentioned earlier. If your focus is in the terminal, Alt plus F2 opens the Terminal Accessible View, which puts the entire terminal history into a static text editor so you can search it, copy from it, and read it at your own pace.

-

Alex: Now we need to get into the weeds a bit. We are going to cover Screen reader-specific configurations. VS Code behaves slightly differently depending on whether you are using NVDA, JAWS, or VoiceOver. Let us start with NVDA on Windows.

-

Jamie: I use NVDA. When I first started, I had this weird issue where I would be reading a really long line of code, and suddenly NVDA would just stop reading in the middle of it.

-

Alex: That is a very common issue, and it has to do with an NVDA setting, not a VS Code setting. By default, NVDA limits how much text it will read on a single line in Browse Mode. To fix this, you need to open your NVDA Preferences, go to Settings, then Browse Mode. Look for the setting called Maximum length of text on a single line.

-

Jamie: And what should I change it to?

-

Alex: Change it to ten thousand. That ensures NVDA will read the entire line of code, no matter how long the variable names or string text might be. Also in those NVDA settings, you should check the box for Automatic focus mode for focus changes, and uncheck Automatic focus mode for caret movement.

-

Jamie: Why do we do that?

-

Alex: Because VS Code is essentially a complex web application running on your desktop. You want NVDA to automatically switch into focus mode when you open a menu or a dialog box, so you can interact with it. But when you are just moving your text cursor, your caret, around the editor, you do not want it constantly flipping modes.

-

Jamie: That makes perfect sense. What about JAWS?

-

Alex: For JAWS users, the setup is similar. You want to go into the JAWS Settings Center, under HTML, PDF, Accessibility. Make sure Auto Forms Mode is checked.

-

Jamie: Is there anything specific for reading code with JAWS?

-

Alex: Yes. Under Text Processing in JAWS, there is a setting for Blank Line Announcement. By default, JAWS says the word blank every time you arrow over an empty line. In code, there are a lot of blank lines used for formatting. Hearing the word blank fifty times a day gets exhausting. You can change that setting from Speech to Tone. Then, JAWS will just play a tiny click sound when you hit a blank line.

-

Jamie: Oh, I love that. Less talking, more coding. And what about our Mac users on VoiceOver?

-

Alex: VoiceOver requires a very specific tweak. You need to open the VoiceOver Utility, go to Navigation, and pay attention to Quick Nav. Quick Nav is a feature that lets you navigate web pages by pressing single letter keys. For example, pressing H jumps to the next heading.

-

Jamie: But in a code editor, if I press the letter H, I probably just want to type the letter H!

-

Alex: Exactly! If Quick Nav is on while you are in the VS Code editor, you will not be able to type normally. You must ensure Quick Nav is toggled OFF when your focus is in the editor. You can toggle it quickly by pressing the Left and Right arrow keys at the same time.

-

Jamie: And what about punctuation? Code is just a giant pile of punctuation.

-

Alex: Right. In VoiceOver Utility, under Verbosity, then Text, you should set Punctuation to All. You need to hear every bracket, every semicolon, and every parenthesis. If VoiceOver filters them out to make it sound more like natural English, your code will just not make any sense.

-

Alex: Let us talk about moving around. Keyboard-only navigation is the lifeblood of using VS Code with a screen reader.

-

Jamie: There are so many shortcuts, but you really only need a handful to get started, right?

-

Alex: Exactly. You do not need to memorize the entire dictionary. The most important shortcut, the one that rules them all, is the Command Palette. We mentioned it earlier: Control plus Shift plus P, or Command plus Shift plus P.

-

Jamie: If you forget every other shortcut, remember that one. Because you can just type what you want to do. If you want to open a new terminal, just open the Command Palette and type terminal. If you want to format your code, type format.

-

Alex: Beyond the Command Palette, you need to know how to navigate between the different parts of the window. VS Code has the main editor area where you type, but it also has a sidebar on the left and a panel on the bottom.

-

Jamie: The sidebar is where your file explorer is, right? Where you see all the files in your project.

-

Alex: Yes. To jump to the File Explorer in the sidebar, press Control plus Shift plus E. Or Command plus Shift plus E on Mac. To jump to the Source Control view, where you manage your Git commits, press Control plus Shift plus G.

-

Jamie: And the panel on the bottom is where the terminal lives.

-

Alex: Correct. You can toggle that bottom panel open and closed by pressing Control plus the Backtick key. The backtick is that little key usually right above the Tab key on your keyboard.

-

Jamie: What about moving between open files? If I have five files open, how do I switch between them without getting lost?

-

Alex: You use Control plus Tab. It works just like switching tabs in a web browser. If you hold down Control and press Tab repeatedly, it will cycle through all your open files. When you hear the name of the file you want, just let go of the keys, and your focus will be right there.

-

Jamie: One shortcut I use constantly is Control plus G. Go to line. When I run a test and it says there is an error on line one hundred and fifty, I just press Control plus G, type one five zero, hit Enter, and boom. I am exactly where I need to be.

-

Alex: Let us wrap up with a crucial topic: Troubleshooting accessibility issues. Because no matter how perfectly you set things up, eventually, something will get stuck.

-

Jamie: Oh, the dreaded silent editor. When you press an arrow key and your screen reader just says nothing. It is terrifying. You feel like you broke everything.

-

Alex: It happens to everyone. Usually, what has happened is that your system focus has gotten trapped inside a webview or a custom UI element that does not know how to report its state to the screen reader.

-

Jamie: How do we fix it? Do I have to restart my whole computer?

-

Alex: No, thankfully. The first thing to try is simply pressing the Escape key a few times. Sometimes a hidden menu is open and stealing focus. If that does not work, try pressing F6. F6 is the shortcut to cycle focus between the main parts of the VS Code window: the editor, the panel, the sidebar, and the activity bar. Often, pressing F6 forces the focus out of whatever trap it was in.

-

Jamie: And if it is completely frozen?

-

Alex: Then you use the Developer Reload Window command. Open the Command Palette with Control plus Shift plus P, and type Reload Window. Hit Enter. This refreshes the entire VS Code interface without actually closing the application or losing your unsaved work. It takes about two seconds and almost always fixes screen reader sync issues.

-

Jamie: Another issue I have run into is the Tab key getting trapped. I will be in the terminal, and I press Tab to autocomplete a file name, but instead, it moves my focus to a completely different button on the screen.

-

Alex: That is a feature called Tab Trapping. Sometimes it gets toggled on by accident. If your Tab key stops inserting tabs or autocompleting, press Control plus M. That is Command plus M on Mac. That toggles whether the Tab key moves focus between interface elements, or acts like a normal Tab key inside text areas.

-

Alex: We have covered a massive amount of ground today. Jamie, what are your top takeaways for our listeners?

-

Jamie: First, definitely make sure editor dot accessibility support is set to On, not auto. Do not leave it up to chance. Second, configure your screen reader properly! Change that NVDA line length to ten thousand, or turn off Quick Nav in VoiceOver. Your editor can only do so much if your screen reader is fighting it.

-

Alex: Excellent points. I will add a third: Embrace the Accessible Diff Viewer. Press F7 when you are reviewing code changes. Stop trying to read visual side-by-side diffs with a screen reader. And finally, use Alt plus F2 to open the Accessible View anytime you need to read a hover message, an error, or terminal output clearly.

-

Jamie: This really is the ultimate reference guide. I wish I had this episode two years ago.

-

Alex: All of the settings, JSON configurations, and shortcuts we discussed today are available in Appendix M of your workshop materials. You do not have to memorize them from this audio; they are all written down for you to copy and paste.

-

Jamie: What are we covering next time?

-

Alex: In our next episode, we are moving from editor configuration to pure magic. We are going to tackle GitHub Copilot. We will explain how to use artificial intelligence to write code, and most importantly, how to navigate and review AI suggestions accessibly using your screen reader.

-

Jamie: Oh, that is going to be incredible. Copilot is a game changer. I cannot wait.

-

Alex: Until then, keep exploring your settings, customize your audio cues, and we will see you next time on Gitt Going with GitHub.

-
- - -

Episode 31: GitHub Codespaces

-

Cloud dev environments, accessibility setup, and screen reader usage.

-

Based on: Appendix N: GitHub Codespaces

- - -

Download Episode 31 (MP3)

-
-Read Transcript - Episode 31: GitHub Codespaces - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode 31, GitHub Codespaces. I am Alex, and I am so glad you are joining us today as we continue our journey through accessible development and open source collaboration.

-

Jamie: And I am Jamie. I am a developer who learned GitHub about two years ago, and I am here to ask all the questions that you are probably thinking right now. I remember exactly what it felt like to be overwhelmed by all this terminology, so we are going to break it down together.

-

Alex: Today we are diving into a feature that completely changed how I teach development, and honestly, how I write code myself. We are talking about GitHub Codespaces. Before we jump in, let us quickly remind ourselves of our prerequisites. In our previous episodes, we covered the basic layout of Visual Studio Code, or VS Code, and we talked about fundamental Git commands like commit and push. You will be using all of that today.

-

Jamie: Okay, so GitHub Codespaces. I hear this term thrown around a lot in workshops and open source projects. What exactly is a Codespace? Because when I first heard the word, I thought it was some kind of social network for developers.

-

Alex: That would be interesting, but no. A Codespace is a cloud hosted development environment. Let us define that. A development environment is everything you need to write, run, and test your code. It is your code editor, your programming languages, your debugging tools, all of it. Historically, you had to install all of this directly onto your own computer.

-

Jamie: Right, and I have nightmares about that from when I was learning. I remember spending three days just trying to get Python, Node, and Ruby installed on my computer. I kept messing up my system paths, my screen reader was reading me endless error messages in the terminal, and I had not even written a single line of code yet. It was incredibly frustrating.

-

Alex: That is exactly the problem Codespaces solves. When we say it is cloud hosted, we mean GitHub creates a virtual machine, which is basically a computer running in a massive data center somewhere, and they set up all those tools for you. Then, they connect your code editor to that remote computer over the internet.

-

Jamie: So I love a good analogy. Is it kind of like renting a fully furnished workshop?

-

Alex: That is a perfect analogy. Imagine you want to build a table. You could spend weeks buying a saw, a drill, a workbench, and clearing out space in your garage. That is local development. Or, you could just rent a workshop that already has all the tools laid out on the bench, perfectly tuned and ready to go. You just walk in and start building. That is a Codespace.

-

Jamie: That sounds amazing. And because it is in the cloud, does that mean I do not need a super powerful computer to use it?

-

Alex: Exactly. This is one of the biggest benefits, especially for accessibility and inclusion. We call this developing on low end devices. Because the heavy lifting, the compiling, the running of the code, is all happening on GitHub servers, your computer is just acting as the display and keyboard. You could run a massive, complex project on an old, inexpensive laptop. You can even run Codespaces on mobile devices.

-

Jamie: Wait, really? Like an iPad or a smartphone?

-

Alex: Yes. If you pair a Bluetooth keyboard with a tablet, you can open a Codespace in your mobile web browser and have a full desktop class coding environment. The screen reader on your tablet will interact with the web interface. It is incredibly freeing to know you are not chained to a high end machine.

-

Jamie: Okay, I am sold on the concept. How do I actually create one? Let us say I am on a repository page on GitHub.

-

Alex: The process is very straightforward, but it requires navigating a few specific buttons. When you are on the main page of a repository, you want to navigate to the Code button. There is no direct keyboard shortcut to jump exactly to this button, so you will typically use your screen reader to navigate by buttons, or simply press Tab until you reach it.

-

Jamie: Got it. So I press Enter or Space to activate the Code button. What happens next?

-

Alex: A panel opens up. Inside this panel, there are usually two tabs. One is called Local, which is for cloning the code to your own computer. The other is called Codespaces. You want to use your arrow keys to select the Codespaces tab. Once you are in that tab, you will find a button called Create codespace on main. Main being the name of the default branch.

-

Jamie: Okay, I activate that button. What is the startup experience like? Because you said it is setting up a whole computer for me. That cannot be instant, right?

-

Alex: You are correct, it is not instant. When you activate that button, a new browser tab opens. This is where the provisioning happens. Provisioning is just a technical term for allocating the computer and getting it ready.

-

Jamie: What is happening behind the scenes during that time?

-

Alex: A few things. First, GitHub finds an available virtual machine. Next, it clones the repository you were just looking at directly into that machine. Then, it installs any tools that the project specifically requested. Finally, it starts up the VS Code interface. This whole process usually takes between thirty and ninety seconds.

-

Jamie: Ninety seconds to set up a whole environment? I will take that over three days of installing Python any day. While it is loading, does my screen reader tell me what is happening?

-

Alex: It does. The page has live regions that announce the progress, like connecting, or setting up environment. Once it finishes, focus automatically shifts into the VS Code editor.

-

Jamie: You mentioned a moment ago that GitHub installs the tools the project specifically requested. How does GitHub know what tools the project needs?

-

Alex: That is a brilliant question. This brings us to a concept called the dev container. The word dev is short for development. When you start a Codespace, GitHub looks inside your repository for a specific file. It looks in a folder called dot dev container, and inside that folder, it looks for a file called dev container dot json.

-

Jamie: Let me guess, json stands for JavaScript Object Notation, which is just a way of formatting data.

-

Alex: Exactly. The dev container dot json file is essentially the blueprint for your workshop. It is a text file that tells GitHub exactly how to build the environment.

-

Jamie: Can you give me an example of what goes into that blueprint?

-

Alex: Sure. Let us say you are working on a web project that needs a specific version of Node JS, and you want all the developers on your team to use an accessibility linting extension to catch errors. You write those requirements into the dev container dot json file. When anyone on your team creates a Codespace, GitHub reads that file, installs that exact version of Node, and pre installs the accessibility extension.

-

Jamie: Oh, that is clever! So it eliminates that classic developer excuse of, well, it works on my machine.

-

Alex: Precisely. It works exactly the same on everyone's machine, because everyone is using the exact same blueprint. This is especially amazing for workshops. As an instructor, I know that every single student has the exact same setup. Nobody is falling behind because their local environment is broken.

-

Jamie: Okay, so the Codespace has loaded. I am sitting in a browser tab. What does it actually look and feel like to my screen reader? Is it a stripped down version of VS Code?

-

Alex: Not at all. It is the full VS Code interface, running directly in your browser. It works in Chrome, Edge, Firefox, and Safari. For screen reader users, Chrome and Edge tend to offer the most consistent behavior with NVDA and JAWS.

-

Jamie: I remember the first time I used VS Code in the browser, I was worried my screen reader commands would conflict with the browser commands. How does accessibility in Codespaces work?

-

Alex: That is a very common concern. The great news is that VS Code is highly optimized for this. When VS Code in the browser detects a screen reader, it automatically activates a feature called Screen Reader Optimized Mode.

-

Jamie: What does that mode actually do?

-

Alex: It makes several crucial changes under the hood. For example, normally, a code editor might present text in a way that forces your screen reader to read character by character, which is incredibly tedious. Screen Reader Optimized Mode ensures the editor content is presented as a proper text area, allowing you to read line by line seamlessly. It also changes how things like code suggestions and differences between files are announced, making them much more friendly for audio output.

-

Jamie: What if it does not detect my screen reader automatically? Can I turn it on myself?

-

Alex: Yes, absolutely. You can use the Command Palette. We talked about this in a previous episode. You press Control plus Shift plus P. This opens a search field. You just type the word Toggle, and then the words Screen Reader Accessibility Mode. Press Enter, and it will turn on manually.

-

Jamie: Control plus Shift plus P. I use that shortcut probably fifty times a day. Okay, what about audio cues? I rely heavily on those little sounds VS Code makes when I hit an error or a breakpoint. Do those work in the browser?

-

Alex: They do. VS Code in Codespaces supports the exact same audio cues as the desktop version. You will hear a specific tone if your cursor lands on a line with an error, a different tone for a warning, and a little chime when a background task completes. The only catch is that sometimes modern web browsers mute audio for new tabs by default. If you are not hearing the cues, you might need to check your browser permissions and ensure that github dot com is allowed to play sound.

-

Jamie: Let us talk about the terminal. The terminal is where I run my commands, and it can be notoriously tricky with screen readers. How does the integrated terminal work in a Codespace?

-

Alex: It is a standard terminal, but navigating it requires a bit of technique. When you press Control plus grave accent to open the terminal, your focus moves into the terminal input area. The grave accent is the key usually located just above the Tab key on an American keyboard.

-

Jamie: Right. And when I type a command, like running a test script, a bunch of text usually flies up the screen. How do I read that?

-

Alex: This is where you need to understand your screen reader modes. If you are using NVDA or JAWS, your screen reader has two main modes. Focus Mode, which passes your keystrokes directly to the application so you can type, and Browse Mode, or Virtual Cursor in JAWS, which intercepts your keystrokes so you can read the screen like a document.

-

Jamie: So when I am typing the command, I need to be in Focus Mode.

-

Alex: Correct. But once the output arrives, you need to manually switch to Browse Mode. For NVDA, you press Insert plus Space. For JAWS, you press Insert plus Z. Once in Browse Mode, you can use your standard arrow keys to read the terminal output line by line. When you are ready to type your next command, you switch back to Focus Mode.

-

Jamie: I wish I had known that when I started. I used to just arrow up and down in Focus Mode and it would just cycle through my previous commands instead of reading the output.

-

Alex: That is a very common mistake! But VS Code also offers another brilliant feature called Accessible View. If you are in the terminal and you want to review the output without messing with screen reader modes, you can press Alt plus F2.

-

Jamie: Alt plus F2. What does that do?

-

Alex: It takes the entire output of the terminal and opens it in a temporary text editor buffer. You can read it, search through it, and navigate it exactly like you would a normal code file. When you are done reading, you just press Escape, and you are right back in the terminal input.

-

Jamie: Oh, that is huge. Alt plus F2. I am writing that down.

-

Alex: Now, we have been talking about using Codespaces in the web browser. But you do not actually have to use the browser. You can connect to a cloud Codespace using your local installation of VS Code on your computer.

-

Jamie: Wait, really? Why would I do that if the browser version works so well?

-

Alex: A few reasons. First, muscle memory. You might have your local screen reader settings, your keyboard shortcuts, and your operating system commands dialed in perfectly. Second, some VS Code extensions are not compatible with the web browser version. They require a native desktop environment to run.

-

Jamie: Okay, that makes sense. How do I connect my local VS Code to the cloud Codespace?

-

Alex: You need to install an extension in your local VS Code called GitHub Codespaces. Once that is installed, you open your Command Palette with Control plus Shift plus P. You search for the command Codespaces colon Connect to Codespace. It will ask you to sign into GitHub if you haven't already, and then it will show you a list of your running Codespaces. You pick one, and your local VS Code window refreshes.

-

Jamie: And at that point, I am typing in my local app, but the files are in the cloud?

-

Alex: Exactly. Your screen reader is interacting with your local desktop application, which is usually faster and more responsive, but all the heavy lifting, the terminal commands, the file saving, is happening on the GitHub server. It is the best of both worlds.

-

Jamie: Let us shift gears to something that always confused me. When I am developing locally, and I write a simple website, I usually run a command to start a local web server. Then I go to my browser and type local host colon three thousand to preview my site. But if my code is running on a cloud server in a Codespace, how do I preview my website?

-

Alex: That is a fantastic question, and it brings us to a concept called port forwarding.

-

Jamie: Port forwarding. Okay, define that for me.

-

Alex: Let us use an analogy. Imagine your Codespace is a secure vault on an island. Inside the vault, your website is running on a specific port, say, port three thousand. But you are on the mainland. You cannot just walk in. Port forwarding creates a secure, temporary tunnel from the vault on the island directly to your local computer.

-

Jamie: So it forwards the traffic from the cloud to me. How do I set up this tunnel? Does it require complex network configurations?

-

Alex: Thankfully, no. VS Code handles it automatically. When you run your web server command in the Codespace terminal, VS Code detects that a server has started. It automatically creates the secure tunnel. You will usually hear a notification from your screen reader saying a port has been forwarded.

-

Jamie: And how do I actually open the website to test it?

-

Alex: When the notification pops up, it usually includes a button to Open in Browser. If you miss the notification, which is easy to do, you can open the Command Palette with Control plus Shift plus P, and search for the command Ports colon Focus on Ports View. This opens a panel listing all your forwarded ports, and you can simply press Enter on the one you want to open. GitHub assigns it a unique, secure URL that only you can access.

-

Jamie: Okay, this all sounds incredibly powerful, which leads me to my next logical question. How much does this cost? Because renting a cloud computer cannot be free forever.

-

Alex: You are right, but GitHub provides a very generous free tier for personal accounts. Every month, you get a certain allowance of free compute hours and storage. For most workshop participants and open source contributors doing casual development, you will comfortably stay within this free usage limit.

-

Jamie: What happens if I forget to close my Codespace? Will it just run forever and drain my free hours?

-

Alex: No, they have thought of that. By default, if you are inactive for thirty minutes, meaning you have not typed anything or run any commands, the Codespace will automatically stop itself.

-

Jamie: What is the difference between stopping a Codespace and deleting a Codespace?

-

Alex: Think of stopping a Codespace like pressing pause on a movie, or putting your laptop to sleep. The virtual machine shuts down, and you stop using compute hours. However, your files, your uncommitted changes, and your terminal history are all saved on a hard drive. You are still using a tiny amount of your storage allowance, but the computer is off.

-

Jamie: And deleting it?

-

Alex: Deleting it is throwing the computer in the trash. The virtual machine is destroyed, and the storage is wiped clean. If you have uncommitted changes or code you haven't pushed to GitHub, it is gone forever.

-

Jamie: Okay, note to self. Always commit and push my work before deleting a Codespace. How do I manually manage these states? Let us say I am done for the day and I want to stop it manually.

-

Alex: You navigate to github dot com slash codespaces. This is your dashboard. It displays a list of all your active and stopped Codespaces. You can use your screen reader to navigate through the list. Next to each Codespace, there is an options menu, often labeled with an ellipsis, or simply announced as an action menu. If you activate that menu, you will find options to Stop codespace, or Delete.

-

Jamie: And if I want to resume one that is stopped?

-

Alex: From that same dashboard, you just navigate to the stopped Codespace and activate the button that says Open in. It will spin up the machine again, and in a few seconds, you are right back where you left off.

-

Jamie: Before we wrap up, I have seen another feature called GitHub dot dev. You just press the period key on any repository and a browser editor opens. Is that the same thing as a Codespace?

-

Alex: That is a great clarification. No, they are different. GitHub dot dev is a lightweight editor. When you press the period key, it opens VS Code in your browser, but it does not create a virtual machine. There is no compute power behind it.

-

Jamie: So what does that mean in practice?

-

Alex: It means you cannot run code. There is no terminal. You cannot run a local web server, and you cannot run tests. It is entirely powered by your browser.

-

Jamie: When would I use GitHub dot dev instead of a Codespace?

-

Alex: GitHub dot dev is perfect for quick edits. If you spot a typo in a documentation file, or you want to read through the code of a project without waiting ninety seconds for a Codespace to provision, you press the period key. It opens instantly. You make your text edit, commit, and you are done. Plus, GitHub dot dev is completely free and unlimited.

-

Jamie: Got it. So GitHub dot dev is for quick edits and reading, and Codespaces is for serious development where I need a terminal and a running environment.

-

Alex: Exactly.

-

Alex: We have covered a massive amount of ground today. Let us recap our key takeaways. First, a Codespace is a cloud hosted virtual machine running VS Code, giving you a full, pre configured development environment without installing anything locally.

-

Jamie: Second, the environment is defined by a blueprint called dev container dot json, which ensures everyone working on the project has the exact same tools and extensions. No more dependency nightmares!

-

Alex: Third, accessibility is built in. You can use Codespaces in your browser with Screen Reader Optimized Mode, or you can connect your local desktop VS Code directly to the cloud machine for maximum familiarity.

-

Jamie: And finally, port forwarding acts as a secure tunnel, letting you preview web apps running in the cloud right on your local machine. Just remember to commit and push your work before you delete your Codespace from the dashboard.

-

Alex: Perfect summary. In our next episode, we are going to dive into branching strategies. We will talk about how multiple people can work on the exact same files at the exact same time without overwriting each other's work. It is where the true magic of Git collaboration happens.

-

Jamie: I cannot wait for that one. Thank you all for listening, and we will catch you in the next episode!

-
- - -

Episode 32: GitHub Mobile

-

VoiceOver and TalkBack guide for iOS and Android GitHub apps.

-

Based on: Appendix O: GitHub Mobile

- - -

Download Episode 32 (MP3)

-
-Read Transcript - Episode 32: GitHub Mobile - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is Episode 32, called GitHub Mobile. I am Alex, and I am so glad you are joining us today.

-

Jamie: And I am Jamie! If you have been following along with our two-day workshop series, you have already learned how to navigate repositories, open issues, and manage pull requests using the desktop website and VS Code. But today, we are taking GitHub on the go.

-

Alex: Exactly. Before we dive in, let us do a quick refresher on our prerequisites. We will be talking a lot about issues and pull requests today. As a reminder, an issue is essentially a tracking ticket for a bug you need to fix or a new feature you want to build. And a pull request, which is my favorite term because you are literally requesting that someone pull your code changes into their project, is how you propose updates to a repository.

-

Jamie: If you are comfortable with those concepts, you are perfectly ready for this episode. And I have to say, Alex, I am really excited about this one. When I first learned GitHub about two years ago, I thought I was chained to my computer. If someone asked me to review their code, I felt like I had to drop everything, run home, and open my laptop.

-

Alex: That is a very common feeling. And that is exactly why GitHub Mobile exists. We are going to cover what the app offers, how to install it on iOS and Android, and how to navigate it using VoiceOver and TalkBack. We will talk through viewing notifications, reading issues, reviewing pull requests, and browsing code. Finally, we will discuss some current accessibility limitations and when it makes sense to use mobile versus your desktop.

-

Alex: Let us start with what GitHub Mobile actually is. It is an official app available for both iOS and Android devices. You can download it by opening the App Store on your iPhone or iPad, or the Google Play Store on your Android device, and searching for GitHub.

-

Jamie: And just to be clear, because this confused me at first, GitHub Mobile is not a code editor. You are not going to be typing out hundreds of lines of Python or JavaScript on your phone screen.

-

Alex: That is a great point. Think of GitHub Mobile like a walkie-talkie and a clipboard for your project, rather than your actual drafting table. It is designed for communication, project management, and review. The core features are triaging notifications, reading and replying to issues, reviewing pull requests, and doing some light code browsing.

-

Jamie: Triaging notifications is my absolute favorite part. Triage just means sorting things by priority, figuring out what needs your attention right now versus what can wait.

-

Alex: Yes, and after you install the app and sign in with your GitHub account, the app will prompt you to enable notifications. I highly recommend allowing this. It is the best way to stay on top of review requests and mentions without constantly refreshing your email or the GitHub website.

-

Jamie: OK, so I have downloaded the app, I have signed in, and I have allowed notifications. What does the app actually consist of?

-

Alex: The app is organized around a main navigation bar containing five tabs. There is the Home tab, which is a personalized feed of activity across all the repositories you watch. A repository, as a quick reminder, is just the project folder where all the files and history live.

-

Jamie: Then there is the Notifications tab, which we will talk a lot about. There is an Explore tab to discover new projects. The Pull Requests tab, which collects all the pull requests assigned to you or created by you. And finally, the Profile tab for your personal settings.

-

Alex: You can move between these tabs by navigating to them and activating them, just like any other standard app on your phone. But before we get into the specific features, we need to talk about how to actually get around the app using screen readers.

-

Alex: Let us talk about iOS and VoiceOver first. If you are using an iPhone or iPad, you likely already know that you can toggle VoiceOver on by triple-clicking the side button on newer phones, or the Home button on older ones. You can also turn it on by navigating to Settings, then Accessibility, then VoiceOver.

-

Jamie: When I open GitHub Mobile with VoiceOver running, how do I move around? Is it any different from Safari or Mail?

-

Alex: It is very similar. The basic gestures apply. You swipe right with one finger to move your focus to the next element, and swipe left to move to the previous element. When you hear the item you want, you double-tap anywhere on the screen to activate it.

-

Jamie: What if I open a really long issue description and I just want VoiceOver to read the whole thing to me while I listen?

-

Alex: Great question. You can use a two-finger swipe up to read from the very first item, or a two-finger swipe down to read continuously from your current focus point. If you need to pause the speech because someone asks you a question, just do a two-finger single tap. Another two-finger tap will resume the speech.

-

Jamie: I use the two-finger tap all the time. It is a lifesaver. But what about navigating complex screens? Like, sometimes an issue has a lot of comments, and swiping through every single timestamp and author name takes forever.

-

Alex: This is where the VoiceOver Rotor becomes your best friend. The Rotor is a feature that lets you change how your up and down swipes behave. Think of it like a physical combination dial on a safe. You place two fingers on the screen and rotate them clockwise or counter-clockwise. As you turn this invisible dial, VoiceOver will announce different settings.

-

Jamie: So I twist my fingers on the screen, and I might hear it say "Characters," "Words," "Headings," "Links."

-

Alex: Exactly. For GitHub Mobile, the most useful Rotor settings are Headings, Links, and Form Controls. If you select Headings on your Rotor, you can then just swipe down with one finger to jump directly from the issue description, to the first comment, to the second comment, completely skipping all the clutter in between.

-

Jamie: Oh, that is clever! I wish I had known that when I started. It is like skipping from chapter title to chapter title in an audiobook instead of fast-forwarding through every word.

-

Alex: That is a perfect analogy. You will also use the Form Controls option on the Rotor quite a bit. When you want to leave a comment on a pull request, selecting Form Controls and swiping down will jump your focus straight to the text input field, so you do not have to hunt for it.

-

Jamie: OK, but what if I am on an Android device? I know we have a lot of Android users in the workshop who use TalkBack.

-

Alex: Absolutely. TalkBack is the built-in screen reader for Android. You can usually turn it on by holding both volume keys for three seconds, or by navigating to Settings, then Accessibility, then TalkBack.

-

Jamie: Are the gestures the same as VoiceOver?

-

Alex: Many of them are! You still swipe right with one finger to move to the next element, swipe left for the previous element, and double-tap to activate whatever is currently in focus.

-

Jamie: What about scrolling? If a screen is really long, how do I move down?

-

Alex: With TalkBack, you can scroll down by using a two-finger swipe up, which pushes the content up so you can access what is below. Or, if you prefer the single-finger gestures, you can swipe up then immediately down in one fluid motion to scroll forward. To go back to the previous screen, you can swipe right then left.

-

Jamie: And does TalkBack have something like the VoiceOver Rotor for jumping around quickly?

-

Alex: It handles this slightly differently, through reading controls and the TalkBack menu. You can swipe up or down with one finger to cycle through your reading granularity, changing it to characters, words, lines, or paragraphs.

-

Jamie: So I can set it to paragraphs and swipe right to jump a whole paragraph at a time?

-

Alex: Exactly. You can also open the global TalkBack menu by tapping the screen with three fingers, or by swiping down then right. This menu lets you activate specific reading controls or even copy text from an issue description, which is incredibly useful if you need to copy an error message someone posted.

-

Jamie: One thing I love doing on Android is Explore by Touch.

-

Alex: Yes, Explore by Touch is fantastic on GitHub Mobile. Instead of swiping sequentially through every item, you just drag one finger slowly across the glass of your screen. TalkBack will announce whatever is underneath your finger. It is exactly like reading a tactile map with your hands. Once you learn the general layout of the app, dragging your finger directly to the tab bar is much faster than swiping fifty times to get there.

-

Jamie: So now that we know how to move around, let us talk about the feature I use the most. The Notifications tab.

-

Alex: I will go a step further, Jamie. I think the Notifications tab on GitHub Mobile is one of the strongest accessibility features GitHub has ever built. For screen reader users, the mobile notification experience is often much better than the desktop web version.

-

Jamie: I completely agree. On the website, notifications can feel overwhelming. They are grouped in these complex tables, and sometimes it is hard to figure out why you are even being notified.

-

Alex: But on mobile, your notifications are presented as a clean, simple, linear list. It is just one item after another. And the true power comes from the swipe actions.

-

Jamie: Right! This is my mail sorting analogy. Imagine you have a massive stack of physical mail. You pick up an envelope, decide what to do with it, and throw it into a bucket. Keep, trash, or read later.

-

Alex: Exactly. When your focus is on a notification in the list, you can use the custom actions in your screen reader. On VoiceOver, you swipe up or down when focused on a notification to hear the available actions. On TalkBack, you can use the action menu.

-

Jamie: You can mark it as read, archive it, or even unsubscribe from the conversation entirely if it is getting too noisy. You never even have to open the issue to clear it from your inbox.

-

Alex: And if you do want to read it, just double-tap the notification. It will open the full issue or pull request right there.

-

Jamie: There is also a really great filter feature, right?

-

Alex: Yes. If you navigate to the filter button on the notifications screen, it opens a panel with accessible form controls. You can filter your notifications by type, so you only hear about Pull Requests, or only hear about Issues. You can also filter by reason. For example, you can choose to only see notifications where someone directly at-mentioned your username, or where someone explicitly requested your review.

-

Jamie: That is a lifesaver when you are working on a massive open-source project and there are hundreds of notifications a day. You just filter by "Review Requested," handle those three items, and get on with your day.

-

Alex: Let us talk about what happens when you actually open an issue. Remember, an issue is where conversations happen about bugs or new ideas.

-

Jamie: Filing an issue on mobile is surprisingly easy. You navigate to the repository you want, activate the Issues tab, and navigate to the New Issue button.

-

Alex: When you activate that, you are presented with a simple form. There is a text field for the title, and a larger text field for the body of the issue. You also have buttons to assign labels, add assignees, or attach it to a milestone.

-

Jamie: OK, that sounds like a lot of steps.

-

Alex: It does! But here is the thing, you have already done most of this on Day 1 of the workshop. It is the exact same workflow as the website, just presented in a single, vertical column. You type your title, type your description, and activate the Submit button.

-

Jamie: Writing comments is where I used to get tripped up, though. I would activate the comment field, the on-screen keyboard would pop up, I would dictate my message, and then I could not find the submit button to actually post it.

-

Alex: That is a very common point of friction, and it has to do with how mobile operating systems handle keyboards. When the keyboard appears, it takes up nearly half of your screen, often covering the buttons underneath it.

-

Jamie: Exactly! I would swipe right, and suddenly I am just tabbing through my keyboard letters. Q, W, E, R, T, Y.

-

Alex: The workaround here is to dismiss the keyboard first, or scroll past it. On iOS, you can sometimes touch an empty area of the screen above the keyboard to dismiss it, or swipe down with two fingers to hide it. Once the keyboard drops out of the way, the Comment button is right there waiting for you.

-

Jamie: On Android, I usually just use the system back gesture, which is swiping right then left. That hides the keyboard, and then I can swipe right to find the Comment button. It feels natural once you do it a few times, but the first time it happens, it is definitely confusing.

-

Alex: Now let us move on to pull requests. This is where GitHub Mobile really shines for developers on the go.

-

Jamie: A pull request, just to recap, is when someone says, "Hey, I wrote some code, and I want to merge it into the main project." And usually, they need someone else to review it and approve it first.

-

Alex: Exactly. Mobile is fantastic for quick pull request reviews. Imagine you are waiting for a bus, or sitting in a coffee shop without your laptop, and a teammate messages you saying they fixed a typo and need a quick approval. You can do that entirely from your phone.

-

Jamie: When I open a pull request on the app, how is it structured?

-

Alex: The screen is divided into clear sections, which your screen reader will announce as headings. There is the Description heading, which contains the summary the author wrote. Then there is a Commits heading, showing the individual history of changes. Then there is Files Changed, which is where you actually look at the code. And finally, a Checks heading, which tells you if the automated tests passed or failed.

-

Jamie: I want to talk about the Files Changed section, because this is my other favorite accessibility feature. On the desktop website, looking at a diff, which is the difference between the old code and the new code, can be a nightmare with a screen reader.

-

Alex: It really can. The web version often uses complex, multi-column tables. One column for the old line number, one for the new line number, one for the old code, one for the new code. It is very difficult to parse by ear.

-

Jamie: But on the mobile app, the diff is simplified! It is just a text list.

-

Alex: Yes, this is a huge advantage. Because phone screens are narrow, GitHub Mobile strips away the complex table layout. Instead, each changed line of code is presented as a single item. Your screen reader simply announces "Added" followed by the new code, or "Removed" followed by the old code.

-

Jamie: It is so much cleaner. If someone changed a color value, my screen reader just says, "Removed: background blue. Added: background black." It is incredibly easy to understand.

-

Alex: Once you have reviewed those changes, you can leave your review. You navigate to the Review Changes button and activate it. This opens a panel where you can choose to Approve the pull request, Request Changes if something is wrong, or just leave a general Comment. You can type an optional message, and then activate the Submit Review button.

-

Jamie: What about just browsing code? Sometimes I want to look up how a specific function was written, but I am not reviewing a pull request. Can I do that?

-

Alex: You can. If you navigate to any repository, there is an option to browse the code. You can move through the folders and open individual files to read them.

-

Jamie: But this goes back to our earlier point. It is like reading the table of contents of a cookbook, and maybe reading a single recipe. You are not going to rewrite the recipe from your phone.

-

Alex: Exactly. You can read the code, but there is no syntax highlighting, and more importantly, you cannot edit the files directly in the app. If you need to write code, you need to use a desktop environment or a cloud tool like GitHub Codespaces.

-

Alex: Before we wrap up, we need to be honest about the current accessibility limitations of GitHub Mobile. While it is a fantastic tool, it is not perfect.

-

Jamie: Yeah, I have definitely run into a few quirks. Sometimes, if a pull request description is really long and has complex formatting, like embedded videos or large markdown tables, VoiceOver just sort of skips over it or reads it in a very confusing order.

-

Alex: That is a known issue. Complex markdown parsing on mobile screen readers can be tricky. The best workaround for this is to open the pull request in your mobile browser instead. You can navigate to the More Options menu, which is usually labeled as a button with three dots, and activate Open in Browser. Safari or Chrome will often read complex web layouts better than the native app view.

-

Jamie: I have also noticed a quirk with TalkBack on Android regarding the notification badges. You know how apps have a little number telling you how many unread items you have?

-

Alex: Yes, the badge count.

-

Jamie: Sometimes TalkBack does not announce when that badge count updates live. I will be on the Home tab, and a new notification will come in, but TalkBack will not say anything about it.

-

Alex: That is true. The visual badge updates, but the accessibility event does not always fire. To get the current, accurate count read aloud, you need to explicitly navigate your focus to the Notifications tab itself.

-

Jamie: And of course, there is the occasional app freeze.

-

Alex: Yes, like any app, GitHub Mobile can occasionally freeze or crash. If your screen reader suddenly stops responding while inside the app, the best step is to force close the application. On iOS, you swipe up from the bottom edge and hold to open the app switcher, then swipe up on GitHub to close it. On Android, you open your recent apps and swipe it away. Then just reopen it. If it keeps happening, you can navigate to your Profile, open Settings, and sign out, then sign back in.

-

Jamie: So, comparing mobile to desktop, what is the final verdict?

-

Alex: It comes down to using the right tool for the job. Think of GitHub Mobile as a Swiss Army knife, and your desktop computer as a full workshop. The mobile app is absolutely excellent for triaging notifications. The linear list and swipe actions are superior to the desktop web experience.

-

Jamie: It is also great for quick pull request approvals, leaving simple comments, or checking if your automated tests passed while you are making lunch.

-

Alex: But for writing long, detailed pull request descriptions, reviewing massive code diffs with hundreds of changed files, or dealing with complex issue templates, you are going to have a much better time on your desktop using your physical keyboard.

-

Jamie: And of course, for actually writing and editing code, desktop is the only way to go.

-

Alex: That brings us to the end of Episode 32. Let us recap our main takeaways.

-

Jamie: First, GitHub Mobile is an incredibly powerful companion app for iOS and Android, designed for project communication, not for writing code.

-

Alex: Second, the app fully supports VoiceOver and TalkBack. Mastering tools like the VoiceOver Rotor or TalkBack reading controls will make navigating complex issues much faster.

-

Jamie: Third, the Notifications tab is a game changer. Use the swipe actions to quickly triage your inbox, just like sorting physical mail.

-

Alex: And finally, the simplified, linear code diffs on mobile are highly accessible. They announce "Added" or "Removed" sequentially, making quick code reviews by ear much easier than wrestling with web-based tables.

-

Jamie: I am definitely going to be doing more PR reviews from my couch now.

-

Alex: That is the spirit. In our next episode, Episode 33, we will be pivoting back to the desktop to explore GitHub Actions. We will learn how to automate our workflows, run tests automatically, and make the robots do the heavy lifting for us.

-

Jamie: I cannot wait to automate everything! Thanks for listening, everyone.

-

Alex: Keep practicing with the mobile app, and we will see you in the next episode. Happy coding!

-
- - -

Episode 33: Publishing with GitHub Pages

-

Free static site hosting, custom domains, HTTPS, and accessibility.

-

Based on: Appendix P: Publishing with GitHub Pages

- - -

Download Episode 33 (MP3)

-
-Read Transcript - Episode 33: Publishing with GitHub Pages - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub.

-

Jamie: The audio series for blind and low-vision developers learning GitHub and open source collaboration.

-

Alex: I am Alex, and I am thrilled to be here with you today.

-

Jamie: And I am Jamie. I am ready to learn, and I have my usual list of questions.

-

Alex: This is episode 33, Publishing with GitHub Pages. Today, we are taking all that Markdown and code you have been writing and turning it into a live, public website. Free of charge, directly from your repository.

-

Jamie: I remember when I first learned about this. I had been paying ten dollars a month for a basic web host just to put my resume online. When someone told me GitHub would host it for free, I honestly did not believe them.

-

Alex: It is one of the best kept secrets for beginners, though it is incredibly popular once you know about it. Before we dive in, let us do a quick check on prerequisites. For this episode, you will want to be comfortable with basic git concepts like making commits and working with branches, which we covered back in episode 4. You should also be familiar with writing Markdown, from episode 12.

-

Jamie: So, Alex, let us start at the very beginning. What exactly is GitHub Pages?

-

Alex: GitHub Pages is a static site hosting service built directly into GitHub. It takes the files from a specific branch or folder in your repository and serves them to the internet as a website.

-

Jamie: You used the phrase static site. I hear that a lot, usually contrasted with dynamic sites. Can we define what static means in this context?

-

Alex: Absolutely. A static website means that the server is simply handing over files exactly as they exist in your repository. It serves HTML, CSS, JavaScript, images, and documents. But it does not run any server-side logic.

-

Jamie: So no database connections, no PHP, no Python running on the server to generate the page on the fly.

-

Alex: Exactly. Think of a static site like a printed brochure or a bulletin board. What is printed on the paper is exactly what the reader sees. If you want to change the text, you have to print a new brochure. A dynamic site, on the other hand, is like a vending machine. You press a button, machinery whirs into action behind the glass, and it constructs a custom response based on what you asked for.

-

Jamie: That is a great analogy. So GitHub Pages only gives out printed brochures. If I want a vending machine, like a site where users log in and post comments to a database, GitHub Pages is not the right tool.

-

Alex: Spot on. But for many things, a brochure is exactly what you need. GitHub Pages is perfect for documentation sites, project landing pages, personal portfolios, and even simple blogs. In fact, the workshop materials for this very audio series are hosted on GitHub Pages.

-

Jamie: Okay, I am sold. How do I actually turn this on for my repository?

-

Alex: It is all done through the repository settings on the GitHub website. Let me walk you through the navigation path using a screen reader. First, navigate to your repository page. In the top navigation bar, you will find a link called Settings. Activate that link.

-

Jamie: Got it. The main settings page.

-

Alex: Once the Settings page loads, move to the left sidebar. This sidebar has a series of navigation links grouped by category. Navigate down to the group heading called Code and automation. Under that heading, you will find a link simply called Pages. Activate that Pages link.

-

Jamie: Okay, I am on the Pages settings screen. What am I looking for here?

-

Alex: Navigate to the section heading called Build and deployment. Here, you have a choice for your publishing source. You will find a dropdown menu or radio buttons depending on the current interface layout, offering two main choices. One is Deploy from a branch, and the other is GitHub Actions.

-

Jamie: Let us start with Deploy from a branch. That sounds simpler.

-

Alex: It is the simplest option. When you select Deploy from a branch, two new standard select dropdown menus will appear. You can navigate these easily with your arrow keys. The first dropdown asks you to select a branch, like your main branch. The second dropdown asks you to select a folder.

-

Jamie: What are my folder options?

-

Alex: You have two choices. You can select the root folder, which is represented by a forward slash. Or, you can select the docs folder, represented by forward slash docs.

-

Jamie: Why would I choose one over the other?

-

Alex: If your repository is just a website, like a personal portfolio where the HTML files are right there in the main directory, you choose the root folder. But let us say your repository is a complex software project, like a Python library. Your root folder is full of Python code, setup files, and tests. You do not want to publish all of that as a website.

-

Jamie: Oh, I see. So I would create a folder called docs, put my HTML documentation in there, and tell GitHub Pages to only look at that folder.

-

Alex: Exactly. Think of it like pointing a spotlight at a very specific folder on your messy desk. GitHub Pages only illuminates and publishes what is inside the docs folder, ignoring the rest of your source code.

-

Jamie: That is incredibly useful. So I click Save, and then what? Does it go live instantly?

-

Alex: Almost instantly. GitHub will take a minute or two to build and deploy the site. Once the first deployment succeeds, a message will appear at the top of that Pages settings screen with your new live URL.

-

Jamie: Let us talk about that URL. If I do not have my own domain name, what address does GitHub give me?

-

Alex: The default URL structure is your username dot github dot io, followed by a forward slash, and then your repository name. So if your username is Jamie Codes, and your repository is called my dash project, your website will be live at jamie codes dot github dot io slash my dash project.

-

Jamie: That is pretty clean. But what if I just want jamie codes dot github dot io, without the repository name at the end? Like for my main personal website?

-

Alex: GitHub has a special feature just for that. If you create a repository and name it exactly your username dot github dot io, GitHub automatically recognizes this as your user profile repository. When you enable Pages for that specific repository, it serves the site at the root level. No forward slash repository name required.

-

Jamie: I love that. I definitely used that trick for my first portfolio. But let me ask you about something that used to happen to me all the time. I would type the URL wrong, or I would try to visit a page I had not uploaded yet, and I would get this very generic GitHub 404 Page Not Found error. Can I change that?

-

Alex: You absolutely can, and you should! To create a custom error page, all you have to do is create a file named exactly four oh four dot html in the root of your publishing source.

-

Jamie: So just the numbers 4 0 4 dot html?

-

Alex: Yes. When GitHub Pages cannot find a file a visitor is looking for, it automatically serves that specific file. It is a great place to put a friendly message and a link back to your home page. Think of it like hiring a polite receptionist to tell visitors they have the wrong room, rather than just letting them walk face-first into a locked brick wall.

-

Jamie: Okay, so we have talked about hosting plain HTML files. But writing a whole website in raw HTML sounds exhausting. If I have a blog with fifty posts, I do not want to copy and paste my navigation menu fifty times.

-

Alex: And you definitely should not. This is where Static Site Generators come in. Remember our factory assembly line analogy? A static site generator is a factory. You feed it raw materials, usually Markdown files containing your content, and a few HTML templates. The generator runs the assembly line, stitches the templates and Markdown together, and spits out a complete folder of finished HTML pages.

-

Jamie: That sounds exactly like what I need. Does GitHub Pages include a factory like that?

-

Alex: It does. GitHub Pages has native support for a static site generator called Jekyll. Jekyll is built in Ruby, and it is the default engine behind GitHub Pages. If you push a repository full of Markdown files, and you have not told GitHub otherwise, it will quietly run Jekyll behind the scenes to convert those Markdown files into a website.

-

Jamie: That is why my README file automatically showed up as a website when I tested this last year! I was so confused about how my Markdown magically became HTML.

-

Alex: That was Jekyll doing the heavy lifting. But Jekyll is not the only static site generator out there. There is Hugo, which is incredibly fast. There is Eleventy, which is very popular in the accessibility community. There are frameworks like Next dot js that can export static files.

-

Jamie: But if Jekyll is the only one built in, how do I use Eleventy or Hugo with GitHub Pages?

-

Alex: That brings us back to the Build and deployment section in the Pages settings. Remember how the first option was Deploy from a branch? The second option is GitHub Actions.

-

Jamie: Ah! Okay, I have heard of GitHub Actions, but it always sounded a bit intimidating.

-

Alex: It does sound intimidating! But here is the thing, you have already done most of this on Day 1. The workflow is exactly the same, just with a server handling the commands instead of you typing them. GitHub Actions is basically a way to hire a robot assistant to run tasks for you every time you push code.

-

Jamie: So instead of the built-in Jekyll factory, I am telling my robot assistant to bring in the Eleventy factory, build my site, and then hand the finished files to GitHub Pages?

-

Alex: Precisely. You create a configuration file, specifically a yaml file, in a folder called dot github slash workflows. In this file, you write out the instructions for your robot assistant.

-

Jamie: What do those instructions look like?

-

Alex: It is a step by step list. First, you tell the robot to check out your repository code. Second, you tell it to set up the environment, like installing Node dot js if you are using Eleventy. Third, you tell it to run your build command, like npm run build. And finally, you use a pre-built GitHub Action called upload pages artifact to take the folder of finished HTML and hand it to the GitHub Pages service.

-

Jamie: That actually makes a lot of sense. And I assume there are templates for these workflow files so I do not have to write them from scratch?

-

Alex: Tons of them. When you select GitHub Actions as your source in the settings, GitHub will actually suggest pre-written workflow files based on the code in your repository. If it sees a Next dot js project, it will offer you a Next dot js template. You just commit the file, and the robot takes over.

-

Jamie: Alright, let us talk about domains. Because jamie codes dot github dot io is nice, but I really want my site to be at jamie codes dot com. Can I use a custom domain with a free GitHub Pages site?

-

Alex: Yes, you can use a custom domain on the free tier. It is one of the best features. But it does require a little bit of configuration using DNS, which stands for Domain Name System.

-

Jamie: DNS always confuses me. It feels like dark magic.

-

Alex: It can feel that way! But DNS is simply the phonebook of the internet. When someone types jamie codes dot com into their browser, their computer looks up that name in the DNS phonebook to find out the actual IP address of the server hosting your website.

-

Jamie: So how do I tell the phonebook to point to GitHub?

-

Alex: There are two steps. First, you go to your GitHub Pages settings. There is a field labeled Custom domain. You type jamie codes dot com in there and activate the Save button. GitHub will then create a file called CNAME in the root of your repository to remember your domain.

-

Jamie: Okay, step one is telling GitHub to expect visitors looking for my domain. What is step two?

-

Alex: Step two happens over at the company where you bought your domain name, your domain registrar. You need to log into their dashboard and add some records to your DNS settings. The type of record depends on whether you are using a subdomain or an apex domain.

-

Jamie: Can you define apex domain?

-

Alex: An apex domain is the root level of your domain, like jamie codes dot com. A subdomain has an extra prefix, like blog dot jamie codes dot com, or www dot jamie codes dot com.

-

Jamie: Got it. So what is the difference in the setup?

-

Alex: If you are using a subdomain, you create what is called a CNAME record. You tell your registrar that the CNAME for blog dot jamie codes dot com should point directly to your default GitHub address, jamie codes dot github dot io. It is basically a mail forwarding rule.

-

Jamie: And for the apex domain?

-

Alex: For an apex domain, you have to use A records. A stands for Address. You will create four separate A records, and point them to four specific IP addresses owned by GitHub. You can find these four IP addresses in the GitHub documentation.

-

Jamie: Okay, so I update the phonebook. Does it work right away?

-

Alex: Not always. DNS changes can take up to 48 hours to propagate across all the servers in the world, though it usually happens in a few minutes. If you push a change and do not see it, you might need to do a hard refresh of your browser. You can do this by pressing Control plus F5 on Windows, or Command plus Shift plus R on a Mac, to bypass your local cache.

-

Jamie: That is a great tip. Now, what about security? I notice most websites start with HTTPS these days. Does GitHub Pages support that?

-

Alex: It does better than support it, it enforces it. GitHub Pages automatically provisions an SSL certificate for your site using a service called Let's Encrypt. This ensures that all traffic between your visitor and your website is encrypted.

-

Jamie: Like putting the website data in a sealed, tamper-proof envelope before sending it across the internet.

-

Alex: Exactly. For the default github dot io domains, this happens automatically. For custom domains, once your DNS finishes updating, GitHub will request the certificate. You just need to make sure the Enforce HTTPS checkbox is checked in your Pages settings. It will redirect anyone trying to use the old, insecure HTTP protocol directly to the secure version.

-

Jamie: That is amazing that it is all free. Are there any security risks I should worry about?

-

Alex: There is one massive security rule you must remember. Never, ever store secrets, API keys, passwords, or private data in a GitHub Pages repository.

-

Jamie: Because it is a static site, so anyone can just view the source code?

-

Alex: Yes. And more importantly, if you are on a free GitHub account, your repository must be set to Public to use GitHub Pages. That means your entire source code history is visible to the world. Even if you delete a file with a password in it, that file still exists in your git history. So keep your secrets out of your repository.

-

Jamie: Let us pivot to something I care deeply about. Accessibility. If I publish a website using GitHub Pages, is it automatically accessible to screen readers?

-

Alex: I wish I could say yes, but no. Publishing a site just makes it available on the internet. It does not automatically make it accessible. The accessibility of your published site depends entirely on the HTML, CSS, and JavaScript you or your static site generator produce.

-

Jamie: Right, so the factory just builds what you tell it to build. If you feed it inaccessible templates, it will print inaccessible brochures.

-

Alex: Exactly. When you are building your site, you need to ensure you are using semantic HTML. This means using the correct tags for the correct purposes. For example, your primary content should be wrapped in the main landmark tag. You should have a logical heading hierarchy, starting with an H1, followed by H2s, and so on.

-

Jamie: What about navigation? If I have a blog with a big menu on every page, it can be really tedious for a keyboard user or screen reader user to tab through that menu on every single page load.

-

Alex: That is a critical point. For sites with repeated navigation, you should implement a skip link.

-

Jamie: Can you explain how a skip link works?

-

Alex: A skip link is an anchor tag placed at the very top of your HTML body. Its href attribute points directly to the id of your main content area. The text usually says something like Skip to main content. Using CSS, you can hide it visually until it receives keyboard focus. This allows keyboard and screen reader users to press the Tab key once, activate the link, and jump right over the navigation menu to the actual content of the page.

-

Jamie: I love skip links. They save so much time. What about Single Page Applications? I know some static site generators use JavaScript to load new pages without refreshing the browser.

-

Alex: That requires careful focus management. If the browser does not fully refresh, a screen reader user might not even realize the page content has changed. If you are using a framework that does this, you must ensure that when the new content loads, keyboard focus is programmatically moved to the new H1 heading, or to a wrapper element with a tabindex attribute set to negative one.

-

Jamie: Okay, so semantic HTML, skip links, focus management. How do I test all this once it is live?

-

Alex: You should definitely test the live URL. Some issues, like broken relative links or color contrast problems, might only become obvious once the site is fully rendered in a browser. You can use automated tools like WAVE or Axe DevTools.

-

Jamie: Wait, Axe DevTools? Can I use that robot assistant we talked about earlier to run Axe automatically?

-

Alex: You absolutely can! That is one of the most powerful reasons to use GitHub Actions for your deployment. You can add a step in your workflow file to install the Axe core command line interface. Before the robot deploys your site, it runs Axe against your built HTML files.

-

Jamie: And if Axe finds an accessibility violation?

-

Alex: You configure the workflow to fail. The robot stops the assembly line, refuses to deploy the broken site, and sends you an alert. It completely blocks inaccessible code from reaching your live website.

-

Jamie: That is brilliant. I am definitely setting that up for my next project. I wish I had known that when I started.

-

Alex: We have covered a lot of ground today. Let us recap our main takeaways. First, GitHub Pages is a free hosting service that serves static files directly from your repository. It is perfect for documentation, portfolios, and blogs, but it does not run server-side code.

-

Jamie: Second, you can serve files directly from your main branch, or isolate them using a docs folder. And if you want to use a custom static site generator like Eleventy or Next dot js, you can use GitHub Actions to automate the build process.

-

Alex: Third, GitHub Pages supports custom domains through DNS configuration, and it automatically enforces HTTPS using Let's Encrypt to keep your traffic secure. Just remember to never store sensitive secrets in your public repositories.

-

Jamie: And finally, publishing a site does not make it accessible. You still need to use semantic HTML, implement skip links, and manage focus. But you can use GitHub Actions to run automated accessibility tests and block deployments if violations are found.

-

Alex: Perfect summary, Jamie. In our next episode, we are going to explore GitHub Discussions, a feature that allows you to build a community and have open-ended conversations right next to your code.

-

Jamie: I am looking forward to it. Thanks for listening, everyone!

-

Alex: Keep practicing, and we will catch you in the next episode of Gitt Going with GitHub.

-
- - -

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: Welcome to Gitt Going with GitHub, the audio learning series for blind and low-vision developers who are mastering GitHub and open source collaboration. This is episode 34, titled GitHub Actions and Workflows. I am your host, Alex.

-

Jamie: And I am Jamie. I am so excited for this one. We have spent the last thirty-three episodes talking about how to write code, how to commit code, and how to open pull requests. But today, we are talking about what happens after you open that pull request. Because a lot of magic happens, and sometimes it can feel a little bit like a black box.

-

Alex: That is a perfect way to describe it, Jamie. Before we dive into that black box, let us do a quick prerequisite check. To get the most out of this episode, you should already be comfortable with the concepts of commits, pushing branches to a remote repository, and opening a pull request. If you need a refresher on those, head back to episode 28. Assuming you are ready, let us talk about GitHub Actions.

-

Jamie: So, I will admit, when I first started learning GitHub about two years ago, I kept hearing the phrase GitHub Actions. And I thought it just meant the literal actions I was taking on the website, like creating a repository or adding a collaborator. But it is actually a specific feature, right?

-

Alex: Exactly. GitHub Actions is GitHub's built-in automation system. It is a way to define automated tasks that run in response to specific events happening in your repository. The best way to think about it is that GitHub Actions is like having a tireless robot assistant living inside your repository.

-

Jamie: I love a robot assistant. What kind of things is this robot doing for us?

-

Alex: Well, you get to tell the robot exactly what to do. You can say, hey robot, every time someone opens a pull request, I want you to download their code, install all the dependencies, run our automated test suite, and report back on whether the tests passed or failed. Or you could say, hey robot, every time I push code to the main branch, I want you to package up the application and deploy it to our live web server.

-

Jamie: Oh, that is incredibly powerful. Because otherwise, a human maintainer would have to manually pull down my branch, run the tests on their own machine, and then manually reply to my pull request. This robot is saving everyone a massive amount of time.

-

Alex: Precisely. It is event-driven automation. Something happens in the repository, which is the event, and that triggers the automation, which is the action. And as a contributor to open source, you usually do not need to write these automations from scratch. The repository maintainers have already set them up. But you absolutely need to understand how to read them, what they are doing, and what to do when they fail on your pull request.

-

Jamie: Okay, so if the maintainers have set up this robot assistant, where do the instructions for the robot actually live? Is it a setting in the repository dashboard somewhere?

-

Alex: That is a great question. The instructions do not live in a dashboard. They live directly in the repository itself, right alongside the code, as plain text files. They live in a very specific, mandatory folder structure. If you navigate to the root directory of a repository, you will find a folder called dot github.

-

Jamie: And just to clarify for everyone listening, when we say dot github, we mean a folder name that literally starts with a period character, followed by the word github. My screen reader usually reads it out as dot github. When I first saw that, I thought the period was a typo.

-

Alex: It is not a typo, but it is a convention borrowed from Unix-based systems where putting a dot at the start of a file or folder name marks it as hidden. So depending on your editor settings, you might need to enable a setting like show hidden files in your file explorer to navigate to it. Inside that dot github folder, there is another folder called workflows. And inside that workflows folder is where the magic lives.

-

Jamie: Dot github, slash workflows. Got it. And what kind of files are in there? Are they JavaScript files or Python scripts?

-

Alex: They are YAML files. That is spelled Y A M L. And they usually have the file extension dot y m l. YAML stands for YAML Ain't Markup Language, which is a classic nerdy recursive acronym. But really, it is just a plain text format used for configuration files. It uses key and value pairs, separated by colons.

-

Jamie: I have a love-hate relationship with YAML. The syntax is very clean because it does not use a bunch of curly braces or brackets, but it relies heavily on indentation to define structure. And as a screen reader user, indentation can be tricky if you are not prepared for it.

-

Alex: That is a really important point. When you are reading a YAML file, the spacing at the start of the line tells you how things are nested. If you are reading these files, I highly recommend configuring your screen reader to announce indentation. In NVDA, you can do this by pressing NVDA plus Control plus D to open the document formatting settings, and then checking the box to announce line indentation.

-

Jamie: Yes, I do exactly that. Or sometimes I use an extension in Visual Studio Code that plays a little audio tone that goes higher in pitch the more indented a line is. It is super helpful for YAML. So, we have these YAML files in the workflows folder. What is the vocabulary we need to know to actually read them? I know there is a specific hierarchy of terms.

-

Alex: There is. The hierarchy goes like this. Workflow, event, job, step, and action. Let us break those down. A workflow is the entire automated process. Each YAML file in that folder represents one workflow. For example, you might have a file called tests dot y m l. That entire file is your testing workflow.

-

Jamie: Okay, workflow is the whole file. And what triggers the workflow?

-

Alex: That is the event. In the YAML file, you will find a key called on, spelled O N. This defines the trigger event. Common events include push, which triggers when someone pushes a commit to a branch. Another is pull underscore request, which triggers when a pull request is opened or updated.

-

Jamie: So if the file says on colon pull underscore request, that workflow will run every single time I update my pull request.

-

Alex: Exactly. There are other triggers too. You can use schedule to run a workflow on a timer, like every Monday at nine in the morning. Or you can use workflow underscore dispatch, which is a fancy way of saying manual trigger. It adds a button to the GitHub interface so a maintainer can run the workflow whenever they want.

-

Jamie: Alright, so we have the workflow, which is the whole file. We have the event, which wakes the robot up. What comes next?

-

Alex: Next is the job. A workflow can have one or more jobs. A job is a group of steps that run together on the same machine. In the YAML file, you will see a key called jobs. Underneath that, you name your jobs. You might have a job called run dash tests, and another job called build dash documentation.

-

Jamie: You mentioned they run on the same machine. Where is this machine? Is it my computer?

-

Alex: No, it is not your computer. This is one of the coolest parts of GitHub Actions. GitHub provides the computers for you, completely free for public open source repositories. These computers are called runners. They are essentially fresh, clean virtual servers in the cloud. In your YAML file, every job must specify what kind of runner it needs using a key called runs dash on.

-

Jamie: Oh, I have seen this. It usually says something like runs dash on colon ubuntu dash latest.

-

Alex: Exactly. Ubuntu dash latest tells GitHub to spin up a virtual machine running the latest version of the Ubuntu Linux operating system. You can also ask for windows dash latest or macos dash latest if your code needs to be tested on those specific operating systems. So, your job asks for a runner, GitHub provisions that runner, and then the job executes its steps on that machine.

-

Jamie: Which brings us to steps. I am guessing steps are the individual commands we want the runner to execute?

-

Alex: You got it. Steps are executed in order, one by one. A step can just be a simple shell command. For example, you could have a step with the key run, followed by the command npm install. The runner will open its terminal and type npm install. The next step might run npm test.

-

Jamie: This makes so much sense. To use an analogy, the workflow is like a recipe for baking a cake. The event is someone saying they are hungry. The job is the kitchen you are cooking in, like the ubuntu latest kitchen. And the steps are the literal recipe instructions. First, measure the flour. Second, crack the eggs.

-

Alex: That is a brilliant analogy, Jamie. And that analogy leads us perfectly to the final piece of the hierarchy, which is the action. Sometimes, a step is not just a simple shell command. Sometimes, a step uses a pre-built piece of automation called an action.

-

Jamie: Ah, so this is where the name GitHub Actions comes from. What is a pre-built action?

-

Alex: Let us go back to your kitchen analogy. Imagine your recipe requires you to make a complex pastry dough. You could write out fifty steps to make it from scratch. Or, you could just buy pre-made pastry dough from the store and save yourself a ton of time. An action is that pre-made dough. It is a reusable unit of code that someone else wrote, which you can just plug into your workflow.

-

Jamie: Oh, that is clever. How do I use one of these actions in my YAML file?

-

Alex: Instead of using the run key for a shell command, you use the uses key. For example, almost every workflow starts with a step that uses an action called actions slash checkout. You write uses colon actions slash checkout at version four.

-

Jamie: What does the checkout action do?

-

Alex: Remember that the runner is a brand new, empty computer. It does not have your code on it yet. The checkout action is a pre-built script that securely authenticates with GitHub, downloads your repository, and places it into the runner's workspace. Doing that from scratch with shell commands would be tedious and error-prone, but the pre-built action does it perfectly in one line.

-

Jamie: That is amazing. Are there other pre-built actions I can use?

-

Alex: Thousands of them. GitHub hosts a directory called the GitHub Marketplace where anyone can publish an action. There are actions to set up specific versions of Python or Node. There are actions to send a message to a Slack channel when a job finishes. There are even actions that use artificial intelligence to scan your code for accessibility issues. It is basically an app store for automation.

-

Jamie: Okay, so I understand the structure now. Workflows have events. Events trigger jobs. Jobs run on runners. And jobs are made of steps, which can either be shell commands or pre-built actions. That feels very logical. But let us talk about how this actually impacts me as a contributor. When I open a pull request, what are the most common workflows I am going to encounter?

-

Alex: The two most common concepts you will hear about are CI and CD. CI stands for Continuous Integration. CD stands for Continuous Deployment. Let us start with CI. Continuous Integration is the practice of automatically testing every single change made to a codebase.

-

Jamie: So when I open a pull request, the CI workflow is the one that grabs my code and runs the tests.

-

Alex: Exactly. The CI workflow is usually triggered by the pull underscore request event. It spins up a runner, checks out your branch, and runs the project's test suite. It acts like an automated spellchecker for your logic. It ensures that your new code did not accidentally break any existing features.

-

Jamie: And what about CD? Continuous Deployment?

-

Alex: Continuous Deployment usually happens after your pull request is approved and merged. The CD workflow is typically triggered by a push event to the main branch. When the maintainer merges your pull request, the CD workflow wakes up, packages the application, and automatically deploys it to the live production server.

-

Jamie: Wow. So nobody is manually copying files over to a server via FTP anymore. The CD workflow just handles it. It is like an automated printing press that publishes the book as soon as the final edit is approved.

-

Alex: Exactly. Now, there are a few advanced workflow patterns you will see in open source repositories that are worth knowing about. One is called a matrix build.

-

Jamie: A matrix build. That sounds like something out of a science fiction movie. What does it do?

-

Alex: It is actually very practical. Imagine you are writing a JavaScript library that other developers will use. You want to make sure your library works on Node version eighteen, Node version twenty, and Node version twenty-two. Instead of writing three separate jobs, you define a matrix strategy in your YAML file. You provide a list of the Node versions, and GitHub Actions automatically multiplies your job, running three identical runners side-by-side, each testing a different version.

-

Jamie: Oh, I see! Going back to the kitchen analogy, that is like testing a new cookie recipe by baking one batch in a gas oven, one in an electric oven, and one in an air fryer, all at the exact same time, to make sure they all taste good.

-

Alex: That is exactly what it is. And it saves a massive amount of time. Another concept you will encounter is workflow artifacts.

-

Jamie: Artifacts. Like ancient pottery?

-

Alex: Similar concept, actually! When a job runs on a runner, any files it creates are trapped on that virtual machine. When the job finishes, GitHub deletes the runner. It is completely destroyed. So if your job generates a test report, or compiles a binary executable, that file will be destroyed too. Unless you upload it as an artifact.

-

Jamie: Ah, so an artifact is a way to save a file before the virtual machine self-destructs.

-

Alex: Exactly. You use a pre-built action called actions slash upload dash artifact. You tell it which folder to save, and GitHub attaches it to the workflow run as a downloadable zip file. It is like asking the restaurant for a takeaway box for your leftovers before they clean off your table.

-

Jamie: I love that. Takeaway boxes for code. And what about passwords? If a workflow needs to deploy to a live server, it needs the server password. But you said these YAML files are plain text in the repository. We definitely should not put passwords in plain text YAML files, right?

-

Alex: Right. You should never, ever put passwords, API keys, or security tokens in a workflow file. Instead, GitHub has a feature called Secrets. Maintainers can go into the repository settings and save a password as an encrypted secret. Let us say they name it SERVER underscore PASSWORD. In the YAML file, you can reference that secret using a special syntax. GitHub Actions will securely inject the password into the runner when the job starts, and it will even mask the password in the text logs so nobody can read it.

-

Jamie: That makes sense. It is like putting the password in a locked safe, and only the robot assistant has the combination.

-

Alex: So we have covered how workflows are built. But now we need to talk about the most important part for you as a contributor. Status checks. When you open a pull request, how do you know if the CI workflow passed or failed?

-

Jamie: I know this one! If you navigate to the conversation tab of your pull request and scroll down near the bottom, right above the merge button, there is a section called status checks.

-

Alex: Exactly. If you are using a screen reader like NVDA or JAWS in browse mode, you can press the letter H or the number 2 to navigate through the headings until you hear the section for checks. If you are using VoiceOver on a Mac, you can open your rotor with VoiceOver plus U, select headings, and navigate to checks.

-

Jamie: And what does the screen reader actually announce when I get to that section?

-

Alex: It will announce a list of the jobs that ran on your pull request. Each item in the list will announce its name, and its status. If a workflow is currently running, you will hear that it is pending or in progress. If it finishes successfully, you will hear a green checkmark or passed. And if it fails, you will hear a red cross or failed.

-

Jamie: Okay, let us talk about failure. Because the first time I got a red cross on my pull request, I panicked. I thought I broke the entire open source project and that the maintainers were going to be furious with me.

-

Alex: I am so glad you brought that up. We need to normalize failing status checks. A failing check is not a judgment on your worth as a developer. It is not a sign that you did something terrible. It is simply the robot assistant doing its job. It is giving you information. It is saying, hey, this specific test did not pass with your new code.

-

Jamie: That is a very comforting way to look at it. But okay, the robot says I failed. How do I find out why I failed? How do I read the error?

-

Alex: This is where we need to navigate the Actions tab. From that list of status checks on your pull request, every failed check is actually a link. If you press Enter on the failed check, it will take you away from the pull request and into the detailed workflow run page.

-

Jamie: Okay, I am on the workflow run page. There is a lot of information here. How do I find the actual error message efficiently?

-

Alex: The page is organized with a sidebar showing the jobs, and a main content area showing the steps for the selected job. If a job failed, the steps list will show exactly which step caused the failure. Navigate through the list of steps. They are interactive elements. When you find the step that failed, press Enter to expand its log output.

-

Jamie: And the log output is just a big text area showing everything the terminal printed out during that step, right?

-

Alex: Exactly. And these logs can be thousands of lines long. Reading them from top to bottom with a screen reader is completely inefficient. Instead, you should use your screen reader's find command. If you use NVDA, press NVDA plus Control plus F. If you use JAWS, press Insert plus F. If you use VoiceOver, press VoiceOver plus F.

-

Jamie: And what word should I search for?

-

Alex: Search for the word error, or the word failed in all caps. This will usually jump your cursor directly to the line that explains what went wrong. You might find a message saying syntax error on line forty-two, or assertion failed expected true but received false. Once you have that information, you can go back to your code, fix the issue, and commit the change.

-

Jamie: And do I need to manually restart the workflow after I commit the fix?

-

Alex: Usually, no. Because the workflow is listening for the pull underscore request event, pushing a new commit to your pull request branch will automatically trigger the workflow to run again. The yellow pending indicator will appear, and you can wait to see if it turns into a green checkmark.

-

Jamie: Alex, before we wrap up, I want to ask about something specific to our audience. We are a community of blind and low-vision developers. Are there workflows that specifically help with accessibility?

-

Alex: Absolutely. The open source accessibility community relies heavily on GitHub Actions. Many repositories configure automated accessibility scanners to run on every pull request. These workflows use tools like axe-core or pa11y to scan the HTML output of your code and check for WCAG violations.

-

Jamie: Oh, so if I accidentally write an image tag without an alt attribute, the workflow will catch it?

-

Alex: Exactly. The status check will report as failed. And when you read the log, it will tell you that the image is missing an alt attribute. GitHub even has a new AI-powered accessibility scanner action in the marketplace that helps identify and suggest fixes for these issues.

-

Jamie: That is fantastic. But I assume automated tools cannot catch everything, right?

-

Alex: You are entirely correct. Automated accessibility tools catch only about thirty to forty percent of all accessibility issues. They are great for catching structural errors like missing labels or poor color contrast. But they cannot tell you if a complex widget is actually usable with a screen reader. They cannot evaluate the logical flow of a page.

-

Jamie: Which is exactly why manual testing by developers who actually use screen readers every day is so incredibly valuable. The robot assistant can do the basic checks, but it needs us to ensure the experience is actually accessible.

-

Alex: Perfectly said, Jamie. The robot handles the baseline, so we can focus on the human experience. There is one last thing I want to mention about workflows and open source. Sometimes, you will open a pull request on a repository for the very first time, and the workflows will not run at all. Instead, you will see a message saying a maintainer must approve the workflow runs.

-

Jamie: Oh, I have seen that! I thought I did something wrong. Why does it require approval?

-

Alex: It is a security feature. Remember that GitHub provides free cloud computers to run these jobs. In the past, bad actors would open automated pull requests with malicious code designed to mine cryptocurrency on GitHub's free servers. To prevent this, GitHub requires a human maintainer to approve the first-time workflow run from any new contributor.

-

Jamie: So if I see that message, I just need to be patient?

-

Alex: Yes. You can leave a polite comment on your pull request saying, this is ready for review, could a maintainer please approve the workflow runs? Once they approve you that first time, future pull requests from you will trigger the workflows automatically.

-

Jamie: This has been an incredibly enlightening episode. I feel like the black box of GitHub Actions is finally open. I understand what the robot assistant is doing.

-

Alex: I am glad to hear it. Let us recap our concrete takeaways for today. First, GitHub Actions is an automation system defined by YAML files living in the hidden dot github slash workflows directory.

-

Jamie: Second, the hierarchy goes workflow, event, job, step, and action. Events are triggers like a push or a pull request. Jobs run on cloud computers called runners. And steps execute commands or use pre-built actions from the marketplace.

-

Alex: Third, CI workflows test your code on every pull request, acting like an automated spellchecker. CD workflows deploy your code when it merges to the main branch.

-

Jamie: Fourth, failing status checks are normal and helpful. Use your screen reader's find command to search for the word error in the workflow logs so you can quickly fix the issue and push a new commit.

-

Alex: And finally, automated accessibility workflows are great for catching baseline issues, but they do not replace the vital manual testing that developers using assistive technology provide.

-

Jamie: This was fantastic. What are we covering next time?

-

Alex: Next time, in episode 35, we are taking everything we learned today about GitHub Actions and taking it to the next level. We will be discussing GitHub Agentic Workflows. We will learn how to invite a cloud-based AI coding agent to execute tasks inside these workflows, essentially upgrading our robot assistant with artificial intelligence.

-

Jamie: I cannot wait for that.

-

Alex: Until then, keep exploring, keep pushing code, and we will talk to you next time on Gitt Going with GitHub.

-
- - -

Episode 35: Profile, Sponsors, and Wikis

-

Profile README, GitHub Sponsors, and repository Wikis.

-

Based on: Appendix R: Profile, Sponsors, and Wikis

- - -

Download Episode 35 (MP3)

-
-Read Transcript - Episode 35: Profile, Sponsors, and Wikis - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub, the audio learning series for blind and low-vision developers who are mastering Git, GitHub, and open-source collaboration. I am Alex, and I am thrilled to be here with you for Episode 35, Profile, Sponsors, and Wikis.

-

Jamie: And I am Jamie. I am so ready for this episode because up until now, we have been very focused on the code. We have talked about repositories, commits, branches, and pull requests. But today feels a little different. Today feels like we are talking about the people behind the code.

-

Alex: That is exactly right, Jamie. GitHub is the largest host of source code in the world, but it is also a massive social network for developers. And just like any community, how you present yourself, how you support others, and how you share knowledge all matter deeply. Today, we are covering three community-facing features. First, your profile page and how to create a custom profile README. Second, GitHub Sponsors, which is a way to financially support open-source maintainers. And third, GitHub Wikis, which is a built-in tool for creating project documentation.

-

Jamie: I remember when I first started learning GitHub about two years ago, I was terrified to look at my own profile page. I felt like it was this giant blank billboard announcing to the world that I was a beginner.

-

Alex: That is such a common feeling! Let us start right there. Your profile page is what visitors encounter when they navigate to github dot com slash your username. Think of it as your digital front porch, or your developer business card. By default, it shows your name, maybe a bio if you filled one out in your account settings, a list of repositories you have contributed to, and a contribution graph. But a few years ago, GitHub added a secret feature, an Easter egg, really, that lets you completely customize this page.

-

Jamie: Oh, I love a good Easter egg. What is the secret?

-

Alex: It is called the profile README. If you create a brand new repository, and you name that repository exactly the same as your GitHub username, something special happens.

-

Jamie: Wait, let me make sure I understand. My username is Jamie Codes. So I would create a repository and literally name it Jamie Codes?

-

Alex: Exactly. It is case-sensitive, so it needs to match perfectly. You create a new public repository named Jamie Codes. You initialize it with a README file. And here is the magic part. Whatever you write inside that specific README file will be automatically displayed right at the top of your main GitHub profile page.

-

Jamie: That is incredibly clever. So instead of just a generic list of my projects, I can actually write an introduction. I can say, Hello, I am Jamie, I am learning Python, and I am passionate about digital accessibility.

-

Alex: Exactly. You have complete control. You write it in Markdown, which, as a reminder, is the lightweight text formatting language we use all over GitHub to create headings, lists, and links. Your profile README is the perfect place to include an introduction, your current focus or what you are learning right now, the skills you bring to the table, and how people can get in touch with you.

-

Jamie: I have to admit, okay, when I finally figured this out, I went a little overboard. I found all these tutorials online about adding dynamic widgets and fifty different skill badges for every piece of software I had ever touched.

-

Alex: And how did that work out for your screen reader?

-

Jamie: It was a nightmare! My screen reader would just announce, graphic, JavaScript logo, graphic, Python logo, graphic, HTML logo. It took forever to read through my own profile. I realized I had made my digital front porch completely inaccessible to other blind developers.

-

Alex: That is a brilliant point, and it brings us to making your profile README accessible. Because visitors are skimming this page, you want to keep it clean and structured. First, always use proper heading levels. Start with a level one heading for your name, and level two headings for sections like Skills or Get in Touch. This allows screen reader users to press the H key and jump straight to the information they want.

-

Jamie: Yes, heading structure is a lifesaver. And what about images? I know some people like to put a banner image at the top.

-

Alex: If you use an image, you must provide alternative text, or alt text. In Markdown, you write an exclamation mark, then square brackets containing your description, followed by the image link in parentheses. But even more important than alt text is what you should avoid. You mentioned those auto-generated statistics widgets, like the ones that say Jamie has made forty commits this week. Those are often rendered as complex scalable vector graphics, or SVGs, without proper text equivalents. They are completely silent or read as a jumble of code to a screen reader.

-

Jamie: And let us talk about ASCII art. You know, when people use hundreds of punctuation marks to draw a picture of a cat or a spaceship?

-

Alex: Please, do not put ASCII art in your profile README. A screen reader will dutifully read every single character. Dash dash dash slash backslash asterisk asterisk. It is incredibly frustrating for someone just trying to find your email address. Keep it human, keep it authentic, and keep it simple. A well-written paragraph about who you are is far more impactful than a wall of noisy widgets.

-

Jamie: I ended up deleting all those badges and just writing a few bullet points about my current projects and my screen reader testing experience. It felt much more authentic. Now, Alex, you mentioned the contribution graph earlier. I have heard my sighted colleagues talk about this a lot. They talk about their green squares and keeping their streak alive. Can you explain what the contribution graph is and what those squares actually represent?

-

Alex: Absolutely. The contribution graph is a visual calendar on your profile page that shows your GitHub activity over the past year. Sighted users see a grid of little squares, where each square represents a day. If you made a contribution on that day, the square is colored green. The more contributions you made, the darker the green.

-

Jamie: And what counts as a contribution?

-

Alex: A contribution is recorded when you commit code to a repository's default branch, when you open an issue, when you propose a pull request, or when you submit a pull request review. So it is essentially a data log of your public activity.

-

Jamie: It sounds like a fitness tracker, but for coding. Like hitting your ten thousand steps, but instead, you are making commits.

-

Alex: That is a perfect analogy. And just like a fitness tracker, it can be motivating, but it can also be a little toxic if you obsess over it. Some developers feel immense pressure to have a contribution every single day, to keep their streak going. But taking a break is healthy. From an accessibility standpoint, GitHub has improved the screen reader experience for this graph. You can navigate through the grid, and your screen reader will announce the date and the number of contributions made on that day. But remember, this graph is just one metric. It does not measure the quality of your code, your mentorship, or the time you spent reading documentation. It just measures activity.

-

Jamie: Okay, so we have talked about how to present ourselves to the community using the profile README. But part of being in a community is supporting others. Let us talk about GitHub Sponsors. What exactly is it?

-

Alex: GitHub Sponsors is a feature that allows you to financially support the developers and projects that you depend on. If you are familiar with platforms like Patreon, where you can subscribe to support an artist or creator, GitHub Sponsors is exactly like that, but built directly into GitHub for open-source maintainers.

-

Jamie: That makes a lot of sense. Because so much of the software we use every day, even the tools that run the internet, are built by volunteers working in their free time.

-

Alex: Exactly. Many open-source maintainers spend twenty, thirty, or even forty hours a week managing pull requests, fixing bugs, and writing documentation, completely unpaid. GitHub Sponsors was created to help make open-source more sustainable. When you sponsor someone, you usually choose a monthly tier, like five dollars, ten dollars, or twenty-five dollars a month. And the best part is that GitHub covers all the payment processing fees, so one hundred percent of your sponsorship goes directly to the developer.

-

Jamie: That is incredible. So if I am using an open-source screen reader add-on, and it saves me hours of work every week, I could set up a five-dollar monthly sponsorship just to say thank you. How do I actually do that?

-

Alex: It is very straightforward. When you navigate to a user's profile page, or to a specific repository, you can explore the page by pressing the B key on your keyboard to jump between buttons. If that developer has opted into the program, you will eventually land on a button called Sponsor. It usually has a little heart icon next to it for sighted users.

-

Jamie: And when I activate that Sponsor button?

-

Alex: It takes you to their Sponsor profile. There, you can read about why they are seeking sponsorship, and you can navigate through the different payment tiers they have set up. You choose a tier, enter your credit card or PayPal information, and you are done. Your sponsorship will then show up on your own profile page under a Sponsors tab, which is a nice way to publicly show your support for the community, though you can also choose to sponsor privately.

-

Jamie: Some developers offer perks too, right? Like early access to new features or a private chat server for sponsors?

-

Alex: Yes, they can! It is entirely up to the maintainer. Some offer priority bug fixes, others offer one-on-one mentoring, and some just offer their deep gratitude.

-

Jamie: So, flipping the script. What if I am the one building something useful? Can I receive sponsorships?

-

Alex: Absolutely. If you maintain an open-source project, or even if you just contribute regularly to other projects, you can set up a sponsor profile. You navigate to github dot com slash sponsors, and you select the button to join the waitlist or set up your profile. You will need to connect a bank account or a Stripe account so GitHub can send you the funds. Then, you create your tiers and write a description of your work.

-

Jamie: I want to highlight this for our listeners because I know several blind developers who use GitHub Sponsors to fund their accessibility advocacy. They spend hours testing open-source software with screen readers, filing detailed bug reports, and submitting pull requests to fix focus management or ARIA labels. That is incredibly valuable work, and setting up a Sponsors page is a great way to let the community compensate you for that labor.

-

Alex: I am so glad you brought that up, Jamie. Accessibility work is highly specialized, and it absolutely deserves financial support. If you are doing that work, do not be shy about setting up a Sponsors profile and sharing the link in your pull requests or on social media.

-

Jamie: All right, we have covered profiles and sponsors. Let us move to the third topic for today, which brings us back to repositories. GitHub Wikis. I know what Wikipedia is, but what is a GitHub Wiki?

-

Alex: Every repository on GitHub has the option to enable a Wiki. A Wiki is a space for documentation that lives alongside your code, but is kept separate from the code itself. It is entirely text-based, written in Markdown, and is designed to be a lightweight, multi-page reference guide for your project.

-

Jamie: Wait, why would I need a Wiki if I already have a README file? I thought the README was the documentation.

-

Alex: That is a great question. Let us use an analogy. Think of your repository as a workshop where you build furniture. The README file is the welcome mat and the directory poster on the front door. It tells people what the workshop is, what tools are inside, and gives them a quick start guide to building their first chair.

-

Jamie: Okay, so the README is the quick summary.

-

Alex: Right. But what if you have a fifty-page manual on the specific types of wood you use, a troubleshooting guide for the table saw, and a frequently asked questions section about varnishes? If you put all of that on the front door, the poster would be a mile long. Nobody would read it. That is where the Wiki comes in. The Wiki is the filing cabinet or the reference library inside the workshop. It is meant for deep, multi-page documentation.

-

Jamie: That makes perfect sense. So the README gets them started, and the Wiki gives them the deep dive. How do I actually access a Wiki?

-

Alex: When you navigate to any repository on GitHub, there is a navigation menu at the top of the page with tabs like Code, Issues, and Pull Requests. If the maintainer has enabled it, one of those tabs will be called Wiki. If you activate that tab, you are taken to the Wiki home page. If no pages exist yet, you will find a button that says Create the first page.

-

Jamie: And creating a page is pretty straightforward?

-

Alex: Very straightforward. When you activate the New Page button, you are given a simple form with two main fields. First, a text input for the page title. Second, a large text area for the page content. You write your content using the exact same Markdown syntax you use for issues and pull requests. Then, you move to the bottom of the page and activate the Save Page button.

-

Jamie: I assume I need to use good heading structure here too, right?

-

Alex: Always. Because Wikis often contain long articles, using clear heading levels is crucial for screen reader users to navigate the content. Another great feature of Wikis is that GitHub automatically generates a sidebar navigation menu with links to all the pages you create, so visitors can easily jump between different topics. And you can link between pages yourself. If you type two opening square brackets, the name of another Wiki page, and two closing square brackets, GitHub automatically creates a link to that page.

-

Jamie: That is really handy. But I have another question. Let us say I have a repository, and inside my code files, I just create a folder called docs, D O C S. And I put a bunch of Markdown files in there. How is a Wiki different from just having a docs folder in my code?

-

Alex: This is where we get into the architecture of GitHub. When you put documentation inside a docs folder in your main repository, it is version-controlled exactly like your code. If someone wants to change a typo in the documentation, they have to create a branch, make a commit, and open a pull request. The maintainer has to review it and merge it.

-

Jamie: Which is great for control, but maybe a bit heavy for a simple typo.

-

Alex: Exactly. A Wiki, on the other hand, is actually an entirely separate Git repository running quietly behind the scenes. By default, Wikis are designed to be community-editable. Depending on how the maintainer configures the settings, any GitHub user might be able to navigate to a Wiki page, activate the Edit button, make a change, and save it instantly, without going through a pull request review process.

-

Jamie: Oh, wow. So no pull requests, no branch protection rules. Just edit and save.

-

Alex: Yes. Which makes Wikis incredibly powerful for community-driven knowledge bases. If you have an active community of users, they can collectively maintain a list of frequently asked questions or community tutorials without bottlenecking the main developers with pull requests.

-

Jamie: But that also sounds a little risky for official documentation.

-

Alex: It is. And that is the primary caveat. Because changes to the Wiki bypass your branch protection rules and pull request reviews, you should not use a Wiki for your primary, critical, version-controlled documentation. If your documentation needs to be tied to specific versions of your software, you should use a docs folder or a tool like GitHub Pages. But if you want a collaborative scratchpad, a community FAQ, or a lightweight reference guide, the Wiki is the perfect tool.

-

Jamie: This has been a really refreshing episode. It is nice to zoom out from the command line and think about the community aspects of open source.

-

Alex: I completely agree. The tools are only as good as the people using them, and these features help us connect as humans. Let us recap our key takeaways for today. First, you can create a custom profile README by creating a public repository with the exact same name as your GitHub username. This acts as your developer business card.

-

Jamie: Second, keep that profile README accessible. Use proper headings, include alt text for images, and please, skip the ASCII art and those noisy SVG stat badges. Keep it authentic and readable.

-

Alex: Third, GitHub Sponsors is a powerful way to financially support the maintainers who build the open-source tools you rely on. It is also a platform you can use to receive funding for your own contributions, including critical accessibility advocacy.

-

Jamie: And finally, GitHub Wikis provide a separate, multi-page reference library attached to your repository. They use Markdown and are great for community-editable guides, but remember they bypass the standard pull request review process.

-

Alex: Perfect summary, Jamie. You now have the tools to build your presence, support your peers, and document your projects. In our next episode, we are going to look at how teams organize themselves on GitHub. We will be covering GitHub Organizations and Repository Templates, which are essential when you start collaborating with larger groups.

-

Jamie: I cannot wait to dive into that. Thank you all for listening, and we will catch you in the next episode!

-

Alex: Happy coding, everyone. Keep building, and keep sharing.

-
- - -

Episode 36: Organizations and Templates

-

GitHub Organizations, repository templates, visibility, and archiving.

-

Based on: Appendix S: Organizations and Templates

- - -

Download Episode 36 (MP3)

-
-Read Transcript - Episode 36: Organizations and Templates - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode 36, Organizations and Templates. I am your host, Alex, and as always, I am here to help you navigate the world of version control and open source collaboration.

-

Jamie: And I am Jamie. I am here to ask all the questions that you are probably thinking as you listen. I started learning GitHub about two years ago, and I still remember how wild it felt to move past just hosting my own small projects. Today, we are graduating. We are moving from single player mode into massive multiplayer mode.

-

Alex: That is a perfect way to describe it. In our previous episodes, we have spent a lot of time talking about personal accounts. We covered how to create your own repositories, how to fork someone else's repository, and how to create a pull request, which is when you request that someone pull your changes into their project. But if you look at a massive open source project, or if you get a job working as a developer at a company, they are not just hosting all their code on one person's personal account.

-

Jamie: Right. It would be pretty funny if the entire infrastructure of a massive company was just sitting on an account called cool coder ninety nine.

-

Alex: Exactly. And that brings us to our first major concept for today, which is the GitHub Organization. A GitHub Organization is a shared account designed for groups of people. It is a completely different type of account from your personal user account.

-

Jamie: So, how should I think about the difference between my personal account and an organization account?

-

Alex: I like to use a real estate analogy for this. Think of your personal GitHub account like your personal apartment. You are the only person who holds the master key. You decide what goes on the walls, you decide who is allowed to visit, and everything in it belongs to you. A GitHub Organization is more like an office building. It is a shared space. It has a name on the outside of the building, and inside, there are many different people working together. The assets, which are the repositories, belong to the organization itself, not to any one single person.

-

Jamie: That makes a lot of sense. And I know this changes the web address too. My personal repositories live at github dot com slash my username slash the repository name. But for an organization, it uses the organization's name in that middle spot. For example, the project we use in our workshop lives at github dot com slash community dash access slash accessibility dash agents. In that address, community dash access is the organization.

-

Alex: Spot on. Now, anyone can create an organization, and you might be wondering about the cost. Creating a GitHub Organization can be completely free, or it can be a paid plan.

-

Jamie: I always get a little nervous when I hear the word paid. If I want to start an open source community with a few friends, do I need to pull out my credit card?

-

Alex: Not at all. The free tier for organizations is incredibly generous and is designed specifically to support open source communities. You can have unlimited public and private repositories, and you can invite as many members as you want. The paid plans are really for businesses and enterprises. The paid plans add features like advanced auditing, single sign on integration so employees can log in with their corporate credentials, and highly specific access controls. But for almost any community project, the free tier is exactly what you need.

-

Jamie: Okay, so let us say I create an organization for my friends and me. We have this virtual office building now. How do we manage who gets to do what? Because in my personal apartment, I am the boss. But in an office building, you usually have different people with different jobs.

-

Alex: That is where Organization Roles come into play. When you invite someone to join your organization, you have to assign them a role. The three main roles you need to know about are Owner, Member, and Billing Manager.

-

Jamie: Let me guess. The Owner is the person who holds the keys to the entire building.

-

Alex: Exactly. Owners have complete administrative control over the organization. They can delete the organization, they can remove other members, and they can change any setting. You usually want to keep the number of owners very small. Then you have the Member role. This is the standard role for almost everyone else in the organization. Members can create repositories, they can collaborate on projects, and they can be assigned to specific teams. Finally, there is the Billing Manager. This role is strictly for the person paying the bills. A Billing Manager can update credit card information and view receipts, but they do not get access to the code. Think of them as the accountant for the building. They can access the financial office, but they cannot walk into the engineering labs.

-

Jamie: I love that. The accountant does not need to see my messy code anyway. So, if I am a standard member, how do I actually join? Does someone just add me and suddenly I am in?

-

Alex: An owner has to invite you. When they do, you will receive an email and a notification inside GitHub. You have to explicitly accept the invitation. You can navigate to github dot com slash settings slash organizations to accept it, or just open the link in your email.

-

Jamie: I want to share a quick story about this, because I was so confused by this when I first joined an organization. I got the invite, I accepted it, and I was so proud. I immediately went to my public GitHub profile page to see the organization badge shining on my profile. But it was not there. I thought I did something wrong.

-

Alex: That is a very common experience. By default, when you join an organization, your membership visibility is set to private. That means only you and the owners of the organization can see that you are a member. To the rest of the outside world, you are invisible.

-

Jamie: Which is great for privacy, but terrible for my ego.

-

Alex: Exactly. If you want people to know you are part of that community, you have to navigate to your organization settings and manually change your membership visibility from private to public. Once you do that, the organization's logo will appear on your public profile.

-

Jamie: Okay, so we have our office building, we have our owners, and we have our members. But what happens when the organization gets really big? Like, hundreds of members. How do you keep track of who is working on what?

-

Alex: That is where Teams come in. Teams within organizations allow you to group members together based on their role or their project. Staying with our office analogy, if the organization is the building, teams are the different departments. You might have a design department, a security department, and an accessibility review department.

-

Jamie: And this actually solves a problem I used to run into. Sometimes I would open a pull request, and I needed someone with screen reader expertise to review my code. Before I knew about teams, I had to guess who to ask, or I would just mention the one person I knew. Which meant that one poor person got pinged every single time I needed a review.

-

Alex: Yes, that is a quick way to burn out your volunteers. Teams solve this beautifully. An organization owner can create a team, let us call it accessibility dash reviewers, and add five people to it. Then, when you open your pull request, you do not need to mention a specific person. You just type the at symbol, followed by the organization name, a forward slash, and the team name. So you would type at community dash access slash accessibility dash reviewers. GitHub will automatically notify everyone on that team that a review is requested.

-

Jamie: That is so clever. It distributes the workload. As a contributor, I do not usually have permission to create teams, right?

-

Alex: Usually not. Creating teams is generally reserved for owners or specific team maintainers. But as a contributor, you need to understand what teams are so that you know why you are suddenly getting notifications when a team you belong to is mentioned, and so you know how to request reviews from teams yourself.

-

Jamie: Let us talk about the repositories inside these organizations. In my personal account, a repository is either public, meaning anyone on the internet can see it, or private, meaning only I can see it unless I invite someone. Does an organization have those same options?

-

Alex: Yes, but organizations get one additional option. Repository visibility in organizations can be public, private, or internal.

-

Jamie: Internal? How is that different from private?

-

Alex: Let us go back to our analogies. A public repository is like a public park. Anyone can walk in, sit on a bench, and look around. You do not even need a GitHub account to read the code in a public repository. A private repository is like a locked room inside the office building. Only specific people who are explicitly handed a key to that exact room can get in. Even if you work in the building, if you do not have a key to that room, you cannot see it.

-

Jamie: Okay, so where does internal fit in?

-

Alex: An internal repository is like the company breakroom. It is completely hidden from the outside public, but anyone who is a member of the organization can walk in. You do not need a special invitation to that specific repository. If you are in the organization, you can see all the internal repositories. This is incredibly useful for companies that want to share code freely among their own employees, but do not want that code leaked to the public internet.

-

Jamie: That makes perfect sense. For our listeners using screen readers, how do we actually know what the visibility of a repository is when we land on the page?

-

Alex: When you open a repository page, the visibility badge is displayed very prominently at the top of the page. For screen reader users, the easiest way to find this is to press the number one key to navigate to the main heading level one, which is the repository name. Right next to that heading, your screen reader will announce a label that says Public, Private, or Internal. It is usually the very next element in the reading order.

-

Jamie: Okay, let us shift gears a bit. We have talked about how to organize people and control visibility. But I want to talk about actually creating new projects. In the past, I have always just created a blank repository and started from scratch. But I have been seeing this button lately called Use this template. It sits right next to the Fork button. And honestly, it confuses me. What is a repository template, and how is it different from a fork?

-

Alex: This is a fantastic question, and it is a point of confusion for almost every developer when they first encounter it. Let us break it down. A repository template is a special status that a maintainer can apply to a repository. It turns that repository into a starting point, or a boilerplate, for new projects.

-

Jamie: So how is that different from forking? Because when I fork a repository, I am also getting a copy of someone else's project to use as a starting point.

-

Alex: The difference is all about the history and the future relationship between the projects. Let us use an analogy. Forking a repository is like taking a collaborative document and making a linked copy. You get the entire revision history of every change ever made to that document. And more importantly, a fork maintains a permanent umbilical cord back to the original project. The whole purpose of a fork is that you plan to make changes and send those changes back up to the original owner via a pull request.

-

Jamie: Okay, so a fork is for contributing back. What about a template?

-

Alex: A template is like buying a cookie cutter, or a blank piece of official stationery. When you use a template, you are creating a brand new repository that stamps out a copy of the files, the folders, and the structure. But it strips away all of the commit history. You start completely fresh with a clean slate. And there is no umbilical cord. Your new repository has absolutely no connection to the template it came from. You cannot easily open a pull request back to a template. You use a template when you want to start your own distinct project, but you do not want to spend two hours setting up the basic folder structure and configuration files.

-

Jamie: Oh, that is huge. The commit history part is the real differentiator. With a fork, I get thousands of old commits from the original authors. With a template, commit number one is just me creating the project.

-

Alex: Exactly.

-

Jamie: So, what actually transfers over when I use a template? Is it just the main branch?

-

Alex: By default, yes. When you use a template, GitHub creates a new repository containing all the files and folders from the template's default branch. It does not transfer issues, it does not transfer pull requests, and it does not transfer repository settings or branch protection rules. It just gives you the files so you can get to work. However, there is a checkbox you can select during the creation process that says include all branches. If you check that, it will copy the files from all the branches, but again, without the commit history.

-

Jamie: OK that sounds like a lot of steps to set up. How do I actually use a template if I find one?

-

Alex: It might sound like a lot, but it does! But here is the thing - you have already done most of this on day one of your GitHub journey. It is the exact same workflow as creating a standard repository, just with GitHub handling the heavy lifting of copying the files for you. To use a template, you simply navigate to the template repository. Near the top of the page, right next to the Code button, there is a button labeled Use this template.

-

Jamie: For screen reader users, what is the fastest way to get to that button?

-

Alex: The quickest way is to press the letter B to navigate through the buttons on the page. Once you hear Use this template, press Enter. That will open a dropdown menu. Use your down arrow key to navigate to the option that says Create a new repository, and press Enter again. From there, you will be taken to a page that looks almost identical to the standard new repository page. You give it a name, you choose whether it should be public or private, and you confirm. Within seconds, you have a brand new repository fully populated with the template files.

-

Jamie: That is incredibly smooth. What if I want to be the one providing the cookie cutter? How do I turn one of my own repositories into a template so other people can use it?

-

Alex: It is literally one checkbox. You must have maintainer or owner access to the repository to do this. You navigate to the repository, open the Settings tab, and stay on the General page. If you navigate down through the page, you will find a checkbox labeled Template repository. Just check that box. The moment you do, the Use this template button will appear for anyone who visits your repository.

-

Jamie: Alright, we have covered how to build the office building, how to assign the teams, and how to stamp out new projects using templates. Let us talk about the end of a project's lifecycle. Sometimes projects die. Or they finish, which is a nicer way to think about it. I have noticed sometimes I land on a repository and my screen reader announces a big warning banner that says the repository has been archived. What does archiving a repository mean, and why do maintainers do it?

-

Alex: Archiving a repository is a way of officially retiring a project while preserving its history. Think of it like taking a historical document and placing it inside a glass display case at a museum. People can walk up to the glass, they can read the document, and they can even take a picture of it. But they cannot touch it, and they definitely cannot edit it with a pen.

-

Jamie: So it becomes completely read only?

-

Alex: Exactly. When a repository is archived, no one can open new issues, no one can submit new pull requests, and no one can add new comments to existing discussions. Even the repository owners cannot push new code to it unless they unarchive it first.

-

Jamie: Why not just delete the repository if the project is over? Why leave it up in a glass case?

-

Alex: Because in the open source world, history is incredibly valuable. Even if a piece of software is no longer being updated, thousands of people might still be using it. Or developers might want to look at the code to see how a specific problem was solved. Deleting a repository breaks links, destroys historical context, and frustrates the community. Archiving is the responsible way to say, we are no longer maintaining this, do not expect any bug fixes, but we are leaving the code here for educational purposes.

-

Jamie: That makes a lot of sense. If I am a screen reader user, how do I know if I have stumbled into a museum? Because I do not want to spend an hour reading a codebase only to realize I cannot contribute to it.

-

Alex: GitHub puts a prominent yellow banner at the very top of the page. When you navigate to an archived repository, I highly recommend pressing Control plus Home to jump to the very top of the web page, and then use your down arrow to read the first few lines. Your screen reader will read the banner text, which says, This repository has been archived by the owner on, and then it gives the date. It is usually the very first major piece of text before the repository name. If you hear that, you know you are looking at a retired project.

-

Jamie: If I really love an archived project, can I still fork it?

-

Alex: Yes, you can! You can fork an archived repository and continue the work on your own account. In fact, if you find a repository that you planned to contribute to is archived, the best thing to do is to check the network graph or search GitHub to see if someone else has already forked it and created a successor project.

-

Jamie: We have one last topic to cover today, and this is one that genuinely intimidated me the first time I had to do it. Transferring repository ownership. Sometimes you build a project on your personal account, it gets really popular, and you decide to move it into an organization. How does transferring work, and is it as scary as it feels?

-

Alex: It is totally normal to feel intimidated by this. Transferring a repository is like handing over the deed to a house. You are giving full control of the project to someone else, or to an organization. But GitHub has built in several safety nets to ensure you do not do this by accident.

-

Jamie: What actually happens to the repository when it moves? Do all the links break?

-

Alex: No, and that is the magic of GitHub's transfer system. When you transfer a repository, GitHub automatically sets up a redirect. If someone tries to visit the old web address on your personal account, GitHub smoothly redirects them to the new address in the organization. It also transfers all the issues, the pull requests, the commit history, and the stars. Everything moves over intact.

-

Jamie: That is a relief. So how do I actually execute the transfer?

-

Alex: You navigate to the Settings tab of your repository, scroll all the way to the bottom to the Danger Zone. That section is literally called the Danger Zone, and it is usually marked by a heading level two. In that section, you will find a button to Transfer ownership. When you activate that button, GitHub will ask you to type the name of the new owner or organization.

-

Jamie: And this is where the safety net comes in, right?

-

Alex: Yes. GitHub will force you to manually type out the full name of the repository you are transferring just to confirm. You cannot just accidentally click a button and lose your project. You have to explicitly type out the name to prove you are paying attention. Once you confirm, the new owner receives an email, and they must accept the transfer. The repository does not actually move until they say yes.

-

Jamie: That is really good to know. The typing confirmation definitely makes me feel better. It is like the digital equivalent of being asked, are you sure, are you really sure, okay, sign here.

-

Alex: Exactly. It is designed to make you pause and think.

-

Jamie: Wow. We covered a massive amount of ground today. We moved out of the personal apartment and into the corporate office building.

-

Alex: We did. Let us summarize the key takeaways for today. First, GitHub Organizations are shared accounts designed for communities and companies. They allow you to group people into teams, which makes requesting reviews and managing permissions much easier.

-

Jamie: Second, organization repositories have an extra visibility option called internal. This is like the company breakroom. It is hidden from the public internet, but visible to everyone who is a member of the organization.

-

Alex: Third, repository templates allow you to stamp out new projects with a clean commit history. Remember, a fork keeps the history and the connection to the original project because you want to contribute back. A template gives you a fresh start with no strings attached.

-

Jamie: And finally, archiving a repository puts it in a read only museum display case. It preserves the history without allowing new changes. If you are using a screen reader, press Control plus Home when you load a repository page to check for that archived warning banner at the top of the page.

-

Alex: Perfect summary. You now have the conceptual foundation to navigate massive open source communities and corporate GitHub environments. In our next episode, episode 37, we are going to look at Issue Forms and Community Health Files. We will explore how maintainers use templates to guide contributors on exactly what information to provide when reporting a bug.

-

Jamie: I cannot wait. Those issue forms save so much back and forth communication.

-

Alex: They really do. Until then, keep exploring, keep practicing, and we will see you next time on Gitt Going with GitHub.

-
- - -

Episode 37: Contributing to Open Source

-

Finding issues, scoping contributions, the fork-to-PR workflow, and building habits.

-

Based on: Appendix T: Contributing to Open Source

- - -

Download Episode 37 (MP3)

-
-Read Transcript - Episode 37: Contributing to Open Source - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is Episode 37, Contributing to Open Source. I am Alex, and I am here with Jamie.

-

Jamie: Hello everyone! I am so excited for this episode. We are well into Day 2 of our GitHub workshop, and today we are talking about taking everything we have learned so far and actually putting it out into the world.

-

Alex: Exactly. Over the past few episodes, and throughout Day 1 of the workshop, we covered the core mechanics. We talked about branches, commits, and pull requests. We have set up our local environments. Now, we are going to talk about using those skills to collaborate on public open source projects.

-

Jamie: And I have to admit, when I first heard the phrase open source contribution, I was terrified. Before I learned GitHub a couple of years ago, I thought contributing to open source meant you had to be a professional developer with twenty years of experience, writing complex operating system code in C plus plus.

-

Alex: That is such a common misconception, and it keeps so many talented people from getting involved. The truth is, open source software is just software whose source code is publicly available. Anyone can read it, use it, and contribute to it. But the word code in source code makes people think that programming is the only way to contribute.

-

Jamie: Which is completely false!

-

Alex: Completely false. What counts as a contribution is so much broader than that. Writing or improving documentation is a massive contribution. Filing a clear, reproducible bug report is a contribution. Reviewing other people's changes, translating content, adding automated tests. All of these are essential to keeping a project healthy.

-

Jamie: I like to think of an open source project like a community garden. Yes, planting seeds is important, which would be like writing new features. But if nobody waters the plants, or fixes the broken lock on the front gate, or paints the signs so people know what is growing where, the garden falls apart. Writing documentation is painting those signs. Filing bug reports is telling the community that the gate is broken.

-

Alex: I love that analogy. And for our listeners, who are blind and low-vision developers, I want to emphasize something very specific. You possess a superpower in the open source world. Assistive technology users bring a perspective that the vast majority of sighted, mouse-first developers simply do not have.

-

Jamie: Oh, absolutely. When I navigate a webpage, I know immediately if the heading structure is broken. Or if I land on a form and my screen reader just says button, button, button, because there are no accessible names. A sighted developer using a mouse might never notice those missing labels because the buttons have visual icons on them.

-

Alex: Exactly. When you encounter a project with those issues, filing a bug report that explains exactly what your screen reader is announcing, and how it breaks your navigation, is a high-value contribution. Suggesting a fix, like adding an aria-label or fixing the heading levels, improves that project for everyone. You do not need anyone's permission to do this. If a repository's issues are public, you can suggest an improvement today.

-

Jamie: Okay, so let us say I am convinced. I want to help fix the garden. How do I actually find my first issue? Because there are millions of repositories on GitHub. It feels like looking for a needle in a haystack.

-

Alex: It does, but GitHub has specific tools to help you narrow it down. Most welcoming open source projects use labels to categorize their issues. When you are on a repository page, you can navigate to the Issues tab, and filter by these labels.

-

Jamie: And there are specific labels meant just for beginners, right?

-

Alex: Yes. The most common one is the label called good first issue. This label means the project maintainers have explicitly reviewed the task and decided it is a great starting point for someone who has never contributed to their project before. It usually means the problem is well-defined and does not require understanding the entire architecture of the software.

-

Jamie: Another one I always search for is the label help wanted. That usually means the maintainers know this is an issue, but they do not have the time to fix it themselves, and they are actively inviting community members to pick it up.

-

Alex: Right. You might also encounter labels like beginner, or easy, or first-timers-only. And do not forget labels that describe the type of work, like documentation or accessibility. If you want to start without writing code, filtering for the documentation label alongside good first issue is a brilliant strategy.

-

Jamie: What if I do not have a specific project in mind yet? Can I search across all of GitHub?

-

Alex: You can. You can use GitHub's global search. For example, if you type label colon quote good first issue quote, space, is colon open, space, language colon markdown. That search string will return open issues labeled as good first issue, specifically in repositories that use Markdown, which usually means documentation tasks. It is a fantastic way to find small typos or broken links to fix.

-

Jamie: So, I run my search, and I find an issue that sounds interesting. How do I know if the project itself is a good place to contribute? Because some communities are more welcoming than others.

-

Alex: That is a crucial question. Before you invest time in a project, you should evaluate the project and the community. First, check their activity. Navigate to the repository's main page and check when the last few commits were made. If the project has not been updated in four years, your contribution might sit there forever without being reviewed.

-

Jamie: I also like to read through a few recent issues or pull requests to gauge responsiveness. If people are opening issues and the maintainers are replying politely within a few days, that is a great sign. If people are asking for help and getting ignored, or worse, getting rude responses, I usually move on. There are plenty of finding communities that welcome new contributors, so there is no need to waste time on toxic ones.

-

Alex: Absolutely. Another major indicator of a welcoming community is a Code of Conduct. This is usually a file named CODE OF CONDUCT dot md. It outlines the community's standards for behavior and how they handle harassment or unacceptable behavior. A project that takes the time to establish and enforce a Code of Conduct is actively thinking about creating a safe space for contributors.

-

Jamie: And while we are talking about files in the repository, we have to mention the CONTRIBUTING dot md file.

-

Alex: Yes! Every project has different expectations. The contributing file is essentially the rulebook for that specific project. It tells you exactly how the maintainers want you to submit your work.

-

Jamie: Going back to analogies, it is like staying at a guest house. Before you start rearranging the kitchen, you should read the house rules left on the counter. The contributing file might tell you that they want commit messages formatted a specific way, or that you need to run a certain command to test your code before opening a pull request. Reading that file saves everyone a lot of time.

-

Alex: Let us talk about the issue itself. You found a welcoming project, you read the contributing file, and you found an issue labeled good first issue. Before you start typing, you need to read the issue carefully and scope your contribution.

-

Jamie: Scoping is so important. When I first started, I would find an issue about a broken link, and while I was in the file, I would decide to rewrite three paragraphs, fix some formatting, and reorganize the folders. And then my pull request would get rejected because it was too massive and touched too many things.

-

Alex: That is the classic trap! A good first contribution needs to be tightly scoped. Start small. Pick one thing. If the issue is about a broken link, fix only the broken link. One pull request, one problem.

-

Jamie: Exactly. If you are a plumber hired to fix a leaky faucet, you do not decide to spontaneously replumb the entire house without asking. It is too much to review.

-

Alex: A sign that a contribution is too large for a first attempt is if your proposed pull request touches more than three or four files, or if you feel like you need to understand the entire codebase just to make the change. A well-executed small contribution, like fixing a single typo, is infinitely more valuable than a massive contribution that never gets merged because it is too complex for the maintainers to review.

-

Jamie: Also, check the issue comments before you start. Is anyone else already working on it? Look for recent comments from other developers saying, I will take this, or check if there is an open pull request linked to the issue. If someone else is actively working on it, you probably want to find a different issue to avoid duplicating effort.

-

Alex: If the coast is clear, and the issue makes sense, leave a brief, polite comment. Something like, I would like to work on this, I will open a draft pull request shortly. This claims the issue and lets the maintainers know you are on it.

-

Jamie: Alright, we have claimed the issue. Now we have to actually do the work. OK, this part sounds like a lot of steps when you first hear it.

-

Alex: It does! But here is the thing. You have already done most of this on Day 1 of the workshop. It is the exact same workflow, just with one extra step at the beginning because we are working across different accounts. Let us walk through the contribution workflow end to end.

-

Jamie: Step one is the new part. We have to fork the repository.

-

Alex: Right. Because you do not have write access to someone else's public project, you cannot just create a branch directly on their repository. So, you navigate to their repository on GitHub, and activate the Fork button. A fork is simply a complete copy of their repository that lives under your own GitHub account.

-

Jamie: I like to think of a fork like copying a recipe card. The original author has their recipe for chocolate chip cookies in their recipe box. You cannot go into their house and write on their card. But you can make a photocopy, put it in your own recipe box, and then make all the notes and changes you want.

-

Alex: Perfect analogy. So, you fork the repository. Step two is to clone your fork to your computer, or open it in a GitHub Codespace. Cloning is just downloading that recipe from your GitHub account down to your local workspace.

-

Jamie: Step three, we create a branch. We learned this on Day 1. You never work directly on the main branch. You create a new branch with a descriptive name, like fix slash broken dash link. You can do this in the terminal, or by opening the command palette in VS Code by pressing Control plus Shift plus P, and typing Git Create Branch.

-

Alex: Step four, you make your change. You open the file, you edit the broken link, you save the file, and you test it with your screen reader to make sure it reads correctly.

-

Jamie: Step five, we commit the change. Again, Day 1 stuff. We stage the file, and write a clear commit message. Not just fixed stuff, but fixed broken link in setup guide.

-

Alex: Step six, you push the branch. This sends your saved changes from your local computer back up to your fork on GitHub.

-

Jamie: And finally, step seven. The grand finale. You open a pull request. You navigate back to the original repository on GitHub, and GitHub will usually display a banner recognizing your recent push, with a button to Compare and pull request. You activate that, and you are literally requesting that the maintainer pull your changes from your recipe box back into their original recipe box.

-

Alex: When you reach that pull request screen, you need to write a description. Writing a pull request description that maintainers will appreciate is an art form. You are handing them a piece of work to review, and they might have zero context about who you are or what you are doing.

-

Jamie: A good pull request description should answer three questions. What, Why, and How.

-

Alex: Exactly. What did you change? Why was the change needed? And how did you verify it works?

-

Jamie: So instead of just writing, I fixed the link, you would write, Fixed a broken link on line thirty four of setup guide dot md. The link pointed to an old setup page that no longer exists. I updated it to the new pre workshop setup page. I verified the target file exists and the anchor link routes correctly.

-

Alex: If I am a maintainer, and I read that description, I can approve your pull request almost instantly. You have given me all the confidence I need that your change is safe and correct.

-

Jamie: But what if they do not approve it instantly? What if they leave a comment asking me to change something? I remember my first pull request, the maintainer asked me to reword a sentence. I felt like I had failed the test. I thought they were rejecting my work.

-

Alex: That is such a natural reaction, but it is so important to reframe that. Responding to review feedback is not a rejection. It is collaboration. It is totally normal for a maintainer to ask for tweaks. Think of them like an editor at a newspaper. You submitted an article, and they are just doing a quick copy edit before it goes to print.

-

Jamie: So when they ask for a change, do I have to start the whole process over? Do I close the pull request and make a new one?

-

Alex: No, and this is the magic of Git. Your pull request is tied to your branch. If a maintainer asks for a change, all you do is go back to your editor, make the change they requested, save the file, commit the change, and push it to your branch again. The pull request on GitHub automatically updates with your new commit.

-

Jamie: That was a huge aha moment for me when I learned that. You just keep pushing to the same branch, and the conversation continues in the pull request until everyone is happy.

-

Alex: And remember, assume good intent. Maintainers are often volunteers managing these projects in their spare time. If they are brief, or if they take a week to reply, it is usually just because they are busy. If you are waiting for a review, it is completely appropriate to leave one polite follow up comment after a week or two, just saying, Hi, checking in on this when you have a moment.

-

Jamie: So, the maintainer reviews it, they approve it, and they merge it. What happens next?

-

Alex: When your pull request is merged, your name is permanently added to the project's commit history. The issue is closed, and you are officially listed as a contributor to that project. This record is publicly available on your GitHub profile. It demonstrates that you know how to scope a problem, communicate with a team, address feedback, and deliver a solution.

-

Jamie: It feels amazing. But the hardest part is definitely just starting. Getting that first one merged. Once you do it once, you realize the workflow is totally manageable. So how do we build a sustainable contribution habit after this workshop ends?

-

Alex: The best way is to set a low bar. Do not pressure yourself to build major features. Keep a list of open source tools, screen readers, or libraries you use every day. When you find a typo in their documentation, fix it right then. If you run into a bug, take fifteen minutes to write a clear, reproducible bug report. A bug report is a real contribution.

-

Jamie: And another great way to build the habit is by continuing to learn. Which brings us to a fantastic resource that is completely free, highly accessible, and lets you practice all of this in a safe environment. GitHub Skills.

-

Alex: Yes, we need to talk about GitHub Skills. This is GitHub's self-paced interactive learning platform. What makes it unique is that there is no external website, no separate login, and no videos to watch. Every course runs entirely inside GitHub.

-

Jamie: It is so cool. When you start a course, GitHub copies a training repository into your own account. And then, an automated bot named Mona becomes your teacher. Mona will open an issue in your repository with instructions for step one.

-

Alex: And because it all happens through standard GitHub issues and pull requests, the screen reader navigation skills we have practiced apply perfectly. You use your heading navigation to jump through Mona's instructions. You navigate to the code tab to make your changes. When you complete a task, like opening a pull request, Mona automatically detects it, validates your work, and posts the next step as a comment.

-

Jamie: We actually use three of these courses during Day 1 of the workshop. Introduction to GitHub, Communicate Using Markdown, and Review Pull Requests. But there are over thirty courses available in the GitHub Skills catalog, organized into learning paths.

-

Alex: Exactly. If you want to continue structured learning after Day 2, you can choose a path that matches your goals. For example, Path 1 covers Git Fundamentals. It includes a great short course on resolving merge conflicts, which is a skill every developer needs to practice.

-

Jamie: Path 2 focuses on GitHub Collaboration. That is where you learn repository management, setting up branch protection, and using GitHub Pages to host a website. If you want to get deep into open source maintainership, that is the path for you.

-

Alex: There is Path 3 for GitHub Actions and Automation, where you learn to build automated workflows to test your code. And Path 4 is all about GitHub Copilot. It teaches you how to use AI-assisted development, from basic code completion to using Copilot's agent mode and building custom extensions.

-

Jamie: And the best part is, you can take your time. Each course takes maybe thirty to sixty minutes. You can track your progress by keeping a list of the courses you have completed. All the links are available in Appendix Z of the workshop materials.

-

Alex: We have covered a lot of ground today. Let us wrap up with some concrete takeaways for contributing to open source. First, remember that code is only one type of contribution. Documentation, bug reports, and accessibility reviews are incredibly valuable and desperately needed.

-

Jamie: Second, start small. Search for issues labeled good first issue or help wanted, and scope your work tightly. One problem, one pull request. Do not try to replumb the whole house.

-

Alex: Third, respect the project's workflow. Evaluate the community for a Code of Conduct, read the contributing rules, and write clear pull request descriptions explaining what you changed, why, and how you tested it.

-

Jamie: And finally, embrace feedback. When a maintainer asks for changes, they are collaborating with you, not rejecting you. Just make the change, commit, and push back to your branch.

-

Alex: That is exactly right. Build the habit by starting with GitHub Skills, fixing small things, and participating in communities you already use.

-

Jamie: I cannot wait to see what everyone contributes. So, what is coming up in our next episode?

-

Alex: In Episode 38, we are shifting gears. We will be diving deep into GitHub Actions. We are going to demystify continuous integration and continuous deployment, and show you how to automate your testing and workflows so the robots do the heavy lifting for you.

-

Jamie: Oh, I love making the robots do the work. That is going to be a fun one.

-

Alex: It really is. Thank you all for listening to Gitt Going with GitHub. We will see you in the next episode!

-
- - - -

Tools, references, communities, and continued learning paths.

-

Based on: Appendix U: Resources and Links

- - -

Download Episode 38 (MP3)

-
-Read Transcript - Episode 38: Resources and Links - -

Transcript

-

Alex: Welcome back to Gitt Going with GitHub. This is episode 38, called Resources and Links. I am Alex, your lead host, and as always, I am joined by Jamie.

-

Jamie: Hello everyone. We are getting toward the end of our two-day workshop material, and I have to admit, my brain is feeling a little bit full. We have covered issues, pull requests, merge conflicts, Copilot, VS Code, and custom agents. It is a massive amount of information.

-

Alex: It really is, Jamie. And if you are listening to this and feeling slightly overwhelmed, I want to completely normalize that. It is a lot of steps. It is a whole new vocabulary. But here is the thing, you have already done the hardest part. You have built the mental model. You understand how these pieces fit together. Now, it is just about having the right references so you do not have to memorize every single command or keyboard shortcut.

-

Jamie: That is a relief. Because I definitely do not have every shortcut memorized yet. When I learned GitHub about two years ago, I spent half my time just trying to figure out where to go when I got stuck. It felt like walking into a massive library without a card catalog.

-

Alex: Exactly. And that is exactly what this episode is for. We are going to build your personalized card catalog. We are covering every tool, link, and community reference mentioned in this workshop, plus where to go for help after the workshop ends. We will talk about official documentation, continued learning paths, and how to find accessibility-focused open source projects to contribute to.

-

Jamie: So, where do we start? Do I need to bookmark fifty different websites right now?

-

Alex: No, actually, you only need one. The central project repository from this workshop. The Accessibility Agents repository that you forked on Day 1. That is your permanent reference.

-

Alex: Let us talk about that fork. When you fork a repository, you are making your own personal copy of the project on GitHub. But the real magic happens when you bring it down to your own computer. We call that cloning. Cloning is creating a local copy of a repository on your own hard drive.

-

Jamie: Right, so if I clone my fork of the Accessibility Agents repository, I have all the code, but I also have all the documentation we have been using.

-

Alex: Precisely. Every guide, every cheat sheet, every appendix from this workshop lives in a folder called docs inside that repository. Once you clone it, that documentation works completely offline. Think of it like downloading a comprehensive survival guide before you go off the grid into the wilderness. Even if you have no internet connection, you can open the folder in VS Code, use your screen reader to navigate the markdown files, and read up on how to resolve a merge conflict or how to write an issue template.

-

Jamie: That is incredibly useful. I fly a lot, and having offline access to reference material when I am stuck on an airplane without Wi-Fi is a lifesaver. So the first resource is literally the project we just built. What is next?

-

Alex: Next, we need to talk about the official GitHub documentation. But not just the general documentation. I want to highlight the screen reader-specific GitHub guides created by the GitHub Accessibility team.

-

Jamie: Oh, I love these. The general GitHub documentation is great, but it is massive. It covers every edge case for enterprise administrators and security teams. But sometimes I just want to know the most efficient way to read a diff with NVDA or JAWS.

-

Alex: Exactly. Reading generic documentation as a screen reader user can sometimes feel like asking for directions and being handed a topographical map of the entire state. What you actually want is a local tour guide who uses a white cane, someone who can tell you exactly how many steps to take and where the curbs are. That is what the GitHub Accessibility guides are.

-

Jamie: What kind of topics do they cover?

-

Alex: They have specific guides for navigating repositories, working with issues, managing pull requests, and using GitHub Copilot in VS Code. And what makes them brilliant is that they do not just tell you what a feature does. They tell you the exact keyboard shortcuts to use. Instead of saying, move your mouse to the top right corner and look for the green button, they will tell you to press the letter G then the letter I to navigate to the Issues tab, or to press the letter C to create a new issue.

-

Jamie: That is so much better. They also explain the heading structure, right? Like, they will tell you that the main content starts at a heading level 1, and the comments are all heading level 3s.

-

Alex: Yes, they map out the digital architecture for you. If you are reviewing a pull request, which, as a quick refresher, is when you are requesting that someone pull your code changes into their project, the screen reader guide will tell you exactly how the code changes are presented. It explains how to use your screen reader's browse mode to jump between the added lines and the removed lines without getting lost in the layout tables.

-

Jamie: I wish I had known about those guides when I started. I spent a lot of time just pressing the Tab key and hoping for the best.

-

Alex: Let us move on to how you can continue practicing these skills. Reading documentation is one thing, but muscle memory comes from doing. That brings us to GitHub Skills.

-

Jamie: GitHub Skills! I am so excited to talk about this. This is completely different from a normal online course, right?

-

Alex: It is entirely different. GitHub Skills is GitHub's free, self-paced interactive learning platform. But here is the brilliant part. There are no videos to watch. There is no separate website to log into. Every course runs entirely inside GitHub itself. It uses something called the template-copy pattern.

-

Jamie: Can you explain the template-copy pattern? Because that sounds like enterprise jargon.

-

Alex: Fair point. Think of it like one of those interactive escape rooms, but for code. When you start a course on GitHub Skills, you press a button to use their template. This copies an entire pre-built repository into your own personal GitHub account. As soon as that repository is created, a bot named Mona automatically wakes up and opens a new Issue in your repository.

-

Jamie: Mona is the GitHub mascot, right? The little octopus with cat ears?

-

Alex: Yes, the octocat. So Mona opens an issue, and inside that issue are your instructions for step one. Let us say the course is about resolving merge conflicts. The issue will say, welcome to the course, your first task is to create a new branch and change a specific file.

-

Jamie: And you actually do that right there in the repository? You do not go to a simulated environment?

-

Alex: Exactly. You do the real task in the real environment. You edit the file, you commit the change. And when you do, GitHub Actions workflows are running in the background. Within about twenty seconds, Mona detects what you did. She checks if you did it correctly. If you did, she closes the issue and opens step two. If you made a mistake, she leaves a comment explaining what went wrong and asks you to try again.

-

Jamie: That is so cool. It is like having a digital mentor sitting over your shoulder, but it is completely asynchronous. And from an accessibility standpoint, it means you are using the exact same interface you will use for real work. You are practicing navigating issues, reading comments, and creating pull requests using your screen reader in the actual GitHub web interface.

-

Alex: Exactly. To navigate a course, you just use the skills we learned in the workshop. You press G then I to navigate to your Issues tab. You press the letter H or the number 3 to find the issue heading, press Enter to open it, and use your down arrow in Browse Mode to read Mona's instructions. When you complete the task, you just wait a moment, and your screen reader will announce when Mona posts a new comment.

-

Jamie: What courses do they have? Where should someone start after this workshop?

-

Alex: If you want to reinforce what we learned here, start with the Introduction to GitHub course. It takes less than an hour and covers branches, commits, and pull requests. Then, take the Review Pull Requests course. It teaches you how to leave comments, suggest changes, and approve code. And finally, I highly recommend the Resolve Merge Conflicts course. Merge conflicts are usually the scariest part for beginners, but practicing them in a safe, automated environment takes all the fear away.

-

Jamie: Okay, so GitHub Skills covers the GitHub side of things. But what about Git itself? Git is the underlying version control system that powers all of this, right? I still get confused sometimes between Git and GitHub.

-

Alex: That is a very common confusion. Here is the analogy I like to use. Git is the engine, and GitHub is the garage. Git is the actual software running on your computer that tracks the history of your files. GitHub is the collaborative platform on the internet where you store that history and work with other people. You can use Git without GitHub, but you cannot use GitHub without Git.

-

Jamie: That makes sense. So if I want to understand the engine better, where do I go?

-

Alex: The gold standard reference is the Pro Git Book. It is completely free and available online. It is the full engineering schematic of how Git works. Now, I will warn you, it is incredibly dense. You do not need to read it cover to cover like a novel. Use it like a dictionary or an encyclopedia. If you want to deeply understand how a specific command works, like git rebase, that is where you look.

-

Jamie: Is there anything more interactive for learning Git?

-

Alex: Yes, there is a fantastic resource called Learn Git Branching. It is an interactive tutorial that walks you through how branches work. As a reminder, branching is when you create a parallel universe of your code so you can experiment safely without breaking the main project.

-

Jamie: Wait, I have seen Learn Git Branching. It is highly visual. It draws little nodes and trees on the screen. Is that accessible for a screen reader user?

-

Alex: It is a mixed bag. They do have a command-line interface that you can interact with, which is readable, but the visual tree diagram is the main selling point, and that part is not conveyed well to screen readers. For our blind and low-vision listeners, I actually recommend leaning heavily on the official GitHub Git Cheat Sheet. It is a text-based PDF that lists every major Git command and explains exactly what it does in plain English. Keep that PDF open in a separate window, and practice the commands in your own VS Code terminal.

-

Alex: Speaking of VS Code, we need to talk about your local development environment. VS Code is like your personal physical workshop. When you walk into a physical workshop, you want your tools arranged exactly how you like them, so you can reach out and grab a screwdriver or a wrench without even looking.

-

Jamie: Right, and in VS Code, arranging your tools means setting up your keyboard shortcuts and configuring the accessibility settings.

-

Alex: Exactly. The first resource you need here is the official VS Code Accessibility documentation. Microsoft has done an incredible job building screen reader mode into VS Code. The documentation explains how to use features like the Accessible View, which lets you inspect hover text and error messages in a clean, screen-reader-friendly buffer.

-

Jamie: Oh, and Audio Cues! We talked about those in a previous episode, but the documentation lists all of them. Audio cues are those little sounds VS Code plays to tell you if a line has an error, or if a line was added or deleted in a diff, without you having to read the text.

-

Alex: Yes, the audio cues are fantastic. The documentation also provides a complete list of keyboard shortcuts for Windows and Mac. The most important shortcut to remember, the one that unlocks everything else, is the Command Palette. You open it by pressing Control plus Shift plus P on Windows, or Command plus Shift plus P on Mac. From there, you can type any command you want, like open accessibility settings, and press Enter.

-

Jamie: So if the GitHub Accessibility guides are the tour guide for the website, the VS Code Accessibility documentation is the blueprint for organizing your digital workshop.

-

Jamie: Alex, what if someone wants to go beyond just learning Git and GitHub? What if they are a screen reader user who wants to learn how to code from scratch, or pick up a new programming language? Where should they go?

-

Alex: That is a great question. There are two incredibly strong, completely free, open-source learning paths that I always recommend. The first is freeCodeCamp, and the second is The Odin Project.

-

Jamie: I have heard of freeCodeCamp. It is massive.

-

Alex: It is. If GitHub Skills is where you learn how to use the kitchen tools, freeCodeCamp and The Odin Project are the culinary schools where you learn how to cook. They teach you HTML, CSS, JavaScript, Python, and more.

-

Jamie: Are they accessible? A lot of coding platforms rely on drag-and-drop exercises or visual puzzles that are completely broken with a screen reader.

-

Alex: Both of these platforms are heavily text-based and very screen-reader friendly. freeCodeCamp has an integrated editor on their website, and they have worked hard on its accessibility. The Odin Project takes a different approach. They do not use an in-browser editor at all. Instead, their curriculum guides you through setting up your own local environment using VS Code and the terminal, and you build real projects on your own computer.

-

Jamie: I actually love that approach. It forces you to learn the real tools from day one, rather than relying on a training wheels environment. And since you are using VS Code, you can use all the accessibility features we just talked about.

-

Alex: Exactly. Both of these platforms are also entirely open source, hosted on GitHub. If you ever find an accessibility bug in their curriculum, you can open an issue or even submit a pull request to fix it.

-

Jamie: That is a perfect transition. Let us talk about contributing. Once someone finishes this workshop, and maybe does a few GitHub Skills courses, how do they find real open source projects to contribute to? It feels like standing at the edge of the ocean. There are millions of repositories. Where do you even start?

-

Alex: You do not start by swimming into the deep end. You start at the bunny hill. Just like a ski resort has a gentle slope for beginners, the open source community has curated lists of beginner-friendly tasks.

-

Jamie: Like the Good First Issue label! We talked about that earlier in the workshop.

-

Alex: Yes. Maintainers use the Good First Issue label to mark tasks that are isolated, well-documented, and perfect for someone new to the project. But searching for them across all of GitHub can be tricky. So, I recommend using a website called goodfirstissue.dev, or another site called Up For Grabs. These websites aggregate issues from across the internet that are specifically tagged for beginners. They expect you to be new, and the maintainers are ready to help you learn.

-

Jamie: That is brilliant. But what if I specifically want to work on accessibility? Like, what if I want to use my lived experience as a screen reader user to make projects better?

-

Alex: Your lived experience is a superpower in open source. Many sighted developers genuinely want to make their projects accessible, but they do not know how to test them properly. You are the domain expert.

-

Jamie: So how do I find those projects?

-

Alex: You use GitHub Advanced Search. You can search for specific topics. Topics are tags that maintainers add to their repositories to describe what the project is about. If you go to the GitHub search bar and type topic colon accessibility, or topic colon assistive dash technology, you will find thousands of public repositories focused exactly on those areas.

-

Jamie: Oh, that is clever. So I could search for topic colon accessibility, and then filter by the label Good First Issue.

-

Alex: Exactly. You can combine search terms. You could search for is colon open, is colon issue, label colon help dash wanted, and topic colon screen dash reader. That query will give you a list of open issues where maintainers are explicitly asking for help with screen reader compatibility. It is a fantastic way to find projects where your specific skills are desperately needed.

-

Alex: Finally, we need to talk about community. Learning all of this can sometimes feel isolating. When you hit a wall, or when a tool updates and suddenly your screen reader is not reading a specific menu correctly, you need a place to ask questions.

-

Jamie: The digital water cooler. Where do we go to swap stories and get unstuck?

-

Alex: There are two main communities you should join. The first is the A11y Slack community. A11y is numeronym for accessibility, spelled A, the number 11, and Y. This Slack workspace is filled with thousands of accessibility professionals, developers, and users. There are specific channels for screen reader questions, web standards, and developer tools. It is incredibly welcoming.

-

Jamie: And the second one?

-

Alex: The second is the GitHub Community Accessibility Discussions. This is an official discussion forum hosted on GitHub itself. It is monitored by the GitHub Accessibility team. If you find a bug on GitHub, or if you have an idea for how to make the platform more accessible, that is where you post it. It is also a great place to connect with other blind and low-vision developers who are using the exact same tools you are.

-

Jamie: That is really comforting to know. It means I am not just shouting into the void when something breaks. There are actual people, and actual teams, listening and ready to help.

-

Alex: You are absolutely not alone. There is a massive, vibrant community of blind and low-vision developers out there writing incredible code and shaping the future of open source. You are just taking your first steps to join them.

-

Alex: Alright, let us wrap up this episode with a few concrete takeaways. Jamie, what should our listeners remember?

-

Jamie: First, your permanent offline reference is the Accessibility Agents repository that you forked. Clone it to your computer, and you will have the entire workshop documentation available even without internet. Second, do not just read generic documentation. Search for the official GitHub Accessibility guides for screen-reader-optimized instructions and exact keyboard shortcuts.

-

Alex: Perfect. Third, when you are ready to practice, use GitHub Skills. It uses the template-copy pattern to give you real, hands-on practice inside the actual GitHub interface, guided by Mona the bot. And finally, remember your superpower. Use GitHub Advanced Search with topic colon accessibility to find projects that desperately need your lived experience.

-

Jamie: This has been incredibly helpful. I feel like I finally have a map to the library. What is next?

-

Alex: In our next episode, we are going to dive deep into the GitHub Concepts Glossary. We will be demystifying all the jargon and technical terms you will encounter in the wild, from upstream to cherry-picking to rebasing. You will not want to miss it. Until then, keep practicing, keep exploring, and keep Gitt Going.

-
- - -

Episode 39: Accessibility Agents - Complete Reference

-

All six agents, all 28 slash commands, customization, and troubleshooting.

-

Based on: Appendix V: Accessibility Agents - Complete Reference

- - -

Download Episode 39 (MP3)

-
-Read Transcript - Episode 39: Accessibility Agents - Complete Reference - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub. This is episode 39, Accessibility Agents Complete Reference. I am Alex, and I am thrilled to be here with you as we near the end of our two-day workshop material.

-

Jamie: And I am Jamie! I am so ready for this. We have been hinting at this massive ecosystem of agents for a while. Back in episode 17, we did a high-level overview of what an agent even is. But today, we are opening up the whole reference manual.

-

Alex: Exactly. Today is about scale and customization. We are going to cover the complete documentation for all 55 agents across three specialized teams. We will walk through the 54 plus slash commands and how to use them. We will break down exactly how these agents format their inputs and outputs. And most importantly, we will teach you how to customize them, configure your workspace, build your own domain-specific agents, handle version updates, and troubleshoot when things go wrong.

-

Jamie: Okay, just hearing you list all that out makes my brain feel a little full. Fifty-five agents? Fifty-four slash commands? That sounds like a lot of steps and a lot to memorize.

-

Alex: It does sound intimidating! But here is the thing. You have already done most of this on Day 1 of the workshop. You already know the workflow. The only difference now is that Visual Studio Code and GitHub Copilot are handling the heavy lifting. You do not have to memorize 55 agents. Think of it like walking into a massive digital agency. You do not need to know what every single employee does, you just need to know which department to walk into when you have a specific problem.

-

Alex: Let us start with that digital agency analogy. The accessibility agents ecosystem is divided into three teams, or departments. The first is the Accessibility Team, which is the largest, with 26 agents.

-

Jamie: So if I need help specifically with making my code work for screen readers or keyboard users, this is the department I go to.

-

Alex: Spot on. To talk to an agent, you open Copilot Chat by pressing Control plus Shift plus I. Then you type the at symbol, followed by the agent name. For example, you have task agents like at aria specialist, which helps you build complex widgets like comboboxes or modals. You have at contrast master for visual presentation, and at keyboard navigator for focus management.

-

Jamie: I remember struggling so much with live regions when I first learned accessibility. Is there an agent for that?

-

Alex: There is. It is literally called at live region controller. And what is brilliant about this team is that they have orchestrator agents. An orchestrator is like a project manager. If you call at web accessibility wizard, that agent will actually delegate tasks to the other specialized agents to perform a full, guided audit of your work. It gathers all their findings and gives you a single, prioritized action plan.

-

Jamie: That is incredible. So I do not have to talk to five different agents if I do not want to. I just talk to the wizard, and it talks to the team. What are the other two departments?

-

Alex: The second department is the GitHub Workflow Team. This one has 12 agents, and they automate your repository operations. You have at daily briefing, which gives you a morning situation report of issues and pull requests. You have at issue tracker to find and prioritize tickets. And my personal favorite, at pr review.

-

Jamie: Oh, pull requests! A pull request is when you are asking someone to review your code and pull it into the main project. I used to be terrified of reviewing them because I was worried I would miss something important.

-

Alex: And that is exactly why at pr review is so powerful. You give it a pull request number, and it reads the code, assesses the risk level, and even suggests inline comments. But remember the critical rule of the workflow team. The agent produces a starting point. It drafts the reply. You are the human. You read it, you edit it, and you post it under your own name.

-

Jamie: Got it. The agent is the assistant, not the boss. And what is the third team?

-

Alex: The Developer Tools Team. This has 6 agents focused on specific environments. For example, at python specialist for Python accessibility patterns, or at desktop a 11 y specialist for Windows, Mac, and Linux native app accessibility.

-

Alex: Now, alongside those 55 conversational agents, we have over 54 slash commands.

-

Jamie: Okay, so what is the difference? Why would I use a slash command instead of just talking to an agent with the at symbol?

-

Alex: Great question. Let us use an analogy. Talking to an agent with the at symbol is like hiring a contractor. You sit down, you have a conversation, you discuss the nuance of the project, and you go back and forth. A slash command is like a vending machine button. You press it, and you get exactly the specific snack you wanted, immediately, following a strict, repeatable process.

-

Jamie: Oh, I like that. So a slash command is for a single, focused task. How do I use one?

-

Alex: In that same Copilot Chat window, you just type a forward slash. That opens up a menu of commands. Let us talk about some of the most useful ones for this workshop.

-

Jamie: Hit me. What is on the speed dial?

-

Alex: If you type slash my dash issues, it immediately pulls up all your open issues with priority signals. If you type slash review dash pr followed by a number, like slash review dash pr 14, it generates that AI review with inline suggestions.

-

Jamie: What if I am looking at a brand new bug report and I do not know how to categorize it?

-

Alex: You type slash triage. It will read the issue and suggest labels and priority levels. If you need to respond to an issue, type slash issue dash reply. There is also slash daily dash briefing, which does the same thing as the daily briefing agent but in one quick command. And if you are getting ready to publish a new version of your software, slash draft dash release will automatically read all your merged code and generate the release notes for you.

-

Jamie: That is a massive time saver. I used to spend hours reading old commits just to write a changelog. But wait, how do these commands know what to do? You mentioned input and output formats earlier.

-

Alex: Yes. Let us talk about input formats first. Think of a prompt file like giving a recipe to a chef. When you type a slash command, Visual Studio Code looks at a specific file in your project that defines that command. Inside that file, we use input parameters. The syntax is a dollar sign, followed by an opening curly brace, the word input, a colon, the name of the variable, another colon, and then a helpful hint for the user, closing with a curly brace.

-

Jamie: So if I use slash review dash pr, the input parameter is asking me for the pull request number?

-

Alex: Exactly. The prompt file says, hey Copilot, please review the pull request provided in this input variable.

-

Jamie: And what about the output? When the agent replies, is it just a giant wall of text? Because as a screen reader user, a giant wall of text with no structure is my worst nightmare.

-

Alex: That is where the output format constraints come in. These agents are strictly instructed on how to structure their replies. We use an analogy of a well-organized filing cabinet. The agents are told to always use strict heading levels. They use heading level 2 for major sections, and heading level 3 for sub-sections. They are explicitly told never to skip heading levels, because jumping from an H1 straight to an H3 is a huge accessibility violation and breaks screen reader navigation.

-

Jamie: Oh, I love that. I navigate almost entirely by pressing the letter H to jump between headings. If the structure is predictable, I can skim an agent's response in seconds.

-

Alex: Exactly. Another strict output rule is the empty state rule. If you ask the daily briefing agent for your security alerts, and you have zero security alerts, the agent is not allowed to just skip that section. It must print the heading for Security Alerts, and underneath it, write All Clear.

-

Jamie: Yes! Silent failures are the worst. If a section is just missing, I always wonder if the agent broke, or if my screen reader skipped it, or if there really was nothing there. Explicitly saying All Clear removes so much cognitive load.

-

Alex: So, we know how the agents work out of the box. But every developer, every team, and every project is different. That brings us to customization. How do we teach the agents our specific rules?

-

Jamie: Like an employee handbook! You have to tell the new hire how your company does things.

-

Alex: Exactly. We do this through instruction files and settings. There are two main ways to provide always-on instructions. These are rules that the agent follows for every single request, without you ever having to ask.

-

Jamie: Where do we put this employee handbook?

-

Alex: The recommended approach for most projects is a file called copilot dash instructions dot m d. It lives inside a folder named dot github at the root of your project. It is just a plain text file. You can put your accessibility standards in there, your coding conventions, and even rules about tone. For example, you can write, Write for screen reader users first. Use active voice. Never use color as the only indicator of meaning.

-

Jamie: And if I am working on a massive project with different tools, like maybe I am using Claude Code in the terminal alongside Copilot?

-

Alex: Then you use the alternative option, a file simply called A G E N T S dot m d, right at the root of your workspace. It is an open standard that multiple artificial intelligence tools recognize. You use one or the other, not both.

-

Jamie: Okay, so that covers the project rules. But what about my personal preferences? Like, my team might not care what screen reader I use, but I want the agent to know.

-

Alex: That is where the preferences dot m d file comes in. You create this inside the dot github slash agents folder. This file is ignored by the version control system, meaning it stays completely private on your local machine. It never gets uploaded to the public team repository.

-

Jamie: Oh, that is neat. What kind of things do I put in my private preferences?

-

Alex: You can set your GitHub username, your timezone, and your notification priorities. If you want accessibility issues at the top of your daily briefing, you write that here. You can also define your review comment tone. You might say, Be direct but constructive, and be extra warm to first-time contributors.

-

Jamie: And my screen reader context goes here too?

-

Alex: Yes. You literally just write, I use N V D A with Chrome on Windows 11. The agents read this, and suddenly, they stop giving you instructions for VoiceOver on a Mac. They tailor their output specifically to your technology stack.

-

Alex: Now, Jamie, we just talked about project rules versus personal rules. This is a perfect transition to our next concept, which is workspace configuration and scope.

-

Jamie: Scope always confuses me a little. It sounds like a mouthwash.

-

Alex: Think of scope like a hierarchy of laws. You have city laws, state laws, and federal laws. In Visual Studio Code, we have three levels of scope. User level, Workspace level, and Organization level.

-

Jamie: Okay, break those down for me.

-

Alex: User scope, or personal scope, lives in your Visual Studio Code profile. These rules follow you to any project you open on your computer. Workspace scope lives in the repository folder, like that dot github directory we mentioned. Those rules apply to anyone who downloads that specific project. Organization scope is set by your company administrators on GitHub, and applies to every repository your company owns.

-

Jamie: So what happens when these laws conflict? Let us say my company Organization rules say, always write extremely formal code comments. But my User profile says, write casual, friendly code comments. Who wins?

-

Alex: The most specific, local scope always wins. Your Personal User profile has the highest priority. It overrides the Workspace, and the Workspace overrides the Organization. So your comments will be casual and friendly. Visual Studio Code collects all the instruction files from all three scopes, combines them, and sends them to the agent. Priority only matters when there is a direct contradiction.

-

Alex: So far, we have been consumers. We are using the 55 agents that already exist, and we are tweaking their instructions. But what if you want to build your own custom, domain-specific agent?

-

Jamie: Like writing a job description to hire a brand new specialist for my agency.

-

Alex: Exactly. It is surprisingly easy. An agent is just a file ending in dot agent dot m d. You save it in the dot github slash agents folder. The most important part of this file is at the very top, in a section called the frontmatter.

-

Jamie: Frontmatter. I have heard that term. That is the configuration block at the top of a file, usually surrounded by three dashes, right?

-

Alex: Yes. It uses a format called Y A M L, or YAML. In this frontmatter, you define the name of the agent. This is what you will type after the at symbol. You also write a description.

-

Jamie: Is the description just for me to read?

-

Alex: No, and this is crucial. The description is how the orchestrator agents decide whether to delegate work to your custom agent. If you name an agent at cool helper, and the description is just, A helpful agent, it will never get any delegated work. But if the description says, Use when auditing Markdown files for missing alt text and heading skips, the orchestrator knows exactly when to call it.

-

Jamie: Oh, that is clever! It is like a search engine optimization game, but for artificial intelligence delegation.

-

Alex: Exactly. The other critical thing you put in the frontmatter is the tools array. This dictates what your agent is allowed to do.

-

Jamie: Like giving the new hire a security badge.

-

Alex: Perfect analogy. If you give the agent the read tool, it has a visitor badge. It can look at your files but cannot change them. If you give it the edit tool, it can modify code. If you give it the execute tool, it has the master key. It can run shell commands in your terminal. You should be very careful with the execute tool.

-

Jamie: I can imagine. I do not want an agent deciding to format my hard drive because it misunderstood a prompt. Are there any other settings in that frontmatter?

-

Alex: Yes, you can set a flag called user dash invocable to false. This hides the agent from the chat menu. It becomes a background worker that only other agents can talk to.

-

Alex: Let us talk about version compatibility and update patterns. AI models are changing constantly. What happens if you build a custom agent that relies on a specific model, like Claude Sonnet, but then you share your project with a friend whose company only licenses GPT 4?

-

Jamie: Does the agent just crash?

-

Alex: It would, unless you use a fallback array. In your agent frontmatter, instead of listing one model, you can provide a list in brackets. You can say, try Claude Sonnet first, but if that is not available, fall back to GPT 4. Think of it like carrying a spare tire. If your primary model is unavailable, the agent gracefully switches to the backup without throwing an error.

-

Jamie: That is a great practice. What about when we want to enforce rules, rather than just guide the agent? Earlier you said instructions are just guidance.

-

Alex: Yes. Instructions are like a speed limit sign. You are asking the agent nicely to follow the rules. But sometimes you need a physical speed bump. That is where hooks come in. Hooks are JSON files, which is just another configuration format. They execute real shell commands at specific points in the agent's lifecycle.

-

Jamie: Like a security guard checking your bag before you leave the building.

-

Alex: Exactly. You can set a Pre Tool Use hook. Before the agent is allowed to use a tool to edit a file, the hook can run a script to validate the request. You can set a Post Tool Use hook to automatically run a code formatter every time the agent finishes writing a file. Hooks are deterministic. They run every single time, regardless of what the user typed in the chat.

-

Alex: Alright Jamie, we have covered a massive amount of ground. We are at the final concept. Troubleshooting. What happens when you type at daily briefing, and Visual Studio Code just says, Agent not found?

-

Jamie: I usually panic and restart my computer. Let me guess, there is a better way?

-

Alex: There is a slightly faster way. Visual Studio Code has a built-in Diagnostics view for Copilot Chat. You navigate to the Configure Chat gear icon, and select Diagnostics. This opens a panel that shows you every single instruction file, agent, and prompt that is currently loaded.

-

Jamie: Oh, so I can see if my custom agent file actually got loaded into the system.

-

Alex: Exactly. It will tell you if the file was found, if it loaded successfully, or if there is a syntax error in your YAML frontmatter, like a missing quote. If everything looks correct but the agent is still not showing up, you can reload the window.

-

Jamie: How do I do that without closing the whole program?

-

Alex: Press Control plus Shift plus P to open the Command Palette, type Reload Window, and press Enter. It takes about two seconds, and it completely refreshes the agent's brain, picking up any new files you just created.

-

Alex: And that brings us to the end of our complete reference guide for Accessibility Agents. Jamie, what are your top takeaways from today?

-

Jamie: Okay, first, the ecosystem is huge but manageable. We have 55 agents across three teams, and 54 slash commands. But I do not have to memorize them. I just use the orchestrator agents or the slash menu to find what I need. Second, scope and priority. My personal user settings win over the workspace rules, so I can always customize the tone and screen reader context for my own needs. Third, I can build my own agents using a simple markdown file, and I control exactly what they are allowed to do by giving them specific tools. And fourth, if I need to enforce a hard rule, I use a JSON hook. If I just want to guide the agent, I use an instructions file.

-

Alex: That is a perfect summary. You now have the keys to the entire customization engine. In our next episode, Episode 40, we are shifting gears. We will be looking at GitHub Actions and CI CD pipelines, and how we can integrate accessibility testing directly into the continuous integration process.

-

Jamie: I cannot wait. I am going to go write a custom agent to fetch my coffee. See you all next time!

-

Alex: Thanks for listening to Gitt Going with GitHub. Keep exploring, and keep building accessible software.

-
- - -

Episode 40: GitHub Copilot - Complete Reference

-

All Copilot features, chat participants, slash commands, and MCP servers.

-

Based on: Appendix W: GitHub Copilot - Complete Reference

- - -

Download Episode 40 (MP3)

-
-Read Transcript - Episode 40: GitHub Copilot - Complete Reference - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub, the audio learning series designed for blind and low-vision developers who are mastering GitHub and open source collaboration. I am Alex, and I am thrilled to be here with you.

-

Jamie: And I am Jamie! This is episode 40, which means we are getting close to the end of our journey, but we still have some incredibly powerful tools to cover. Today, we are doing a complete reference guide for GitHub Copilot.

-

Alex: That is right. Back in episode 14, we covered the absolute basics of Copilot. We talked about how it acts as an AI pair programmer, and we touched on inline suggestions. But today, we are zooming out to look at the entire Copilot ecosystem. We are going to cover the complete feature inventory, chat participants, slash commands, custom instructions, prompt files, model selection, the command line interface, and even Model Context Protocol servers.

-

Jamie: Okay, that sounds like a lot of steps. And honestly, a lot of jargon. I remember when I first learned GitHub a couple of years ago, hearing all those terms at once would have made me want to close my laptop and walk away.

-

Alex: It does sound like a lot! But here is the thing, Jamie. You have already done most of this on day one of your programming journey. You already know how to ask questions, how to search your codebase, and how to write terminal commands. This is just the exact same workflow, but with VS Code handling the heavy lifting and fetching the context for you. We are going to break every single piece down and explain not just how it works, but why it matters.

-

Jamie: I love that. So where do we start with the complete feature inventory? When we say GitHub Copilot today, what exactly are we talking about?

-

Alex: Copilot has grown far beyond just auto-completing your code. The complete feature inventory really consists of four main pillars. First, there are inline suggestions, which happen right inside your editor as you type. Second, there is Copilot Chat, which is a dedicated conversational interface inside VS Code. Third, there is Copilot in the command line interface, which brings AI assistance to your terminal. And fourth, there is Copilot for Pull Requests, which integrates directly into GitHub dot com to help you summarize and review code changes.

-

Jamie: Let us start with those inline suggestions, because that is where most people first encounter Copilot. When I am typing, Copilot will suggest code, which we often call ghost text. For a screen reader user, this can be a bit chaotic because the screen reader might try to announce things while you are still thinking.

-

Alex: Exactly. And this is a great time to review the most important accessibility workflow for Copilot. When you are typing and a suggestion appears, your screen reader might announce that an inline suggestion is available, especially if you have your accessibility signals turned on in VS Code settings. The instinct is to just press Tab to accept it, or Escape to reject it. But if the suggestion is multiple lines long, you really need to read it first.

-

Jamie: And reading it word by word using Control plus Right Arrow is one way to do it. On a Mac, that would be Command plus Right Arrow. That lets you accept the suggestion one word at a time, which is great for short completions. But for a whole function, that gets tedious.

-

Alex: Right. Which is why the Accessible View is your best friend. Whenever a suggestion appears, do not press Tab immediately. Instead, press Alt plus F 2. On a Mac, that is Option plus F 2. This opens the Accessible View.

-

Jamie: I wish I had known about Alt plus F 2 when I started. Can you explain exactly what the Accessible View does?

-

Alex: Absolutely. Think of the Accessible View like taking a photograph of a moving object. When Copilot generates text, it streams it in token by token, piece by piece. If your screen reader tries to read that live stream, it sounds broken and fragmented, like someone shouting words at you one by one as they think of them. The Accessible View captures the complete, static response and puts it into a structured, read-only text pane. You can navigate it with your up and down arrow keys at your own pace.

-

Jamie: And the best part is, you do not even have to wait for the response to finish generating anymore. You can press Alt plus F 2 immediately after sending a prompt, and the Accessible View will dynamically update in a screen-reader-friendly way. Once you read the suggestion and decide you want it, you just press Control plus Slash, or Command plus Slash on Mac, and it inserts the code right at your cursor. You do not even have to close the panel first.

-

Alex: Now let us move to the second pillar: Copilot Chat. You open this panel by pressing Control plus Shift plus I, or Command plus Shift plus I on Mac. This is where you can ask open-ended questions. But the real power comes from Chat Participants.

-

Jamie: Chat participants. I use these all the time, but I always explain them to people as inviting experts into a conference room. If I am in an empty room and I ask, why is this broken, nobody knows what I am talking about. But if I invite the database expert and the frontend expert into the room and ask the same question, they can look at my work and give me a specific answer.

-

Alex: That is a perfect analogy. In Copilot Chat, you invite these experts by typing the at symbol, followed by their name. The most common one is at workspace. When you type at workspace before your question, Copilot searches your entire VS Code project for relevant context. It looks at your open files, your file structure, and the code itself.

-

Jamie: So if I want to know where we define our heading hierarchy for accessibility, I would type at workspace, followed by, find all places where heading hierarchy is documented.

-

Alex: Exactly. Another great participant is at terminal. If you run a command and it spits out a huge, confusing error message, you can open Copilot Chat and type at terminal, what did that last command output mean? Copilot will read the buffer from your integrated terminal and explain the error. There is also at github, which lets you search issues, pull requests, and code across all of GitHub dot com right from your editor.

-

Jamie: And alongside those at symbol participants, we have the hash symbol variables, right? Like hash file or hash selection.

-

Alex: Yes. If participants are the experts in the room, the hash variables are the specific documents you slide across the table for them to look at. If you type hash file, a file picker opens, allowing you to attach any specific file to your prompt. If you type hash selection, it attaches whatever text you currently have highlighted in your editor.

-

Jamie: So I could highlight a really messy block of code, open chat, and type, at workspace, please review hash selection for accessibility violations.

-

Alex: You absolutely could. And that actually leads us perfectly into our next topic: Slash Commands.

-

Alex: Slash commands are built-in shortcuts for the most common tasks you might want Copilot to do. Instead of typing out a long prompt, you just type a forward slash and a specific keyword.

-

Jamie: I love slash commands. I think of them like the quick-dial buttons on a microwave. You could type out exactly how many minutes and seconds you want to heat up your popcorn, or you can just press the popcorn button. Slash commands are the popcorn buttons of Copilot.

-

Alex: That is exactly what they are. Let us go through the essential ones. First is slash explain. If you navigate to a complex block of code, select it, and type slash explain in the chat, Copilot will break down exactly what that code does in plain language. This is incredible when you are reading a new codebase.

-

Jamie: Then there is slash fix. If you have code with a bug or a syntax error, you select it, type slash fix, and Copilot will propose a correction.

-

Alex: Next is slash tests. Selecting a function and typing slash tests will generate unit tests for that specific logic. And similarly, slash doc will generate documentation comments, like JS Doc strings, for your selected code.

-

Jamie: There is also slash new, which is fantastic for scaffolding. If I type slash new React component for notifications, Copilot will generate the file structure and the boilerplate code for me. It saves so much repetitive typing.

-

Alex: And if you ever forget these, just type slash help. It will list all the available commands and participants.

-

Jamie: Okay, so built-in slash commands are great. But what if I want my own custom popcorn buttons? What if my team has very specific ways we write tests, or very specific accessibility rules we follow? I do not want to type those rules out every single time I ask Copilot to generate code.

-

Alex: This is where Custom Instructions and Prompt Files come in, and they are total game changers. Let us talk about Custom Instructions first. You can create a file in your repository at the exact path dot github slash copilot dash instructions dot md.

-

Jamie: And just to clarify, that is a folder named dot github, and inside it, a markdown file named copilot dash instructions.

-

Alex: Correct. This file is basically the employee handbook for Copilot. Whatever you write in this plain text markdown file will be quietly attached to every single request you make to Copilot in that workspace. You never have to invoke it manually.

-

Jamie: So what kind of things should go in the employee handbook?

-

Alex: Project-wide conventions. You might write things like: Include semantic HTML elements in generated markup. Never use color as the only indicator of meaning. Write commit messages using the conventional commits format. Always use active voice in documentation. Once you save that file, Copilot just knows to follow those rules.

-

Jamie: That is brilliant. And you can actually have VS Code generate a starting point for this file automatically, right?

-

Alex: Yes! If you open Copilot Chat and type slash init, it will analyze your workspace and create a tailored copilot dash instructions file for you. You can review it, tweak it, and commit it to your repository so everyone on your team gets the same consistent AI behavior.

-

Jamie: Now, what if I have instructions that should only apply to specific files? Like, I only want my testing rules to apply when I am looking at test files.

-

Alex: For that, you use Scoped Instructions. You create files with the extension dot instructions dot md. Inside these files, you can use a bit of configuration at the top called frontmatter to define when the file should activate. For example, you can set an applyTo property that tells Copilot, only use these instructions if the current file ends in dot test dot js.

-

Jamie: That is so smart. It keeps the context window clean. The AI does not need to read the testing rules if I am just asking it to fix a CSS bug. And what about those custom popcorn buttons we mentioned? The reusable prompt files?

-

Alex: Those are called Prompt Files. They live in a folder named dot github slash prompts, and they have the extension dot prompt dot md. If you create a file in there called review dot prompt dot md, you instantly get a new slash command in your chat called slash review.

-

Jamie: So I could write a prompt file that says, check the selected code against the Web Content Accessibility Guidelines level AA, and suggest fixes for any keyboard navigation issues. Then, anytime I want that check, I just type slash review.

-

Alex: Exactly. And there is a priority system here that is important to understand. You can have instructions at the Organization level, the Workspace level, and the User level. The User level refers to files stored in your personal VS Code profile folder. If there is ever a conflict, your personal User instructions always win. They override the Workspace, and the Workspace overrides the Organization. But mostly, they are additive. VS Code combines all the relevant instructions and sends them together.

-

Jamie: Let us talk about Model Selection. I noticed a dropdown menu at the bottom of the Copilot Chat input area. It lets me change the AI model. Why would I want to change it?

-

Alex: Because different models have different strengths. Think of it like hiring different types of contractors. Sometimes you need a very fast junior developer to write a quick script or format some JSON. Other times, you need a deliberate, meticulous senior architect to design a complex system from scratch.

-

Jamie: So if I just need a quick explanation of a terminal command, I might use a smaller, faster model. But if I am asking Copilot to refactor an entire module and ensure it handles edge cases, I want to select the most powerful model available in that dropdown.

-

Alex: Exactly. The interface lets you switch models on the fly depending on the complexity of the task. Keep in mind that as a screen reader user, you can navigate to this dropdown by tabbing through the bottom toolbar of the Chat view. Pressing Space or Enter will open the list of available models.

-

Jamie: Okay, so we have covered the editor extensively. But I spend a lot of time in the command line. Does Copilot exist outside of VS Code?

-

Alex: It absolutely does. If you have the GitHub CLI installed, which is the command line tool you run by typing g h, you can install the Copilot extension for it. Once you do, you get access to a feature that is like having a universal translator for your terminal.

-

Jamie: I definitely need a translator for some of those complex Git commands or obscure shell scripts. How does it work?

-

Alex: There are two main commands. The first is g h copilot suggest. You type that, followed by what you want to do in plain English. For example, g h copilot suggest find all markdown files modified in the last three days. Copilot will generate the exact terminal command you need, and even offer to run it for you.

-

Jamie: That is incredible. No more digging through manual pages to remember which flags to use for the find command.

-

Alex: Exactly. And the second command is the reverse: g h copilot explain. If you come across a command in documentation that looks like alphabet soup, you can copy it, paste it after g h copilot explain, and it will break down exactly what every single flag and argument does.

-

Jamie: Alright, let us tackle the jargon I mentioned earlier. MCP Servers. I see this acronym everywhere now. Model Context Protocol. What is it, and why should I care?

-

Alex: MCP is a breakthrough in how AI agents interact with the world. Think about it this way. By default, Copilot lives in a box. It can read your code, and it can write text. But it cannot directly browse the live internet, or query your company database, or run a Docker container. It does not have hands.

-

Jamie: So an MCP server gives it hands?

-

Alex: Yes. An MCP server is like giving Copilot a secure API badge to access specific external tools. It is an open standard protocol. If your team builds an MCP server that connects to your internal bug tracker, you can plug that server into VS Code. Suddenly, Copilot can actually look up live ticket statuses when you ask it questions.

-

Jamie: That makes so much sense. It is a standardized way to plug tools into the AI. I know GitHub has a community repository called awesome dash copilot, where people share these tools. You can actually install an MCP server from there that gives Copilot even more capabilities.

-

Alex: That is right. Awesome dash copilot is a curated ecosystem of plugins, prompts, and MCP servers. You can explore it right from your chat by typing slash plugin. It acts as a marketplace browser for community-built tools.

-

Jamie: We have one last pillar to cover from our feature inventory: Copilot for Pull Requests. This happens on GitHub dot com, not in VS Code, right?

-

Alex: Mostly, yes. When you are on GitHub dot com and you open a pull request, Copilot can help in two major ways. First, it can generate a PR summary. Instead of manually typing out a description of the twenty files you changed, Copilot reads the differences and generates a structured summary of the feature, the changes, and the impact.

-

Jamie: I think of that like having a proofreader write an executive summary for your report. It saves the reviewer so much time because they get a high-level overview before they dive into the code.

-

Alex: Exactly. And the second feature is PR reviews. Reviewers can ask Copilot to explain specific changes in the pull request, or even ask it to generate review comments checking for common bugs. It is an incredible time saver for maintainers.

-

Jamie: And speaking of automation on GitHub dot com, I read something in the reference material about GitHub Agentic Workflows. What is that?

-

Alex: That is a technical preview feature that takes AI automation to the next level. Instead of interacting with an agent in your editor, you write a markdown file describing a goal, like, create a daily status report of all open issues. You push that file to your repository, and a cloud-based AI agent runs on a schedule, reads your repository, and completes the task automatically. It is like having a tireless project manager running in your GitHub Actions pipeline.

-

Jamie: Wow. We have covered a massive amount of ground today. From ghost text to cloud agents. How do we summarize all of this?

-

Alex: Let us narrow it down to three concrete takeaways for our listeners to practice. First, make Alt plus F 2 your default reflex. Whenever Copilot suggests inline code or responds in chat, open the Accessible View. It removes the streaming noise and gives your screen reader a clean, navigable structure.

-

Jamie: Second, leverage chat participants and slash commands. Do not just ask generic questions. Invite the experts by using at workspace or at terminal, and use slash explain or slash fix to skip the repetitive typing.

-

Alex: And third, start building your project's employee handbook. Create a dot github slash copilot dash instructions dot md file in your workspace. Write down your accessibility standards and coding conventions in plain English. You will be amazed at how much better Copilot's suggestions become when it knows the rules of your specific house.

-

Jamie: I am definitely going to set up an instructions file today. This has been such a helpful reference guide. What are we covering in the next episode?

-

Alex: In episode 41, we are going to dive deep into a specific community toolset: Accessibility Agents. We will look at how to build and use custom agents specifically designed to catch accessibility violations before they ever leave your editor. It is going to be incredibly practical.

-

Jamie: I cannot wait for that one. Thank you all for listening to Gitt Going with GitHub.

-

Alex: Keep exploring, keep coding, and we will see you in the next episode.

-
- - -

Episode 41: Copilot AI Models

-

Model comparison, strengths, plan availability, and selection guidance.

-

Based on: Appendix X: Copilot AI Models

- - -

Download Episode 41 (MP3)

-
-Read Transcript - Episode 41: Copilot AI Models - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub, the audio series where we build your open source skills from the ground up. I am Alex, and today we are diving into Episode 41, titled Copilot AI Models.

-

Jamie: And I am Jamie. I am so excited for this one. We have been using GitHub Copilot in the last few episodes, asking it to explain code and help us write functions. But today we are looking under the hood.

-

Alex: Exactly. If you are just joining us, you might want to review Episode 13 where we installed Copilot in Visual Studio Code, and Episode 40 where we covered the basics of interacting with the chat panel. Today, we are talking about the actual brains powering those interactions. Because Copilot is not just one single artificial intelligence. It is actually a collection of many different AI models that you can choose from.

-

Jamie: That was a huge aha moment for me when I first started learning GitHub a couple of years ago. I thought Copilot was just one big brain sitting on a server somewhere. But it is more like a whole team of developers with different specialties, right?

-

Alex: That is a perfect analogy. And GitHub has built something really unique here. Instead of forcing you to use just one provider, they have partnered with several of the biggest names in artificial intelligence. Inside Copilot, you have access to models from OpenAI, which makes the GPT and Codex models. You also have Anthropic, which makes the Claude models. Google is here with their Gemini models. And xAI is available with their Grok models.

-

Jamie: It is like having a workshop where you can call over a master carpenter, an electrician, or an architect depending on what you need to build. But with so many options, how do you even begin to understand the differences between them?

-

Alex: We can break it down by looking at three main characteristics. Speed, quality, and context window size. Let us define that last term first, because it is crucial. A context window is the amount of text, code, and conversation history that the AI can hold in its short-term memory at one single time.

-

Jamie: I love talking about context windows. The way it finally clicked for me was thinking about my physical physical desk. If I have a tiny desk, I can only have one or two reference books open while I am working. If I need to look at a third book, I have to close one and put it away. That is a small context window. But a massive context window is like having a giant conference table where I can spread out fifty documents, my entire project codebase, and all my error logs, and look at them all at once.

-

Alex: That is exactly right. A larger context window means the AI can understand how a function in your database file connects to a variable in your user interface file, because both files fit on its mental conference table at the same time. But here is the trade-off. Models with giant context windows, or models that are built for extremely high quality and deep reasoning, are usually slower. And they require more computing power.

-

Jamie: Which brings us to the speed versus quality trade-off. It is like choosing between a quick spell-check and a deep structural edit of a novel. If I just want to know the keyboard shortcut to save a file, I want the answer instantly. I do not need the AI to ponder the philosophical implications of saving data. I just want a fast answer.

-

Alex: Precisely. So let us talk about how to match the right model to the right task, starting with general purpose coding and writing. For everyday tasks, like simple code completions, writing documentation, or explaining a standard function, you want a reliable, fast default. Right now, as of February 2026, the standard workhorses are OpenAI models called GPT 4.1 and GPT 5 mini. They are incredibly fast, very accurate, and they handle most everyday tasks effortlessly.

-

Jamie: And they are free to use, right? We will get into the pricing plans in a minute, but I know I use GPT 5 mini for almost everything. It is just so snappy. But what if I have a really repetitive task, like I need to rename twenty variables, or I need boilerplate code for a basic HTML page?

-

Alex: For tasks where speed is your absolute top priority, you can switch to models specifically optimized for fast help. Anthropic has a model called Claude Haiku 4.5. Google has Gemini 3 Flash. And OpenAI has Grok Code Fast 1 and a Codex Mini variant. These models are lightweight. They do not do well if you ask them to architect a complex database, but if you ask them to write a quick regular expression to validate an email address, they will give you the answer before you even finish taking a breath.

-

Jamie: Okay, so we have the everyday models and the super fast models. But what about when things get really complicated? Like last week, I had a bug where my screen reader was not announcing a status update on a web page, and the problem was buried somewhere between three different JavaScript files and an ARIA live region. A fast model would probably just guess and get it wrong.

-

Alex: Exactly. That is when you need to bring in the heavy hitters for deep reasoning and debugging. This is where you want to use Anthropic models like Claude Sonnet 4.6, or Claude Opus 4.6. Or OpenAI models like GPT 5.2. These models are designed to stop, think, and analyze complex multi-file problems.

-

Jamie: Bringing in Claude Opus is like escalating a bug to the senior staff engineer. You know it might take them a few extra seconds to reply, but they are going to give you a deeply considered, architectural answer.

-

Alex: Yes, and they excel at understanding unfamiliar codebases. If you join a new open source project and you need someone to explain how their authentication flow works across ten different files, Claude Opus or Gemini 3 Pro are the models you want reading those files.

-

Jamie: We should also talk about a term that has been popping up a lot lately. Agentic software development. I hear people saying Copilot has an Agent mode now. What does agentic actually mean in this context?

-

Alex: Agentic simply means the AI acts as an autonomous agent. In a standard chat, you ask a question, the AI gives you an answer, and you have to go copy and paste the code yourself. In Agent mode, you give Copilot a goal, like, set up a new testing framework for this project. The AI will then independently write the code, open your terminal, run the installation commands, read the error messages if something fails, fix its own mistakes, and keep iterating without you needing to guide it step by step.

-

Jamie: That sounds slightly terrifying but mostly amazing. Does it use a specific model for that? Because I imagine you need a very smart model to let it run its own terminal commands.

-

Alex: You do. And for agentic tasks, OpenAI has created specialized models under the Codex name. Right now, the recommended model for this is GPT 5.1 Codex Max, or GPT 5.2 Codex. These are explicitly trained for autonomous reasoning and multi-step execution.

-

Jamie: What about visuals? As a totally blind developer, I obviously do not work with visual mockups. But occasionally, a sighted designer will hand me an image file of a user interface and ask me to build it. Can these models help with that?

-

Alex: They absolutely can, and this is a fantastic accessibility use case. Several models support image input, meaning you can paste an image directly into the Copilot chat. GPT 5 mini, Claude Sonnet, and Gemini 3 Pro all understand images. You could paste that design mockup into the chat and type, please describe the structural layout of this image and generate the semantic HTML to build it. The AI will analyze the visual layout and translate it into code for you.

-

Jamie: That is brilliant. I wish I had known that when I started. It completely removes the barrier of needing a sighted colleague to describe a screenshot to me.

-

Alex: Now that we know about all these different models, we need to talk about how you actually get access to them. GitHub Copilot has several different subscription plans. There is Copilot Free, Copilot Pro, Copilot Pro Plus, Business, and Enterprise.

-

Jamie: And this is where the concept of premium requests comes in, right? Because not all models cost the same amount of resources to run.

-

Alex: Exactly. Let us use an arcade token analogy. Imagine your Copilot subscription gives you a certain number of tokens every month. The fast, everyday models like GPT 4.1 and GPT 5 mini have a cost multiplier of zero. They are free games. You can play them all day long and they never use up your premium tokens.

-

Jamie: So if I am on the completely free tier of Copilot, I can still use those zero-multiplier models as much as I want?

-

Alex: Well, on the Free tier, you have a hard limit of 50 total requests per month. But if you are on any paid plan, like Pro or Business, you can use the zero-multiplier models infinitely.

-

Jamie: Got it. But what if I want to play the really fancy arcade game? The deep reasoning models like Claude Opus?

-

Alex: Those models have a higher cost multiplier. For example, Claude Opus 4.6 has a multiplier of three. That means every single message you send to Claude Opus consumes three of your premium requests. The mid-tier models, like Claude Sonnet or GPT 5.2, have a multiplier of one. They consume one premium request per message.

-

Jamie: Okay, so if I am on the standard Copilot Pro plan, which gives me 300 premium requests a month, I need to budget them. I should not use Claude Opus to ask how to center a text element, because that is wasting three tokens on a problem that the free GPT 5 mini model could solve for zero tokens.

-

Alex: Exactly. You want to save those premium requests for the truly demanding tasks. Now, if you are on Copilot Pro Plus or Copilot Enterprise, you have unlimited premium requests, so you do not have to worry about quotas. But for everyone else, managing that multiplier is an important part of your workflow.

-

Jamie: Alright, let us get practical. I am in Visual Studio Code right now. How do I actually switch between these models?

-

Alex: Let us start with the Chat panel. First, you press Control plus Shift plus I to open the chat view. Your focus will naturally land in the text input area where you type your messages.

-

Jamie: Okay, I am there.

-

Alex: Now, the model picker is a button located in the toolbar that sits right below that text input area. If you press the Tab key to navigate through the chat input toolbar, you will move past the attach button, and the next item your screen reader announces should be the name of the currently active model. It might say something like Auto, or Claude Sonnet 4.6, button.

-

Jamie: I just pressed Tab, and my screen reader said, Auto, model picker button.

-

Alex: Perfect. Press Space or Enter to activate that button. It opens a dropdown menu listing all the available models on your plan. You can just use your Up and Down Arrow keys to move through the list. When you hear the one you want, press Enter to select it. Your screen reader will then announce the newly selected model, and your focus returns to the chat input area so you can start typing.

-

Jamie: That is really straightforward. And what about Inline Chat? We talked about that a few episodes ago, where you press Control plus I to open a quick chat directly inside your code editor instead of opening the side panel. Can I switch models there too?

-

Alex: You can. When you press Control plus I to open Inline Chat, a small toolbar appears in your editor. The model picker button is right there in that toolbar. The interaction is exactly the same. You navigate to the button, open the dropdown, and select your model.

-

Jamie: But wait, does changing the model in the chat panel also change the model that gives me those automatic ghost text suggestions while I am typing? You know, the inline completions that just appear as I type?

-

Alex: That is a fantastic question, and the answer is no. This is a really important distinction. Model selection only affects your conversational chats. The automatic inline suggestions that appear as you type are handled completely separately.

-

Jamie: Why is that?

-

Alex: Because inline suggestions have to be instantaneous. If you are typing a function, you cannot wait five seconds for Claude Opus to ponder the meaning of your code. You need a suggestion in milliseconds. So GitHub exclusively uses highly specialized, hyper-fast models for inline completions. Right now, those are fine-tuned OpenAI models called Raptor mini and Goldeneye. You cannot manually switch those. GitHub manages them in the background to guarantee speed. You only choose models for the Chat and Agent interactions.

-

Jamie: Earlier, my screen reader announced that my selected model was Auto. What exactly does Auto do?

-

Alex: Auto mode is the default setting, and honestly, it is what most developers should use most of the time. Think of it like an automatic transmission in a car. You do not have to manually shift gears. Copilot analyzes your prompt and automatically routes it to the best model.

-

Jamie: So if I ask a simple question, it automatically routes to a fast, zero-multiplier model. But if I ask it to debug a massive architectural issue, it automatically shifts into a higher gear and routes to a deep reasoning model?

-

Alex: Exactly. And if you give it an agentic task, it automatically selects a Codex model. It manages your premium requests intelligently. You can always check which model it decided to use by navigating to the response details after it replies.

-

Jamie: If Auto is so smart, why would I ever manually override it and pick a specific model?

-

Alex: A few reasons. Sometimes you might be running low on premium requests for the month, so you manually lock it to GPT 5 mini to ensure you do not spend any more tokens. Or, you might find that for your specific programming language, say you write a lot of obscure Haskell code, you find that Claude Sonnet consistently gives you better answers than the model Auto chooses. Finally, if you want to use the vision capabilities to analyze an image, you might manually select a model that you know supports images, just to be safe.

-

Jamie: That makes sense. If I manually select a model, how do I get back to Auto mode?

-

Alex: You just open the model picker dropdown again using the steps we discussed, arrow to the very top of the list, and select Auto. It is just another option in the menu.

-

Jamie: One thing I have noticed over the last two years is that the models keep changing. I remember when everyone was talking about GPT 4, and now we are talking about GPT 5.2. It feels hard to keep up.

-

Alex: It is a fast-moving landscape. GitHub regularly updates the roster. They bring in newer, smarter models and they retire the older ones. It is just like getting software updates on your phone. Eventually, the old version is no longer supported.

-

Jamie: What happens if my favorite model gets retired? Like, what if I manually set my chat to use Claude Sonnet 3.5, and then GitHub retires it? Will my Copilot just break?

-

Alex: No, Copilot handles it gracefully. When a model is officially retired, Copilot simply stops sending requests to it and automatically falls back to the nearest equivalent newer model. So you would just be upgraded to Claude Sonnet 4.

-

Jamie: That is a relief. Is there a way to know when models are being added or retired so I am not caught off guard?

-

Alex: Yes, the best place to track this is the official GitHub Copilot changelog on the GitHub blog. They announce all model additions and retirements there. It is a great resource to check once a month just to see what new tools have been added to your workshop.

-

Jamie: This has been incredibly enlightening. I feel like I finally understand what is happening behind the scenes. What are our key takeaways for today?

-

Alex: First, remember that Copilot gives you access to multiple AI providers, including OpenAI, Anthropic, Google, and xAI. Second, match the model to the task. Use fast, free models like GPT 5 mini for everyday questions, and save the powerful models like Claude Opus for complex debugging to conserve your premium requests.

-

Jamie: Third, you can easily switch models in Visual Studio Code by pressing Control plus Shift plus I to open the chat panel, and tabbing to the model picker button. And fourth, when in doubt, just leave it on Auto mode and let Copilot do the driving for you.

-

Alex: Perfectly summarized. Now that you know how to choose the right brain for the job, you need to know how to talk to it effectively. In our next episode, Episode 42, we are going to cover Writing Effective Copilot Prompts. We will learn how to structure your questions to get the highest quality code out of whichever model you choose.

-

Jamie: I definitely need that. Half the time I feel like I am arguing with the AI because I did not explain myself clearly. I cannot wait.

-

Alex: It is going to be a great discussion. Until then, keep experimenting with those different models, and happy coding.

-
- - -

Episode 42: Accessing Workshop Materials

-

Downloading the repository, reading offline, keeping updated, audio format.

-

Based on: Appendix Y: Accessing Workshop Materials

- - -

Download Episode 42 (MP3)

-
-Read Transcript - Episode 42: Accessing Workshop Materials - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub, the audio learning series designed specifically for blind and low-vision developers who are navigating the world of open source. I am Alex, and as always, I am thrilled to be here with you.

-

Jamie: And I am Jamie! I am a developer who learned GitHub about two years ago, and I am here to ask all the questions that you are probably thinking as you listen.

-

Alex: Today we are diving into Episode 42, which is all about Accessing Workshop Materials. We have covered so much ground in this series. We have talked about branches, commits, pull requests, and navigating the GitHub interface. But today, we are taking a step back to talk about the materials themselves.

-

Jamie: Yes, and I am so glad we are doing this. When I attended my first developer workshop, I was so overwhelmed. The instructor sent out a link to a GitHub repository, and I navigated to it, and there were just dozens of files. There was a docs folder, an HTML folder, a scripts folder, markdown files everywhere. I spent the first hour just trying to figure out where the actual reading material was, while everyone else was already starting the exercises.

-

Alex: That is incredibly common, and it is exactly why we dedicated an entire appendix in the written guide, and this entire podcast episode, to this topic. A repository for a workshop is essentially a giant filing cabinet. If you do not know how the cabinet is organized, or how to take the files out of it, you are going to feel lost.

-

Jamie: Exactly. So, I know we have a few prerequisites for today. Listeners should already be familiar with what a repository is, and they should know the basic concept of Git, which we covered way back in our first few episodes.

-

Alex: Spot on. If you know what a repository is, you are ready for this episode. Today, we are going to talk about how to get the workshop materials, how to read them offline, how to keep your copy updated when the instructor adds new content, and the different formats we offer, including HTML, Markdown, and the very audio format you are listening to right now.

-

Jamie: I love it. Where should we start?

-

Alex: Let us start by talking about the formats. We provide the workshop materials in multiple ways because different developers have different accessibility needs and learning preferences. The first format is the one we are using right now. The podcast audio series.

-

Jamie: Which is so meta! We are in the podcast, talking about the podcast.

-

Alex: We are! But the audio format serves a very specific purpose. Listening to someone explain a technical concept is completely different from reading a technical document with your screen reader. When you are reading code or step-by-step instructions, your brain is doing a lot of work parsing the syntax, the keystrokes, and the formatting.

-

Jamie: Oh, absolutely. When my screen reader is reading a markdown file, I am listening to every heading level, every list item, every piece of punctuation in a code block. It is a high cognitive load.

-

Alex: Exactly. So the podcast format is designed to be your conceptual introduction. Think of it like having a study buddy sitting in the passenger seat of your car. You can listen to us while you commute, or while you are doing the dishes. We explain the why, the overarching concepts, and the analogies. Then, when you actually sit down at your computer to read the written materials, you already have the mental model. The written materials are for the exact keystrokes and the technical reference.

-

Jamie: That makes so much sense. I wish I had this audio series when I started. Okay, so aside from the podcast, the written materials come in two main formats. Markdown and HTML. Can you break down the difference for someone who might be new to those terms?

-

Alex: I would love to. Markdown is a plain text format. It uses very simple punctuation to indicate formatting. For example, a single number sign before a word makes it a heading. We use Markdown because it is the standard language of GitHub. Every repository has a README file written in Markdown. It is lightweight, and you can write it in any simple text editor.

-

Jamie: And screen readers handle plain text really well.

-

Alex: They do. But plain text does not have the rich navigational structure that a fully built website has. That is where HTML comes in. HTML stands for HyperText Markup Language. It is the code that powers web pages. We have an automated script that takes all our simple Markdown files and transforms them into beautifully structured HTML pages.

-

Jamie: I think an analogy would help here. How should I picture the relationship between Markdown and HTML?

-

Alex: Think of Markdown as the script for a play. It has the raw dialogue and the basic stage directions. It gets the point across perfectly. But HTML is the final stage production. It has the lighting, the sets, the costumes, and the ushers guiding you to your seat. The content is exactly the same, but the presentation and the navigation are much more polished.

-

Jamie: Oh, I love that. The ushers guiding you to your seat is a great way to describe ARIA landmarks and skip links.

-

Alex: Exactly. Our HTML files include breadcrumb navigation, skip-to-content links, and ARIA landmarks. ARIA stands for Accessible Rich Internet Applications, and landmarks are invisible signposts that tell your screen reader where the main content begins, where the navigation menu is, and so on.

-

Jamie: So let us say I am attending the workshop, and I want the fully produced stage play. I want the HTML version with all those navigational signposts. How do I get to it? Do I have to download something?

-

Alex: You do not have to download anything if you do not want to. The absolute easiest way to read the materials during the workshop is by browsing online using GitHub Pages.

-

Jamie: GitHub Pages. We have mentioned that before, but what is it exactly?

-

Alex: GitHub Pages is a free service provided by GitHub that takes the HTML files in your repository and publishes them as a live website. For our workshop, your facilitator will give you a specific web address. Usually, it looks something like community hyphen access dot org slash Learning hyphen Room.

-

Jamie: So it is just a regular website. I open my browser, I navigate to that URL, and I am there.

-

Alex: Exactly. It is like walking into a well-organized public library. Everything is already on the shelves. When you load the page, you will be on the index dot html file, which serves as the homepage. From there, you can use standard screen reader commands to move around.

-

Jamie: Let us talk about those commands, because navigation is everything. When I land on that GitHub Pages site, what is the fastest way to get to the actual reading material?

-

Alex: The fastest way is to use your landmark jump key. In NVDA, you press the D key. In JAWS, you press the R key. That will jump you straight to the main landmark, bypassing all the top-level navigation and the headers.

-

Jamie: That saves so much time. I used to just press the down arrow fifty times until I heard something that sounded like a paragraph.

-

Alex: We have all been there. Once you are in the main landmark, use your heading key, which is the H key, to move through the sections. All the chapters and appendices are linked. If the text references Appendix A, you can just press Enter on that link, and it will take you right to Appendix A. It is a completely seamless online reading experience.

-

Jamie: Okay, so GitHub Pages is the polished library. But what if the facilitator has not set up GitHub Pages, or what if I just want to read the raw Markdown files directly on the GitHub website? Can I do that?

-

Alex: You absolutely can. You can read every single file directly on GitHub dot com without downloading a thing. You just navigate to the repository link that your facilitator shares.

-

Jamie: But this is where I used to get stuck. I would get to the repository page, and my screen reader would just read a massive table of files and folders. How do I actually find chapter one?

-

Alex: Great question. When you load a repository page on GitHub, the main content area contains a grid or a table of all the files. You can press the T key on your keyboard to jump straight to the file table, and then use your arrow keys to move through the rows. You will find a folder called docs. That is where all the written chapters live.

-

Jamie: Wait, did you just say I can press T to jump to the table?

-

Alex: Actually, I should clarify. If you are in browse mode, T jumps to the table. But GitHub has a built-in keyboard shortcut that is even better. If you turn your screen reader's browse mode off, or pass the key through, and you press the letter T anywhere on the repository homepage, it opens the file finder.

-

Jamie: The file finder? I do not think I know what that is.

-

Alex: It is a dynamic search field. When you press T, an edit box pops up. You can just type a word, like pull requests, or chapter five. GitHub instantly filters the entire repository and shows you only the files that match. You arrow down to the one you want, press Enter, and you are inside the file.

-

Jamie: Mind blown. That is so much faster than digging through folders manually. It is like having a digital assistant where you just say the name of the file and it hands it to you.

-

Alex: Exactly. And once you open a Markdown file on GitHub dot com, GitHub automatically renders it. It turns the number signs into actual headings, and it formats the code blocks. So you can still use your H key to navigate by headings, even though it is technically a Markdown file.

-

Jamie: Okay, so reading online is great. But what if I am going to be on a train with no internet, or what if I just want all the files on my own computer so I can open them in my own editor? That sounds like a lot of steps.

-

Alex: It does sound like a lot, but here is the thing. You have already done most of this on Day 1 of the workshop. It is the exact same workflow you use for any code project. To get the files onto your computer, you need to download everything. And you have two options for this. Option A is cloning the repository with Git. Option B is downloading a ZIP file.

-

Jamie: Let us start with Option A, cloning. What does that mean, and how do I do it?

-

Alex: Cloning means using the Git command line tool to create a complete, fully functioning copy of the repository on your local computer. You open your terminal, and you type git, space, clone, space, and then you paste the web address of the repository. So it would be git clone https colon slash slash github dot com slash community hyphen access slash Learning hyphen Room dot git.

-

Jamie: And when I press enter on that command, what happens?

-

Alex: Git reaches out to GitHub, gathers every single folder, every file, every image, and every bit of history, and pulls it down into a new folder on your computer.

-

Jamie: That sounds powerful. But what if I am not comfortable with the command line yet? What is Option B?

-

Alex: Option B is downloading a ZIP file. You do not need Git installed for this. You just go to the repository page on GitHub dot com. You navigate to a button called the Code button. It is a green button near the top of the file listing, right after the branch selector.

-

Jamie: How do I find the Code button with my screen reader?

-

Alex: If you are at the top of the page, you can press the letter B to jump from button to button. You will hear things like Watch, Fork, Star, and eventually, you will hear Code collapsed button. You press Space or Enter to expand it, and a dropdown menu appears. You just arrow down through that menu until you hear Download ZIP, and you activate it.

-

Jamie: And then it just downloads a standard ZIP folder to my downloads directory, and I can extract it like any other file.

-

Alex: Exactly right. You extract it, and you have all the exact same files as if you had cloned it.

-

Jamie: Okay, so I have to ask. If downloading a ZIP is so easy, and I do not have to use the terminal, why do you recommend cloning instead?

-

Alex: That is a brilliant question. I want to use an analogy here. Think about getting your news. Downloading a ZIP file is like walking to the newsstand and buying a printed newspaper. You have all the information that existed at the exact moment you bought it. But tomorrow, when new things happen, your printed newspaper will not update. It is static. A snapshot in time.

-

Jamie: Right. If the workshop facilitator adds a new chapter on day two, my ZIP file from day one will not have it.

-

Alex: Exactly. But cloning with Git is like signing up for a smart digital subscription. You get all the current news today. And tomorrow, you can just ask the service for any updates, and it will only send you the new articles, slotting them perfectly into your existing app. Cloning keeps your local folder connected to the original source on GitHub.

-

Jamie: That makes perfect sense. Okay, so I have used Git clone, and now I have a folder on my computer called Learning hyphen Room. It is full of stuff. I want to read chapter one offline. How do I do that?

-

Alex: The best way to read the materials offline is to open the entire folder in a text editor like Visual Studio Code, which we call VS Code. You open your terminal, you type cd space Learning hyphen Room to move into the folder, and then you type code space dot. That is the word code, a space, and a period.

-

Jamie: I use that command all the time. It opens VS Code and loads the current folder into the workspace.

-

Alex: Yes. And once VS Code is open, you can use the Explorer pane to browse the files. The keyboard shortcut to focus the Explorer is Control plus Shift plus E.

-

Jamie: Let us break down what is actually in this folder, because the structure can be intimidating. When I open the Explorer, what folders am I going to find?

-

Alex: You will see a few main folders. First is the docs folder. This is where all the Markdown files live. Chapters zero through sixteen, and all the appendices. If you want to read the raw text, you open these files.

-

Jamie: And what if I want the pretty, formatted version? The stage play?

-

Alex: Then you navigate to the html folder. This folder contains the exact same content, but pre-built into HTML files. You can actually open the index dot html file directly in your web browser. Just locate it in your computer's file explorer, press Enter, and it will open in Chrome or Edge or Firefox. It works exactly like the online GitHub Pages site, but it is running entirely off your hard drive. No internet required.

-

Jamie: That is so cool. It is like pitching your tent in the woods and having all your supplies with you. You are completely self-sufficient.

-

Alex: Exactly. And there is one more folder you will see, called the learning hyphen room folder. This is where the actual practice exercises live. When the facilitator tells you to complete a challenge, you will find the instructions and the starting code in that folder.

-

Jamie: Okay, so if I decide to read the Markdown files in VS Code, instead of the HTML files in the browser, is there a way to make the Markdown look a bit nicer? Like, instead of my screen reader saying number sign number sign Chapter One, can it just read it as a heading level two?

-

Alex: Yes! VS Code has a fantastic built-in feature called Markdown Preview. If you open a Markdown file in the editor, you can press Control plus Shift plus V. That is V as in Victor.

-

Jamie: What does that shortcut do?

-

Alex: It opens a new pane that renders the Markdown as rich text. Your screen reader will interact with it almost exactly like a web page. You can use your H key to jump by headings, your list commands to read bullet points, and it hides all the raw punctuation. It is a wonderful way to read offline if you prefer to stay inside VS Code rather than opening a browser.

-

Jamie: I am learning so many shortcuts today. Control plus Shift plus E for the Explorer, Control plus Shift plus V for the Markdown preview. This is great. But let us go back to that smart subscription analogy. You said if I clone the repository, I can easily get updates. Let us say it is day two of the workshop. The instructor says, I just fixed a typo in chapter four and added a new cheat sheet. How do I get those updates into my local folder?

-

Alex: This is where the magic of Git comes in. All you have to do is open your terminal, make sure you are inside the Learning hyphen Room folder, and type a two-word command. Git pull. That is G I T, space, P U L L.

-

Jamie: Git pull. I love that name because you are literally pulling the changes down from the internet into your computer.

-

Alex: Exactly. It is like refreshing your podcast app to see if a new episode has dropped. When you run git pull, Git checks the original repository on GitHub, sees what has changed since your last visit, and seamlessly merges those changes into your local files.

-

Jamie: What if I made a change to a file? Like, what if I was taking my own notes inside chapter four, and then I run git pull. Will it overwrite my notes?

-

Alex: Git is very safe. It will not overwrite your local changes without asking. If you modified the exact same line that the instructor modified, Git will pause and say, wait a minute, we have a merge conflict. It will ask you to decide which version to keep. We actually have an entire chapter dedicated to merge conflicts, because they sound scary, but they are just Git's way of being cautious.

-

Jamie: That is reassuring. Now, if I run git pull, does it update both the Markdown files and the HTML files?

-

Alex: Usually, yes, because we commit the updated HTML files to the repository. But if for some reason the HTML files are out of sync, we include a simple script you can run. In your terminal, you just type npm space run space build colon html.

-

Jamie: Wait, spell that out for me.

-

Alex: Sure. N P M, space, run, space, build, colon, html. That command runs a small program on your computer that reads all the Markdown files and generates fresh HTML files. So if you ever edit the materials yourself and want to see the changes in the browser, you just run that command.

-

Jamie: Okay, we have covered reading online, downloading everything, reading offline, and staying updated. I have one last scenario. What if I do not want the whole repository? What if I literally just want the keyboard shortcut cheat sheet so I can print it out or emboss it in Braille? Can I download just one file?

-

Alex: You absolutely can, and I highly recommend doing this for reference sheets. If you are on the GitHub dot com website, and you have navigated to a specific file, let us say the cheat sheet markdown file. You open it, and right above the content of the file, there is a small toolbar of buttons.

-

Jamie: What buttons are in that toolbar?

-

Alex: You will hear things like Preview, Code, Blame, and Raw. You want to navigate to the Raw button and activate it.

-
- - -

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

- - -

Download Episode 43 (MP3)

-
-Read Transcript - Episode 43: GitHub Skills - Complete Course Catalog - -

Transcript

-

Alex: Welcome to Gitt Going with GitHub, the audio learning series for blind and low-vision developers. I am Alex, and today we are diving into Episode 43, GitHub Skills and the Complete Course Catalog.

-

Jamie: And I am Jamie! We are getting so close to the end of our series, which matches up with the end of Day 2 of the workshop. Today is all about what happens next. How do you keep learning once the workshop is over?

-

Alex: Exactly. During the workshop, you have a lot of support. You have facilitators, you have the learning room, you have us in your ears. But when you go back to your desk on Monday, you might feel a little stranded. That is where GitHub Skills comes in.

-

Jamie: I remember when I was learning GitHub about two years ago. I would read these long, static tutorials, and I would try to follow along in my own repository, but I was never quite sure if I did it right. There was no feedback loop. I wished I had someone looking over my shoulder saying, yes, you created that branch correctly.

-

Alex: That is the exact problem GitHub Skills solves. GitHub Skills is a free, interactive, self-paced learning platform. But what makes it truly special for our community is that there is no separate website, no external video portal, and no custom interface to learn. Every single course runs entirely inside GitHub itself.

-

Jamie: Which is huge for accessibility. You do not have to learn a whole new set of keyboard shortcuts or figure out how a completely different website is structured. You just use the heading navigation and landmark jumping skills you have already been practicing.

-

Alex: Right. The way it works is brilliant. It is like an interactive flight simulator. You are not watching someone else fly; you are at the controls. When you start a course, GitHub copies a template repository directly into your own account. It is your repository, completely private to you unless you choose to make it public.

-

Jamie: And then you meet Mona.

-

Alex: Yes, Mona! Mona is GitHub's automated learning bot. Once the repository is copied to your account, Mona uses GitHub Actions in the background to act as your personal instructor. Within about twenty seconds of starting a course, Mona will open an issue in your new repository.

-

Jamie: And just as a quick refresher, an issue is essentially a discussion thread used to track tasks, bugs, or feature requests. So Mona opens this issue, and the first comment will be your instructions for Step 1. It might say something like, welcome to the course, your first task is to create a new branch.

-

Alex: You read the instructions, and then you just do the task right there in your repository. You create the branch, or you edit a file, or you open a pull request. A pull request, of course, being the formal way you ask to merge your code changes into the main project.

-

Jamie: So you do the work, and then what? How does Mona know you did it?

-

Alex: Because Mona is listening for those events. When you open that pull request, the bot detects your action, validates that you did it correctly, and then immediately posts the next step. It might leave a comment on your pull request saying, great job, now let us try leaving a code review comment. You just keep following the prompts until Mona closes the final issue with a congratulatory completion message.

-

Jamie: It is so satisfying to get that final message. OK, that sounds like a lot of automated steps, but I want to normalize this for a second. It might sound intimidating to have a bot watching your repository, but you have already done this. The workflow is exactly what you practiced on Day 1. You are just reading issues, making commits, and managing pull requests.

-

Alex: Absolutely. Now, before we get into the massive catalog of courses, let us talk about how to start a course and track your progress. To start, you simply navigate to the specific course URL, which we list in Appendix Z of the workshop materials, and activate the Start course button.

-

Jamie: But tracking progress is a little quirky, right? Because there is no central dashboard that says, Jamie has completed five out of thirty-six courses.

-

Alex: That is correct. GitHub Skills does not have a central profile dashboard. But there are a few practical ways to track your learning. First, all of these courses create repositories in your account that start with the prefix skills hyphen. So, you can just navigate to your repositories page and filter by the word skills to see everything you have started.

-

Jamie: Oh, that is clever! I also like to bookmark Mona's final completion message in my browser, just as a little digital trophy.

-

Alex: That works too! You can also pin your favorite completed course repositories to your main GitHub profile. And finally, Appendix Z has a personal completion checklist. You can literally just copy that markdown list into a private issue or a local text file and check off the boxes as you go.

-

Jamie: Alright, let us talk about the courses themselves. There are thirty-six modules in total, organized into different learning paths. But before we hit the advanced stuff, there are three courses that are actually woven into Day 1 of the workshop.

-

Alex: Yes, the beginner path, or the workshop courses. These are Introduction to GitHub, Communicate Using Markdown, and Review Pull Requests.

-

Jamie: Introduction to GitHub is the classic starting point. It teaches you the core flow: how to create branches, make commits, open pull requests, and merge them. A commit is basically saving a snapshot of your work, and a branch is a safe parallel universe where you can make those commits without affecting the main project.

-

Alex: Then you have Communicate Using Markdown. Markdown is the lightweight formatting language used everywhere on GitHub. This course teaches you how to format headings, add emphasis, create links, format code blocks, and build task lists and tables, all using plain text characters.

-

Jamie: And the third one is Review Pull Requests. This is where you practice assigning reviewers, leaving comments on specific lines of code, suggesting changes, and finally approving and merging.

-

Alex: If you are listening to this and you did not finish those three modules during Day 1, that is your very first prerequisite. Go finish those before you attempt anything else. They are the foundation of everything we do on GitHub.

-

Jamie: Once those are done, we have six distinct learning paths to choose from. You do not have to do all of them, right? You just pick the path that matches your goals.

-

Alex: Exactly. Let us start with Path 1, Git Fundamentals. This path is for deepening your understanding of the underlying version control system. It includes three courses: Introduction to Git, Resolve Merge Conflicts, and Change Commit History.

-

Jamie: Resolve Merge Conflicts used to terrify me. A merge conflict happens when two people edit the exact same line of code in different ways, and Git essentially throws its hands up and says, I do not know which version to keep, you figure it out.

-

Alex: It is a great analogy. Imagine two authors collaborating on a book. If you both rewrite the exact same paragraph in chapter two, the publisher cannot just mash them together. Someone has to read both versions and write a final, combined paragraph. That is all a merge conflict is. This course teaches you why they happen, how to read the text markers that Git inserts to show you the two versions, and how to resolve them safely using the web editor.

-

Jamie: And what about Change Commit History? That sounds like time travel.

-

Alex: It is time travel! Sometimes you make a typo in a commit message, or you want to combine five messy commits into one clean one before you share your work. This course teaches you how to amend commits, squash them together, and reorder your history using a tool called interactive rebase. It requires the Introduction to Git course as a prerequisite, but it is incredibly powerful once you learn it.

-

Jamie: Path 2 is GitHub Collaboration. This feels like the path for people who want to become open source maintainers or run projects for their team.

-

Alex: Spot on. This path extends the labels and milestones you learned in Day 1 into full repository management. The recommended order starts with Introduction to Repository Management.

-

Jamie: This is where you learn about branch protection, right? Like setting rules that say, nobody is allowed to merge code into the main branch unless it has been reviewed by at least two people.

-

Alex: Exactly. You also learn how to create issue templates, so when someone reports a bug, they get a predefined form asking for reproduction steps and screen reader versions, rather than just a blank text box. It is like running a community center. You need rules, you need clear signs, and you need structure so everyone can collaborate safely.

-

Jamie: The next course in this path is Connect the Dots.

-

Alex: Yes, this teaches you how to cross-reference work. How to mention an issue inside a pull request so that when the pull request merges, the issue automatically closes.

-

Jamie: I love that feature. It feels like magic. Then we have GitHub Pages, which teaches you how to host a website directly from your repository for free. And finally, Release-Based Workflow, where you learn how to tag specific points in your history as official version releases, like version 1 point 0.

-

Alex: Moving on to Path 3, GitHub Actions and Automation. This is for the DevOps folks, or really anyone who is tired of doing repetitive tasks manually.

-

Jamie: Automation is the best. If I have to do something more than twice, I want a robot to do it for me.

-

Alex: That is the spirit of GitHub Actions. Actions are essentially a digital Rube Goldberg machine. You define a trigger, like when someone opens a pull request, and that trigger knocks over a domino that starts a sequence of automated tasks.

-

Jamie: The first course here is Hello GitHub Actions, which is your prerequisite for the rest of the path. It teaches you the vocabulary. What is a workflow file? What is a trigger? What are jobs and steps?

-

Alex: Once you have that vocabulary, the path opens up. You can take Test with Actions, which teaches Continuous Integration. That means automatically running your automated tests every time someone pushes new code, to make sure nothing broke.

-

Jamie: Then there is Reusable Workflows, so you do not have to copy and paste the same automation across fifty different repositories. And Write JavaScript Actions, where you actually build your own custom automation tools from scratch.

-

Alex: The path also covers deployment. There is Publish Docker Images, which teaches you how to build software containers and publish them. And Deploy to Azure, for pushing your web applications to the cloud.

-

Jamie: And they recently added AI to this path too, right?

-

Alex: Yes, the newest courses are AI in Actions and Create AI-Powered Actions. These teach you how to integrate artificial intelligence models directly into your automation pipelines. So your automated workflows can actually summarize pull requests, or categorize issues based on their text content, without human intervention.

-

Jamie: Speaking of AI, that brings us to Path 4, GitHub Copilot. This is the biggest path in the catalog, with ten different courses.

-

Alex: It is massive because Copilot has grown from a simple code completion tool into an entire ecosystem. Copilot is an AI assistant trained on public code. The analogy I use is that it is like pair programming with an incredibly fast typist who has memorized all the documentation on the internet, but who still needs you to be the head chef and tell them what to cook.

-

Jamie: You start with Getting Started with GitHub Copilot. This covers the basics of code completion, using Copilot Chat to ask questions, and getting help with debugging.

-

Alex: From there, you move into Build Applications with Copilot Agent Mode. Agent mode is fascinating. Instead of just suggesting one line of code at a time, you can give Copilot a complex natural language prompt, and it will plan and generate changes across multiple different files at once.

-

Jamie: Then there is Copilot Code Review, where the AI helps you catch quality issues before you merge. And Customize Your GitHub Copilot Experience, which teaches you how to set up custom instructions. So you can tell Copilot, hey, I use a screen reader, always ensure the HTML you generate includes proper ARIA labels.

-

Alex: Exactly. The path gets quite advanced from there. There is Expand Your Team with Copilot, where you learn to assign issues directly to the Copilot agent on the GitHub website, no editor required. And Integrate MCP with Copilot. MCP stands for Model Context Protocol. It is a way to give the AI secure access to external tools and data, so it can read your database schema or check your error logs.

-

Jamie: There is also Scale Institutional Knowledge Using Copilot Spaces, which helps share context across a whole team. And Create Applications with the Copilot CLI. CLI stands for Command Line Interface. I know the terminal can be intimidating, but Copilot can actually explain shell commands to you before you run them, which is a huge confidence booster.

-

Alex: The final two courses in the Copilot path are Your First Extension for GitHub Copilot, where you build custom capabilities for the AI, and Modernize Your Legacy Code. That last one is a two-hour deep dive where you use Copilot to translate an old COBOL accounting system into modern Node dot js.

-

Jamie: Wow. From basic chat all the way to translating COBOL. That is quite a journey.

-

Alex: Let us shift gears to Path 5, Security. Security is everyone's job, but it can feel overwhelming. This path breaks it down perfectly.

-

Jamie: It starts with the Secure Code Game, which sounds fun. It is a gamified course where you hunt for real security vulnerabilities in sample code and learn how to patch them.

-

Alex: Then you have Introduction to Secret Scanning. Secret scanning is like having a bouncer check your pockets before you leave the house to make sure you are not accidentally dropping your house keys on the public sidewalk. It scans your repository to ensure you have not accidentally committed passwords, API keys, or security tokens into your public code.

-

Jamie: And Secure Repository Supply Chain. This is all about dependencies. A dependency is external code written by someone else that your project relies on. This course teaches you how to use Dependabot to find out if those external projects have known vulnerabilities, and how to automatically update them.

-

Alex: Finally, we have Introduction to CodeQL and Configure CodeQL Language Matrix. CodeQL is GitHub's semantic code analysis engine. Think of it as a building inspector. It reads your code, understands the flow of data, and flags structural weaknesses, like a place where a hacker could inject malicious SQL commands into your database. These courses teach you how to enable and configure that inspector.

-

Jamie: Alright, the final path. Path 6, Cloud and Migration.

-

Alex: This path is all about moving your development environment and your existing projects into the modern cloud. It starts with Code with Codespaces.

-

Jamie: We talked about Codespaces in Appendix N. A Codespace is a complete developer environment hosted in the cloud. You do not have to install Node, or Python, or Docker on your local laptop. You just connect to the cloud environment through VS Code or your browser.

-

Alex: The analogy here is renting a fully furnished apartment instead of building a house from scratch. When you start the Code with Codespaces course, you will practice spinning up these environments, configuring them, and accessing them using your local screen reader via the command palette. Just remember to press Control plus Shift plus P to open that command palette.

-

Jamie: The second course is Migrate ADO Repository. ADO stands for Azure DevOps. If your company is moving from Azure DevOps to GitHub, this course gives you a safe sandbox to practice migrating the code and history using the command line.

-

Alex: And the final course in the entire catalog is Idea to App with Spark. GitHub Spark is an AI tool that lets you build small web applications entirely through natural language, without writing the code yourself. It is a fantastic way to rapidly prototype ideas.

-

Jamie: Okay, that is thirty-six courses across six paths. It is a lot to take in. How should someone actually approach this after the workshop?

-

Alex: My biggest piece of advice: do not try to do everything at once. Pick just one path that aligns with your immediate goals. If you want to contribute to open source, start with Path 2, Collaboration. If you want to code faster, start with Path 4, Copilot.

-

Jamie: And work through them one at a time. Each course only takes about thirty to sixty minutes. If you do one a week, you give yourself time to actually absorb the concepts and try them out in your real projects.

-

Alex: Exactly. And keep your workshop materials handy. When a GitHub Skills course asks you to create a branch or resolve a merge conflict, Mona will not give you the specific screen reader keystrokes. You will need to refer back to the chapter guides from this workshop for those specific accessibility instructions.

-

Jamie: So, to summarize our key takeaways. First, GitHub Skills is free, self-paced, and runs entirely in the standard GitHub interface, making it highly accessible. Second, a bot named Mona will guide you through issues and pull requests in your own private template repository.

-

Alex: Third, track your progress by searching your repositories for the prefix skills hyphen, and by using the checklist in Appendix Z. And fourth, always finish the introductory workshop courses before branching out into the specialized paths like Actions, Security, or Copilot.

-

Jamie: This has been such a great roadmap. What is coming up in our next episode, Alex?

-

Alex: In Episode 44, which is our final episode of the series, we are going to talk about community. We will cover how to find accessible open source projects, how to disclose your access needs to maintainers if you choose to, and how to take your very first steps into the wider GitHub community.

-

Jamie: I cannot wait. Thank you so much for listening, everyone. Happy learning, and we will catch you in the final episode!

-

Alex: Take care, and keep Git going.

-
- - -

Production

-

These episodes are generated using Google NotebookLM Audio Overviews. Each episode is produced from the workshop chapter content combined with episode-specific production prompts that ensure concept coverage, accessible language, and screen reader-friendly descriptions.

-

Source bundles and production documentation are in the podcasts/ directory.

- -
- - - \ No newline at end of file diff --git a/html/PROGRESS_TRACKER.html b/html/PROGRESS_TRACKER.html deleted file mode 100644 index 2aada2c..0000000 --- a/html/PROGRESS_TRACKER.html +++ /dev/null @@ -1,579 +0,0 @@ - - - - - - - Progress Tracker - GIT Going with GitHub - - - - - - - - -
-

Progress Tracker

-

Track Your Learning Journey Through the GitHub Workshop

-

How to Use This Tracker

-
    -
  1. Print this page or save as PDF to mark progress offline
    2. -
  2. Or keep a checklist in your preferred note-taking app
    3. -
  3. Check off items as you complete them
    4. -
  4. Return here to see your learning path and next steps
    5. -
-

Pre-Workshop Setup

-
    -
  • Created GitHub account (free tier is fine)
    • -
  • Installed Git (https://git-scm.com/download/)
    • -
  • Installed/configured VS Code or preferred editor
    • -
  • Installed GitHub CLI (gh) - optional but recommended
    • -
  • Set up SSH key or HTTPS authentication
    • -
  • Verified: git --version shows v2.20+
    • -
  • Verified: gh auth status shows you're logged in
    • -
-

Status: Not started In progress Complete

-

Chapter 0: Pre-Workshop Setup

-

Time: 30 minutes | What You'll Do: Get your computer ready

-
    -
  • Read docs/00-pre-workshop-setup.md
    • -
  • Complete all prerequisite installations
    • -
  • Verify all tools work (git, VS Code, GitHub)
    • -
  • Set up SSH key (optional but recommended)
    • -
  • Test: Can you clone a repository? (git clone ...)
    • -
-

Status: Not started In progress Complete

-

Chapter 1: Understanding GitHub Web Structure

-

Time: 1 hour | What You'll Do: Learn GitHub's layout and terminology

-
    -
  • Read docs/01-understanding-github-web-structure.md
    • -
  • Understand: Repositories, Branches, Commits, PRs, Issues
    • -
  • Identify on any GitHub repo: Code tab, Issues tab, PR tab, Settings
    • -
  • Know the difference: Fork vs. Branch
    • -
  • Can explain: What is a pull request?
    • -
-

Status: Not started In progress Complete

-

Chapter 2: Navigating Repositories

-

Time: 45 minutes | What You'll Do: Practice exploring real repositories

-
    -
  • Read docs/02-navigating-repositories.md
    • -
  • Navigate to 3 different repos and identify key files
    • -
  • Use keyboard navigation (accessibility focus)
    • -
  • Found: README, CONTRIBUTING, License, Issues template
    • -
  • Understand the code structure and file tree
    • -
-

Status: Not started In progress Complete

-

Chapter 3: The Learning Room

-

Time: 30 minutes | What You'll Do: Understand the shared practice environment

-
    -
  • Read docs/03-the-learning-room.md
    • -
  • Understand: How the Learning Room automation works
    • -
  • Know: Where to find your first contribution challenge
    • -
  • Reviewed: Available practice challenges
    • -
  • Understand: How bot feedback and peer review work
    • -
-

Status: Not started In progress Complete

-

Chapter 4: Working with Issues

-

Time: 1 hour | What You'll Do: Create, read, and comment on issues

-
    -
  • Read docs/04-working-with-issues.md
    • -
  • Create an issue in a practice repo
    • -
  • Comment on someone else's issue
    • -
  • Add a label and assignment to an issue
    • -
  • Know how to: Search issues, filter by label, use issue templates
    • -
  • Understand: Issue lifecycle (Open → In Progress → Done)
    • -
-

Status: Not started In progress Complete

-

Chapter 5: VS Code Accessibility

-

Time: 45 minutes | What You'll Do: Set up VS Code for accessible development

-
    -
  • Read docs/05-vscode-accessibility.md
    • -
  • Installed: VS Code with accessibility settings configured
    • -
  • Enabled: Screen reader mode and keyboard navigation
    • -
  • Know how to: Use the Command Palette (Ctrl+Shift+P)
    • -
  • Configured: Accessibility signals and editor preferences for your workflow
    • -
-

Status: Not started In progress Complete

-

Chapter 6: Working with Pull Requests

-

Time: 1 hour | What You'll Do: Submit, review, and merge PRs

-
    -
  • Read docs/06-working-with-pull-requests.md
    • -
  • Create a pull request
    • -
  • Review a PR and add comments
    • -
  • Respond to PR feedback
    • -
  • Know how to: See diff, leave suggestions, approve
    • -
  • Understand: PR merge strategies (Merge, Squash, Rebase)
    • -
-

Status: Not started In progress Complete

-

Chapter 7: Merge Conflicts

-

Time: 1 hour | What You'll Do: Resolve conflicts between branches

-
    -
  • Read docs/07-merge-conflicts.md
    • -
  • Understand: Why conflicts happen
    • -
  • Know how to: Identify conflict markers (<<<< ==== >>>>)
    • -
  • Successfully resolved: 1+ real merge conflict
    • -
  • Know the "abort" option: git merge --abort
    • -
-

Status: Not started In progress Complete

-

Chapter 8: Culture & Etiquette

-

Time: 30 minutes | What You'll Do: Learn collaborative best practices

-
    -
  • Read docs/08-culture-etiquette.md
    • -
  • Understand: Respectful code review
    • -
  • Know the difference: Suggestion vs. Requirement
    • -
  • Can give constructive feedback on code
    • -
  • Understand: Inclusive language in issues/PRs
    • -
-

Status: Not started In progress Complete

-

Chapter 9: Labels, Milestones & Projects

-

Time: 45 minutes | What You'll Do: Use GitHub's organizational tools

-
    -
  • Read docs/09-labels-milestones-projects.md
    • -
  • Created: 3+ labels for a repo or issue
    • -
  • Created: 1+ milestone (release or sprint)
    • -
  • Used project board to organize work (optional: add columns and cards)
    • -
  • Filtered issues using: Labels + Milestones
    • -
-

Status: Not started In progress Complete

-

Chapter 10: Notifications

-

Time: 30 minutes | What You'll Do: Master GitHub notifications

-
    -
  • Read docs/10-notifications.md
    • -
  • Set up notifications: Email or in-app
    • -
  • Understand: @mentions, subscriptions, digest settings
    • -
  • Configured: Notifications for your projects
    • -
  • Know how to: Unsubscribe from threads you don't need
    • -
-

Status: Not started In progress Complete

-

Chapter 11: Git & Source Control in VS Code

-

Time: 1 hour | What You'll Do: Master Git operations within VS Code

-
    -
  • Read docs/11-git-source-control.md
    • -
  • Know how to: Clone, branch, commit, push from VS Code
    • -
  • Used: Source Control panel (Ctrl+Shift+G)
    • -
  • Understand: Staging, committing, and syncing changes
    • -
  • Configured: Git credentials and remote tracking
    • -
-

Status: Not started In progress Complete

-

Chapter 12: GitHub Pull Requests Extension

-

Time: 45 minutes | What You'll Do: Review and create PRs from VS Code

-
    -
  • Read docs/12-github-pull-requests-extension.md
    • -
  • Installed: GitHub Pull Requests and Issues extension
    • -
  • Know how to: View, review, and create PRs in VS Code
    • -
  • Understand: Inline code review workflow
    • -
  • Practice: Commented on a PR from within VS Code
    • -
-

Status: Not started In progress Complete

-

Chapter 13: GitHub Copilot

-

Time: 1 hour | What You'll Do: Use AI-assisted coding and chat

-
    -
  • Read docs/13-github-copilot.md
    • -
  • Installed: GitHub Copilot and Copilot Chat extensions
    • -
  • Verified: Copilot Chat works (Ctrl+Shift+I)
    • -
  • Know how to: Use inline suggestions, chat, and custom instructions
    • -
  • Understand: Chat participants, agents, and model selection
    • -
-

Status: Not started In progress Complete

-

Chapter 14: Accessible Code Review

-

Time: 1.5 hours + Exercises | What You'll Do: Review code accessibly

-

Reading & Concepts

-
    -
  • Read docs/14-accessible-code-review.md
    • -
  • Understand: Accessible code review principles
    • -
  • Know the difference: Manual review vs. Copilot review
    • -
  • Familiar with: VS Code Accessible Diff Viewer (F7)
    • -
-

Exercises

-
    -
  • Exercise A: Review issue accessibility using web reader
    • -
  • Exercise B: Use VS Code Accessible Diff Viewer
    • -
  • Exercise C: Comment on PR accessibility
    • -
-

Status: Not started In progress Complete
Exercises Completed: A B C All

-

Chapter 15: Issue Templates

-

Time: 1.5 hours + Exercises | What You'll Do: Create accessible issue templates

-

Reading & Concepts

-
    -
  • Read docs/15-issue-templates.md
    • -
  • Understand: YAML syntax for templates
    • -
  • Know how to: Create and test custom templates
    • -
  • Understand: Form accessibility in templates
    • -
-

Exercises

-
    -
  • Exercise A: Create template using GitHub web UI
    • -
  • Exercise B: Create template locally in VS Code
    • -
  • Exercise C: Create PR for accessibility template
    • -
  • Exercise D: Design custom template for your project
    • -
-

Status: Not started In progress Complete
Exercises Completed: A B C D All

-

Chapter 16: Accessibility Agents

-

Time: 1.5 hours + Exercises | What You'll Do: Automate with Copilot agents

-

Agents to Explore

-

Browse the ecosystem and try agents that match your skills (read Chapter 16 for the full landscape):

-
    -
  • GitHub Workflow agents - @daily-briefing, @issue-tracker, @pr-review, @analytics, @insiders-a11y-tracker, @template-builder
    • -
  • Accessibility agents - @web-accessibility-wizard, @contrast-master, @keyboard-navigator, @markdown-a11y-assistant
    • -
  • Developer Tools agents - @python-specialist, @desktop-a11y-specialist, @a11y-tool-builder
    • -
-

Exercises

-
    -
  • Exercise 1: Generate a template with @template-builder
      -
    • Follow all 8 steps
      • -
    • Ask Questions workflow guided tour
      • -
    • Save generated template
      • -
    • Test locally or on GitHub
      • -
    -
    • -
  • Exercise 2: Extend the @template-builder agent
      -
    • Follow all 6 steps
      • -
    • Edit .github/agents/template-builder.agent.md
      • -
    • Add new Pre-Built Workflow
      • -
    • Test agent with new workflow
      • -
    -
    • -
  • Exercise 3: Iterative refinement with agents
      -
    • Follow all 4 steps
      • -
    • Ask agent to modify/extend template
      • -
    • Observe pattern of interaction
      • -
    • Reflection: How does iteration work with agents?
      • -
    -
    • -
-

Status: Not started In progress Complete
Exercises Completed: 1 2 3 All

-

Appendices (Reference)

-
    -
  • Appendix A: Glossary - Read as needed for term definitions
      -
    • Saved link or printed for reference
      • -
    -
    • -
  • Appendix B: Screen Reader Cheatsheet - Bookmark this!
    • -
  • Appendix Y: Accessing Workshop Materials - How to download, read offline, and keep updated
    • -
  • Appendix Z: GitHub Skills Catalog - All 36 modules organized into six learning paths
      -
    • NVDA commands bookmarked
      • -
    • JAWS commands bookmarked
      • -
    • VoiceOver commands bookmarked
      • -
    -
    • -
-

Overall Progress Summary

-

Exercises by Chapter

-

The workshop includes structured exercises in the following chapters. Use this table to track your exercise completion separately from chapter reading:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ChapterExerciseDescriptionDone?
Ch 160-Second OrientationPress 1, D, 2, H on a repo page - prove you can navigate by ear
Ch 2Five-Tab TourVisit Code, Issues, PRs, file finder, and README on a real repo
Ch 3Individual Challenges12 progressive challenges in learning-room/docs/CHALLENGES.md
Ch 3Group Challenges7 collaborative exercises in learning-room/docs/GROUP_CHALLENGES.md
Ch 4File Your First IssueCreate an introduction issue in the Learning Room
Ch 5Try It Right NowOpen a repo in github.dev, enable screen reader mode, explore the interface
Ch 6Read a Real PRNavigate a PR's description, conversation, and diff
Ch 7Read a ConflictRead merge conflict markers and identify both versions
Ch 8Rewrite One CommentTransform a dismissive review comment into constructive feedback
Ch 9Label 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 11Clone, Branch, CommitComplete the full Git cycle: clone → branch → edit → stage → commit → push
Ch 12Review a PR from VS CodeOpen a diff, use Accessible Diff Viewer (F7), leave a comment
Ch 13First Copilot ConversationAsk Copilot Chat a question about your repo and read the response
Ch 14Exercise AComplete a web-based PR review using screen reader navigation
Ch 14Exercise BUse the VS Code Accessible Diff Viewer on the same PR
Ch 14Exercise CCompare web vs. VS Code review and document findings
Ch 15Exercise AUse an existing issue template in Accessibility Agents
Ch 15Exercise BCreate an accessibility bug report template locally
Ch 15Exercise CSubmit your template upstream via a real PR
Ch 15Exercise DDesign a custom template for your own project
Ch 16Exercise 1Generate a template with the @template-builder agent
Ch 16Exercise 2Extend the @template-builder agent with new workflows
Ch 16Exercise 3Practice iterative refinement with agents
- -
    -
  • Chapters 0-10: Not started In progress Complete
    • -
  • Time: ~8 hours (includes workshop time)
    • -
-

Advanced Path (Day 2)

-
    -
  • Chapters 11-16: Not started In progress Complete
    • -
  • Time: ~5 hours (includes exercises)
    • -
-

Full Curriculum

-
    -
  • All chapters + appendices: Not started In progress Complete
    • -
  • Time: ~13 hours total
    • -
-

Estimated Time Breakdown

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SectionTimeStatus
Pre-Workshop30 min
Day 1 Core (Ch 0-10)8 hrs
Day 2 Advanced (Ch 11-16)5 hrs
Reference/AppendicesAs needed
Total~13 hrs
-

Learning Path by Role

-

If You're a Contributor (New to collaborative coding)

-

Recommended order:

-
    -
  1. Ch 0 (Setup) - 30 min
    2. -
  2. Ch 1 (Structure) - 1 hr
    3. -
  3. Ch 4 (Issues) - 1 hr
    4. -
  4. Ch 6 (PRs) - 1 hr
    5. -
  5. Ch 14 (Accessible Review) - 1.5 hrs
    6. -
  6. Ch 16 (Accessibility Agents) - 1.5 hrs
    7. -
-

Total: ~6.5 hours

-

If You're a Maintainer (Manage projects)

-

Recommended order:

-
    -
  1. Ch 0 (Setup) - 30 min
    2. -
  2. Ch 9 (Labels/Milestones) - 45 min
    3. -
  3. Ch 15 (Issue Templates) - 1.5 hrs
    4. -
  4. Ch 14 (Accessible Code Review) - 1.5 hrs
    5. -
  5. Ch 16 (Accessibility Agents) - 1.5 hrs
    6. -
-

Total: ~5.5 hours

-

If You're a Facilitator (Teaching others)

-

Recommended order:

-
    -
  1. Full curriculum (0-16) - 11+ hours
    2. -
  2. Read FACILITATOR.md
    3. -
  3. Practice all exercises before leading workshop
    4. -
-

Total: ~15 hours

-

Next Steps After Completing This Curriculum

-

Keep Learning

-
    -
  • Work on real open-source projects
    • -
  • Practice code review on real PRs
    • -
  • Create templates for your own repositories
    • -
  • Experiment with agents on your own code
    • -
-

Share Your Knowledge

-
    -
  • Lead a workshop for your team
    • -
  • Contribute improvements to this guide
    • -
  • Help others in GitHub discussions/issues
    • -
-

Advanced Topics (Not in This Guide)

-
    -
  • GitHub Advanced Security features
    • -
  • Custom GitHub Actions
    • -
  • Codespaces for efficient development
    • -
  • GitHub Enterprise features
    • -
-

Questions or Stuck?

-
    -
  • Check: TROUBLESHOOTING.md (common issues & fixes)
    • -
  • Search: QUICK_REFERENCE.md (commands & shortcuts)
    • -
  • Look up: docs/appendix-u-resources.md (external documentation)
    • -
  • Define: docs/appendix-a-glossary.md (term definitions)
    • -
  • Ask: Open an issue or discussion on GitHub
    • -
-

Last updated: February 2026
Print or bookmark this progress tracker to chart your journey!

- -
- - - \ No newline at end of file diff --git a/html/QUICK_REFERENCE.html b/html/QUICK_REFERENCE.html deleted file mode 100644 index a97f267..0000000 --- a/html/QUICK_REFERENCE.html +++ /dev/null @@ -1,486 +0,0 @@ - - - - - - - Quick Reference Guide - GIT Going with GitHub - - - - - - - - -
-

Quick Reference Guide

-

Essential Commands, Shortcuts, and File Locations

-

Screen Reader Commands for GitHub

-

NVDA (Windows)

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TaskCommand
Jump to navigationD
Jump to search/main contentD (cycle through landmarks)
Read next headingH
Navigate by heading level1-6 (headings), T (table), B (button), L (list)
Open Focus ModeNVDA+Space (then navigate)
Announce current lineNVDA+Up
Read all from cursorNVDA+Down
Stop readingControl
Go to link listNVDA+F7
Switch to Browse ModeNVDA+Space (in a page)
-

JAWS (Windows)

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TaskCommand
Virtual cursor browseSpacebar
Navigate headingsH or Numpad 5
Navigate by level1-6
Open navigation barInsert+F5
List linksInsert+Ctrl+L
List headingsInsert+F6
Toggle Focus ModeEnter (on a page)
Announce all textInsert+Down
Stop readingControl
-

VoiceOver (macOS)

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TaskCommand
Navigate web rotorVO+U
Next/previous headingVO+Down, VO+Up
Next/previous linkVO+Right, VO+Left (with Quick Nav)
Activate elementVO+Space
Read from cursorVO+A
Stop readingControl
Headings rotorVO+U → H (then navigate)
Form controls rotorVO+U → F
-

GitHub Navigation Shortcuts (All Browsers)

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ActionKeyboard
Open command paletteCmd+. (macOS) / Ctrl+. (Windows)
Jump to IssuesG then I
Jump to Pull RequestsG then P
Jump to ProjectsG then B
Open issue/PRO then Enter
Navigate PR tabs (Conversation/Commits/Files)← / → Arrow keys
Focus on searchS or /
Go to codeG then C
-

VS Code Keyboard Shortcuts

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ActionWindows/LinuxmacOS
Open Copilot ChatCtrl+Shift+ICmd+Shift+I
Open terminalCtrl+ `Ctrl+ `
Open file searchCtrl+PCmd+P
Find in fileCtrl+FCmd+F
Replace in fileCtrl+HCmd+H
Open command paletteCtrl+Shift+PCmd+Shift+P
ExtensionsCtrl+Shift+XCmd+Shift+X
Reload window(see command palette)(see command palette)
Accessible Diff ViewerF7F7
Accessible ViewAlt+F2Option+F2
Format documentShift+Alt+FShift+Option+F
-

Git Commands (Terminal)

-

Repository Setup

-
git clone https://github.com/[USERNAME]/[REPO].git    # Clone your fork
-cd [REPO]                                               # Enter folder
-git remote -v                                           # View remotes
-git remote add upstream https://github.com/[ORIGINAL]   # Add upstream
-

Branch Workflow

-
git checkout -b [branch-name]           # Create and switch to branch
-git branch -a                            # List all branches
-git branch -d [branch-name]              # Delete local branch
-git push origin [branch-name]            # Push branch to GitHub
-

Staging and Committing

-
git status                               # See what changed
-git add [file]                           # Stage specific file
-git add .                                # Stage all changes
-git commit -m "message"                  # Commit with message
-git push origin [branch-name]            # Push commits
-

Pulling Updates

-
git pull origin main                     # Pull latest from your fork
-git pull upstream main                   # Pull latest from upstream
-git fetch upstream                       # Fetch without merging
-

File Locations Reference

-

Template & Agent Files

-
.github/
-├── ISSUE_TEMPLATE/
-│   ├── accessibility-bug.yml            ← Accessibility issue template
-│   ├── bug-report-template.yml
-│   └── feature-request.yml
-├── agents/
-│   ├── daily-briefing.agent.md
-│   ├── issue-tracker.agent.md
-│   ├── pr-review.agent.md
-│   ├── analytics.agent.md
-│   ├── insiders-a11y-tracker.agent.md
-│   └── template-builder.agent.md        ← The agent for building templates
-├── pull_request_template.md             ← Default PR template
-├── workflows/
-│   ├── learning-room-pr-bot.yml
-│   ├── skills-progression.yml
-│   └── student-grouping.yml
-└── data/
-    ├── challenge-progression.json
-    └── student-roster.json
-

Documentation Files

-
docs/
-├── 00-pre-workshop-setup.md             ← Start here
-├── 01-understanding-github-web-structure.md
-├── 04-working-with-issues.md            ← File issues
-├── 06-working-with-pull-requests.md     ← Review PRs
-├── 14-accessible-code-review.md         ← Day 2 manual skill
-├── 15-issue-templates.md                ← Design templates (manual)
-├── 16-accessibility-agents.md                    ← Automate with agents
-└── appendix-a-glossary.md               ← Term definitions
-

YAML Template Structure (Quick Template)

-
name: Your Template Name
-description: One line description
-title: "[TAG] "
-labels: ["label1", "label2"]
-
-body:
-  - type: markdown
-    attributes:
-      value: |
-        ## Before you begin
-        Please search for existing issues.
-
-  - type: input
-    id: version
-    attributes:
-      label: Version Number
-      placeholder: "e.g., v2.4.1"
-    validations:
-      required: true
-
-  - type: textarea
-    id: description
-    attributes:
-      label: Description
-      description: Explain what happened
-      placeholder: "I was trying to... then..."
-    validations:
-      required: true
-
-  - type: dropdown
-    id: browser
-    attributes:
-      label: Browser
-      options:
-        - Chrome
-        - Firefox
-        - Safari
-    validations:
-      required: true
-
-  - type: checkboxes
-    id: checks
-    attributes:
-      label: Before Submitting
-      options:
-        - label: I searched for existing issues
-          required: true
-

Accessibility Testing Checklist (Quick)

-
    -
  • All form labels announced by screen reader
    • -
  • Required fields marked and announced as required
    • -
  • Dropdown options readable and selectable
    • -
  • No labels skipped (heading hierarchy: 1→2→3, not 1→3)
    • -
  • Link text is descriptive (not "click here")
    • -
  • Color not the only way to convey information
    • -
  • Tested on: NVDA JAWS VoiceOver
    • -
-

Common YAML Errors & Fixes

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ErrorCauseFix
Red squiggles on colonsMissing colon after keyAdd : after field name
Indentation errorsMixed spaces/tabsUse spaces only (2 or 4)
Unmatched quotesMissing closing quoteCheck all " have closing pair
Field not showingWrong type: or missing id:Verify field has all required properties
Dropdown no optionsMissing options: listAdd options: with indented list
-

Where to Find Help

- - - - - - - - - - - - - - - - - - - - - - - -
TopicFile
TroubleshootingTROUBLESHOOTING.md
Resources & setupdocs/appendix-u-resources.md
Glossary & termsdocs/appendix-a-glossary.md
Screen reader guidedocs/appendix-b-screen-reader-cheatsheet.md
-

Accessibility Hotkeys Summary

-

NVDA + JAWS (same): Browse web content with H (headings), T (tables), B (buttons), L (lists)
VoiceOver: Use VO+U to open rotor, then navigate by category (Headings, Links, Form Controls)
VS Code: F7 = Accessible Diff, Alt+F2 = Accessible View

-

Last updated: February 2026 | For latest, see README.md

- -
- - - \ No newline at end of file diff --git a/html/README.html b/html/README.html index be62c1d..e277bbb 100644 --- a/html/README.html +++ b/html/README.html @@ -78,7 +78,7 @@

A Workshop by Student opt-in and waitlist workflow Discussions @@ -100,7 +100,7 @@

A Workshop by 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. By the end of Day 2, your name is in its commit history.

+

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?

@@ -110,7 +110,7 @@

What Is This Event?

  • 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 made real contributions to a real repository. Not simulated. Not pretend. Real.

    +

    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:

      @@ -137,7 +137,7 @@

      Two-Day Overview

      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), run agentic workflows in the cloud, and ship a real PR upstream to community-access/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

      @@ -155,17 +155,18 @@

      The Journey Arc

      Day 2 - Deepen with VS Code + Accessibility Agents Learn VS Code basics → Copilot inline → Copilot Chat - @daily-briefing → @issue-tracker → @pr-review → @analytics → ship upstream + @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 Day 2, you will have:

      +

      By the end of the Day 2 core path, you will have:

      • A fork of accessibility-agents with your personalized preferences
        • -
      • At least one merged PR in a real open source project
        • -
      • Your name in the commit history of community-access/accessibility-agents
        • +
      • 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. Read them in order for the full experience, or jump to what you need.

      +

      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.

      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.

      @@ -183,7 +184,7 @@

      Your Challenges

      HTML Version Available: All markdown documentation is automatically converted to HTML format. After cloning the repository, you can browse the html/ directory for web-formatted versions of every document. See BUILD.md for details.

      -

      Audio Series Available: Every chapter and appendix has a companion podcast episode - a conversational two-host overview perfect for previewing concepts or reducing screen reader fatigue. Browse all 44 episodes or subscribe via RSS.

      +

      Audio Series Available: Every chapter and appendix has a companion podcast episode - a conversational two-host overview perfect for previewing concepts or reducing screen reader fatigue. The refreshed catalog now covers 54 companion episodes, with Challenge Coach episodes planned as a separate teaching layer. Browse the podcast episodes or subscribe via RSS.

      Quick Navigation

      @@ -199,6 +200,11 @@

      Quick Navigation

      +Start +Get Going with GitHub +GitHub Classroom onboarding, Learning Room first steps, support, and tool choice + + 00 Pre-Workshop Setup Everything to install and configure before Day 1 @@ -221,7 +227,7 @@

      Quick Navigation

      04 The Learning Room -Your shared practice space, branching, committing, and PR workflow +Your private practice repository, branching, committing, and PR workflow 05 @@ -500,7 +506,7 @@

      This Repository's Structure

      │ ├── roster-template.csv │ ├── grading-guide.md │ └── teardown-checklist.md -├── learning-room/ -- Practice target for contribution exercises +├── learning-room/ -- GitHub Classroom template copied into each student's private repo │ ├── README.md │ └── docs/ │ ├── welcome.md -- Has TODO sections for you to complete @@ -583,5 +589,6 @@

      License

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/REGISTER.html b/html/REGISTER.html index ec047f5..3ee543d 100644 --- a/html/REGISTER.html +++ b/html/REGISTER.html @@ -4,7 +4,7 @@ - Registration Closed - GIT Going with GitHub + Student Opt-In - GIT Going with GitHub @@ -28,7 +28,7 @@
      -

      Registration Closed

      +

      Student Opt-In

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

      -

      Registration for GIT Going with GitHub is now closed.

      -

      Thank you to everyone who registered! We are excited to learn together.

      +

      Join the next GIT Going with GitHub cohort

      +

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

      @@ -70,56 +70,45 @@

      Registration for G

      - - + + - - - - - - + + + + + +
      DatesSaturday, March 7 and Sunday, March 8, 2026StatusOpen for student opt-in
      Time12:00 PM - 8:00 PM Eastern (both days)
      LocationOnline via ZoomCurrent confirmed registrationsLoading...
      Cost Free
      FormGitHub issue form with automated confirmation and waitlist handling
      -

      Already registered? Complete the Pre-Workshop Setup Guide before March 7. It walks you through GitHub account setup, screen reader configuration, VS Code, and GitHub Copilot - with instructions for NVDA, JAWS, and VoiceOver.

      -

      Questions?

      -

      Need help? File an issue in the workshop repository or join the Discussion Forum.

      -

      A Community Access initiative.

      -

      Important: You must be signed into your GitHub account before clicking the link below. If you are not signed in, go to GitHub and sign in first.

      +

      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 Step 2 - File your registration issue

      +

      Start Student Opt-In Form

      -

      Note: The issue title is pre-filled and required by GitHub. You do not need to change it - just fill out the form fields below it and submit.

      -

      The form asks for:

      +

      What happens automatically

        -
      • First Name (required) - your first name as you would like to be addressed during the workshop
        • -
      • Last Name (required)
        • -
      • Email Address (required) - we will use this to send you Zoom links and workshop materials before the event
        • -
      • GitHub Proficiency Level (required) - a dropdown from "Brand new" to "Experienced" so we can prepare the right level of support
        • -
      • Primary Screen Reader (optional) - which screen reader you primarily use (NVDA, JAWS, VoiceOver, or other)
        • -
      • Questions or Accommodations (optional) - anything we should know or arrange before the workshop
        • +
      • 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.
      -

      After you submit, you will receive an automated confirmation comment on your issue. Your GitHub username is captured automatically - you do not need to enter it.

      -

      What Happens Next

      -

      Once you have completed both steps:

      -
        -
      1. You will receive a Zoom confirmation email (Step 1)
        2. -
      2. You will see a confirmation comment on your GitHub issue (Step 2)
        3. -
      3. Complete the Pre-Workshop Setup Guide before March 7 - it covers GitHub account setup, screen reader configuration, VS Code, and GitHub Copilot
        4. -
      4. Questions? File an issue in the workshop repository
        5. -
      -

      While You Wait

      +

      Important note

      +

      Registration issues are public because this repository is public.

      +

      Need help?

      +

      A Community Access initiative.

      + - \ No newline at end of file + diff --git a/html/REGISTRATION-ADMIN.html b/html/REGISTRATION-ADMIN.html deleted file mode 100644 index 623577d..0000000 --- a/html/REGISTRATION-ADMIN.html +++ /dev/null @@ -1,149 +0,0 @@ - - - - - - - Registration Administration Guide - GIT Going with GitHub - - - - - - - - -
      -

      Registration Administration Guide

      -

      This document explains how the registration system works and how to manage it. This file is not committed to the repository.

      -

      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.

      -

      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
        • -
      • 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
        • -
      - -
      - - - \ No newline at end of file diff --git a/html/REPOSITORY_SECURITY.html b/html/REPOSITORY_SECURITY.html index 2a24055..ea59965 100644 --- a/html/REPOSITORY_SECURITY.html +++ b/html/REPOSITORY_SECURITY.html @@ -407,5 +407,6 @@

      Contact & Support

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/SECURITY.html b/html/SECURITY.html index 5529eeb..3f8e45c 100644 --- a/html/SECURITY.html +++ b/html/SECURITY.html @@ -157,5 +157,6 @@

      Credit

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/TROUBLESHOOTING.html b/html/TROUBLESHOOTING.html deleted file mode 100644 index f83ab8c..0000000 --- a/html/TROUBLESHOOTING.html +++ /dev/null @@ -1,1039 +0,0 @@ - - - - - - - Troubleshooting Guide - GIT Going with GitHub - - - - - - - - -
      -

      Troubleshooting Guide

      -

      Common Issues and Solutions

      -
      -

      How to use this guide: Find your problem in the Table of Contents, or use Ctrl+F (browser) to search by keyword or error message. Every problem follows the same format: Symptoms → Cause → Solution → Prevention (where applicable).

      -
      -

      Table of Contents

      - -

      Setup and Installation

      -

      Problem: Git is not installed

      -

      Symptoms: Terminal shows git: command not found, 'git' is not recognized, or similar error.

      -

      Solution:

      -
        -
      1. Windows: Download and install Git for Windows from the Git for Windows download page. During installation, accept the defaults. Restart your terminal after installation.
        2. -
      2. macOS: Run xcode-select --install (installs Git as part of Command Line Tools), or download from the Git for macOS download page, or run brew install git if Homebrew is installed.
        3. -
      3. Linux (Debian/Ubuntu): sudo apt update && sudo apt install git
        4. -
      4. Linux (Fedora): sudo dnf install git
        5. -
      5. Verify: Close and reopen your terminal, then type git --version
        6. -
      -

      If it still does not work after installation:

      -
        -
      • Windows: Git may not be in your PATH. Search for "Git Bash" in the Start menu and use that terminal instead. Or add Git to PATH: Settings → System → Advanced → Environment Variables → edit PATH → add C:\Program Files\Git\cmd
        • -
      • macOS: If xcode-select hangs, try sudo xcode-select --reset first
        • -
      -

      Prevention: Complete Pre-Workshop Setup before starting.

      -

      Problem: Node.js or npm is not installed

      -

      Symptoms: npm: command not found or node: command not found when trying to build HTML files.

      -

      Solution:

      -
        -
      1. Download Node.js LTS from the Node.js download page
        2. -
      2. Install with default settings
        3. -
      3. Close and reopen your terminal
        4. -
      4. Verify: node --version and npm --version
        5. -
      -

      Note: Node.js is only needed if you want to build the HTML versions of the workshop documents. It is not required for the workshop itself.

      -

      Problem: GitHub CLI (gh command) not found

      -

      Symptoms: gh issue list or other gh commands show "command not found."

      -

      Solution:

      -
        -
      1. Install GitHub CLI from https://cli.github.com/
        2. -
      2. Windows: Download the .msi installer or use winget install --id GitHub.cli
        3. -
      3. macOS: brew install gh
        4. -
      4. Linux: See the GitHub CLI Linux installation guide
        5. -
      5. Authenticate: gh auth login → follow prompts → choose HTTPS or SSH → authenticate via browser
        6. -
      6. Verify: gh --version
        7. -
      -

      Note: GitHub CLI is optional but helpful for faster issue and PR workflows from the terminal.

      -

      Problem: No GitHub account

      -

      Symptoms: Cannot clone, push, fork, or make pull requests.

      -

      Solution:

      -
        -
      1. Create a free account at https://github.com/signup
        2. -
      2. Verify your email address (check inbox for confirmation)
        3. -
      3. Optionally enable two-factor authentication (recommended): https://github.com/settings/security
        4. -
      -

      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.

      -

      Problem: Cannot fork the repository

      -

      Symptoms: Click "Fork" but nothing happens, or you see an error message.

      -

      Solution:

      -
        -
      1. Verify you are signed in to GitHub
        2. -
      2. Check if you already have a fork: Go to your profile → Repositories → search for the repo name
        3. -
      3. If you already forked it, navigate to your existing fork instead
        4. -
      4. If the Fork button is not visible, the repository may be restricted - contact the facilitator
        5. -
      -

      Problem: VS Code cannot be installed

      -

      Symptoms: Installation fails, or you are on a restricted device.

      -

      Solution:

      -
        -
      • Corporate/restricted device: Ask your IT department to allow VS Code, or use the portable ZIP version: https://code.visualstudio.com/docs/editor/portable
        • -
      • Chromebook: Use github.dev (press . on any repo) for Day 1. For Day 2, consider GitHub Codespaces: see Appendix N
        • -
      • Older OS: VS Code requires Windows 10+, macOS 10.15+, or a modern Linux distribution
        • -
      -

      Git Configuration and Operations

      -

      Problem: Git asks for your name and email before committing

      -

      Symptoms: Please tell me who you are error when running git commit.

      -

      Solution:

      -
      git config --global user.name "Your Name"
-git config --global user.email "your_email@example.com"
      -

      Use the same email address as your GitHub account so commits are attributed to your profile.

      -

      Problem: "Fatal: not a git repository"

      -

      Symptoms: Any git command returns fatal: not a git repository (or any of the parent directories): .git

      -

      Solution:

      -
        -
      1. You are not inside a Git repository. Check your current folder:
          -
        • Windows PowerShell: Get-Location
          • -
        • macOS/Linux: pwd
          • -
        -
        2. -
      2. Navigate to your cloned repository: cd path/to/your-repo
        3. -
      3. Verify it is a Git repo: git status
        4. -
      4. If the folder does not contain a .git directory, you need to clone the repository again:
        git clone https://github.com/YOUR-USERNAME/REPO-NAME.git
-cd REPO-NAME
        -
        5. -
      -

      Problem: git pull says "Already up to date" but files seem outdated

      -

      Symptoms: You know changes were made upstream, but git pull reports no changes.

      -

      Solution:

      -
        -
      1. Check which remote you are pulling from: git remote -v
        2. -
      2. If you forked the repo, you need to pull from upstream, not your fork:
        git remote add upstream https://github.com/ORIGINAL-OWNER/REPO.git
-git fetch upstream
-git merge upstream/main
        -
        3. -
      3. Verify you are on the correct branch: git branch (the current branch has a *)
        4. -
      -

      Problem: "Detached HEAD" message

      -

      Symptoms: Git says You are in 'detached HEAD' state and your commits may be lost.

      -

      Solution:

      -
        -
      1. This means you are not on a branch. Create one to save your work:
        git checkout -b my-new-branch
        -
        2. -
      2. If you want to return to main: git checkout main
        3. -
      3. If you already made commits in detached HEAD, create a branch first (step 1), then those commits are safe.
        4. -
      -

      Problem: Accidentally committed to the wrong branch

      -

      Symptoms: Your changes are on main instead of a feature branch.

      -

      Solution (if you have not pushed yet):

      -
        -
      1. Create a new branch from your current position: git branch my-feature
        2. -
      2. Reset main back: git reset --hard HEAD~1 (undoes the last commit on main)
        3. -
      3. Switch to your feature branch: git checkout my-feature
        4. -
      4. Your commit is now on my-feature and main is clean
        5. -
      -

      If you already pushed: Do not force-push. Instead, create a new branch from main, cherry-pick your commit, and open a PR from that branch.

      -

      Problem: "Permission denied" running git commands

      -

      Symptoms: error: insufficient permission or Permission denied on local git operations.

      -

      Solution:

      -
        -
      • Windows: Run your terminal as Administrator, or check that the repository folder is not read-only (right-click folder → Properties → uncheck Read-only)
        • -
      • macOS/Linux: Check folder ownership: ls -la .git/. If owned by root, fix with: sudo chown -R $(whoami) .
        • -
      • Antivirus: Some antivirus software blocks Git operations on .git directories. Add your repository folder to the antivirus exclusion list.
        • -
      -

      Problem: Line ending warnings ("LF will be replaced by CRLF")

      -

      Symptoms: Git shows warnings about line endings when staging files.

      -

      Solution:

      -
        -
      1. This is informational, not an error. Git is converting line endings for your platform.
        2. -
      2. To suppress the warning: git config --global core.autocrlf true (Windows) or git config --global core.autocrlf input (macOS/Linux)
        3. -
      3. In VS Code, the bottom-right shows "LF" or "CRLF" - click to change per file if needed
        4. -
      -

      GitHub Authentication

      -

      Problem: Authentication fails when pushing

      -

      Symptoms: "Permission denied," "Authentication failed," or "Could not read from remote repository" when running git push.

      -

      Cause A: No SSH key set up (if using SSH URLs)

      -
        -
      1. Generate key: ssh-keygen -t ed25519 -C "your_email@example.com"
        2. -
      2. Press Enter three times to accept defaults
        3. -
      3. Copy your public key:
          -
        • Windows: type %USERPROFILE%\.ssh\id_ed25519.pub (then select and copy)
          • -
        • macOS: cat ~/.ssh/id_ed25519.pub | pbcopy
          • -
        • Linux: cat ~/.ssh/id_ed25519.pub (then copy the output)
          • -
        -
        4. -
      4. Add to GitHub: https://github.com/settings/ssh/new → paste key
        5. -
      5. Test: ssh -T git@github.com → should say "Hi [USERNAME]!"
        6. -
      -

      Cause B: Using HTTPS with a password instead of a token

      -
        -
      1. GitHub no longer accepts account passwords for HTTPS Git operations
        2. -
      2. Generate a Personal Access Token: https://github.com/settings/tokens → "Generate new token (classic)" → select repo scope → generate
        3. -
      3. Use the token as your password when Git prompts
        4. -
      4. Store credentials securely:
          -
        • Windows: git config --global credential.helper manager
          • -
        • macOS: git config --global credential.helper osxkeychain
          • -
        • Linux: git config --global credential.helper cache (temporary) or use a keyring helper
          • -
        -
        5. -
      -

      Cause C: Wrong remote URL

      -
        -
      1. Check: git remote -v
        2. -
      2. If URLs point to the wrong repository, fix: git remote set-url origin YOUR-CORRECT-URL
        3. -
      -

      Cause D: Expired token or revoked SSH key

      -
        -
      1. Check SSH keys: https://github.com/settings/keys - is your key listed and not expired?
        2. -
      2. Check tokens: https://github.com/settings/tokens - is your token still active?
        3. -
      3. Regenerate if expired
        4. -
      -

      See Appendix D (Git Authentication) for complete setup instructions.

      -

      Problem: SSH key passphrase prompts every time

      -

      Symptoms: Git asks for your SSH passphrase on every push/pull operation.

      -

      Solution: Add your key to the SSH agent so it is remembered:

      -
        -
      • Windows (Git Bash):
        eval "$(ssh-agent -s)"
-ssh-add ~/.ssh/id_ed25519
        -
        • -
      • macOS:
        ssh-add --apple-use-keychain ~/.ssh/id_ed25519
        -Then add to ~/.ssh/config:
        Host github.com
-  AddKeysToAgent yes
-  UseKeychain yes
-  IdentityFile ~/.ssh/id_ed25519
        -
        • -
      • Linux:
        eval "$(ssh-agent -s)"
-ssh-add ~/.ssh/id_ed25519
        -
        • -
      -

      Problem: "Support for password authentication was removed"

      -

      Symptoms: Git prompts for a password and rejects it with a message about deprecation.

      -

      Solution: You need a Personal Access Token instead of your password. See "Authentication fails when pushing" → Cause B above.

      -

      GitHub Web Interface

      -

      Problem: GitHub page layout looks different from the guide

      -

      Symptoms: Buttons, menus, or sections are in different positions than described.

      -

      Solution: GitHub updates its interface regularly. The core structure (tabs, headings, landmarks) remains consistent. Navigate by role instead of position:

      -
        -
      • Use B for buttons, H for headings, D for landmarks
        • -
      • Use ? on any GitHub page to see current keyboard shortcuts
        • -
      • Use the Elements List (NVDA+F7 / Insert+F3 / VO+U) to find specific elements
        • -
      -

      Problem: Hovercards interfere with screen reader navigation

      -

      Symptoms: When arrowing through links, a popup overlay appears and disrupts reading flow.

      -

      Solution:

      -
        -
      1. Go to https://github.com/settings/accessibility
        2. -
      2. Uncheck "Hovercards" (or the equivalent setting for reducing motion/overlays)
        3. -
      3. Save changes
        4. -
      4. This is covered in Pre-Workshop Setup, Step 4
        5. -
      -

      Problem: GitHub shows "Loading..." or blank content

      -

      Symptoms: Parts of a GitHub page do not render, or show a loading spinner indefinitely.

      -

      Solution:

      -
        -
      1. Hard refresh: Ctrl+Shift+R (or Cmd+Shift+R on Mac)
        2. -
      2. Clear browser cache: Ctrl+Shift+Delete → clear cached files
        3. -
      3. Try a different browser (Chrome, Firefox, Edge, Safari)
        4. -
      4. Check https://www.githubstatus.com/ for outages
        5. -
      5. Disable browser extensions that might interfere (ad blockers, privacy extensions)
        6. -
      -

      Problem: "File finder" or "Go to file" does not work

      -

      Symptoms: Pressing T on a repository page does not open the file search.

      -

      Solution:

      -
        -
      1. Make sure you are in Browse Mode (screen reader), not Focus Mode
        2. -
      2. Click somewhere on the page first to ensure GitHub has keyboard focus
        3. -
      3. Try Shift+T if T alone does not trigger it
        4. -
      4. As an alternative, use the search bar (/) and type filename: followed by the name
        5. -
      -

      Problem: Cannot find the "Fork" button

      -

      Symptoms: You are on a repository page but cannot locate the Fork button.

      -

      Solution:

      -
        -
      1. The Fork button is near the top of the repository page, after the Star and Watch buttons
        2. -
      2. Screen reader: Press B repeatedly to find buttons - look for "Fork"
        3. -
      3. If the button says "Forked from..." instead, you already have a fork. Navigate to your fork at github.com/YOUR-USERNAME/REPO-NAME
        4. -
      -

      Repository Navigation and Cloning

      -

      Problem: Clone fails with "Repository not found"

      -

      Symptoms: git clone returns ERROR: Repository not found or fatal: remote error: Repository not found.

      -

      Solution:

      -
        -
      1. Check the URL: Copy it directly from the GitHub page (Code button → HTTPS or SSH tab)
        2. -
      2. Private repository: You need read access. Ask the owner to add you as a collaborator.
        3. -
      3. Typo in username or repo name: URLs are case-sensitive for SSH
        4. -
      4. Authentication: If using HTTPS, verify your credentials are correct (see GitHub Authentication section)
        5. -
      -

      Problem: Clone is extremely slow

      -

      Symptoms: git clone starts but takes a very long time or hangs.

      -

      Solution:

      -
        -
      1. The repository may be very large. Try a shallow clone: git clone --depth 1 URL
        2. -
      2. Check your internet connection - try cloning a small test repo first
        3. -
      3. If behind a corporate proxy, configure Git: git config --global http.proxy http://proxy-address:port
        4. -
      4. Try switching between HTTPS and SSH - one may be faster on your network
        5. -
      -

      Problem: Cannot find a file that the chapter references

      -

      Symptoms: A chapter says "open file X" but the file does not exist in the repository.

      -

      Solution:

      -
        -
      1. Verify you are on the correct branch: git branch → git checkout main
        2. -
      2. Pull the latest changes: git pull origin main
        3. -
      3. Check spelling and case - filenames are case-sensitive on macOS and Linux
        4. -
      4. The file may be in a subfolder - use git ls-files | grep -i filename to search
        5. -
      5. In VS Code, use Ctrl+P and type part of the filename
        6. -
      -

      Branches, Merging, and Conflicts

      -

      Problem: Large merge conflict - do not know how to resolve

      -

      Symptoms: File shows <<<<<<< HEAD ... ======= ... >>>>>>> branch-name markers. Multiple files may be affected.

      -

      Solution - Quick approach (choose one version):

      -
        -
      • Keep YOUR changes: git checkout --ours [filename] → git add [filename]
        • -
      • Keep THEIR changes: git checkout --theirs [filename] → git add [filename]
        • -
      • Abort the merge entirely: git merge --abort (returns to pre-merge state, nothing lost)
        • -
      -

      Solution - Manual merge (combine both):

      -
        -
      1. Open the file in VS Code
        2. -
      2. Screen reader users: search for <<<<<<< to find each conflict
        3. -
      3. Each conflict has three parts:
          -
        • Between <<<<<<< and ======= → your changes
          • -
        • Between ======= and >>>>>>> → their changes
          • -
        -
        4. -
      4. Edit the file to keep what you want
        5. -
      5. Delete all conflict markers (<<<<<<<, =======, >>>>>>>)
        6. -
      6. Save, then: git add [filename] → git commit -m "Resolved merge conflict"
        7. -
      -

      In VS Code: VS Code detects conflicts and shows "Accept Current Change," "Accept Incoming Change," and "Accept Both Changes" buttons above each conflict. Screen reader users: these are announced as CodeLens actions above the conflict markers.

      -

      Prevention:

      -
        -
      • Pull from upstream regularly: git pull upstream main
        • -
      • Keep PRs small and focused
        • -
      • Communicate with teammates about which files you are editing
        • -
      -

      Problem: "Your branch is behind" or "Cannot fast-forward"

      -

      Symptoms: git push is rejected because your branch is behind the remote.

      -

      Solution:

      -
        -
      1. Pull first: git pull origin your-branch
        2. -
      2. Resolve any conflicts if prompted
        3. -
      3. Then push: git push origin your-branch
        4. -
      -

      Do not force-push (git push --force) unless you understand the consequences - it overwrites the remote branch and can destroy other people's work.

      -

      Problem: Accidentally deleted a branch with unmerged work

      -

      Symptoms: You ran git branch -D branch-name and lost commits.

      -

      Solution: Git keeps deleted branch commits for ~30 days. Recover with:

      -
      git reflog                    # Find the commit hash of your work
-git checkout -b recovered-branch COMMIT-HASH
      -

      Problem: Cannot switch branches - "Please commit or stash your changes"

      -

      Symptoms: git checkout other-branch fails because you have uncommitted changes.

      -

      Solution (choose one):

      -
        -
      1. Commit your work: git add . → git commit -m "WIP: saving progress"
        2. -
      2. Stash your work: git stash → switch branches → git stash pop when you return
        3. -
      3. Discard changes (irreversible): git checkout -- . (discards all uncommitted changes)
        4. -
      -

      Issues and Pull Requests

      -

      Problem: Cannot create an issue - "Issues are disabled"

      -

      Symptoms: The Issues tab is missing or says issues are disabled.

      -

      Solution: The repository owner has disabled issues. You can:

      -
        -
      1. Check if the project uses Discussions instead (look for a Discussions tab)
        2. -
      2. Open an issue on the parent repository (if this is a fork)
        3. -
      3. Contact the maintainer through other channels listed in the repository's README
        4. -
      -

      Problem: PR says "Unable to merge" or "Merge blocked"

      -

      Symptoms: The merge button is grayed out or shows a warning.

      -

      Cause A: Merge conflicts

      -
        -
      • Resolve conflicts first (see "Branches, Merging, and Conflicts" section)
        • -
      -

      Cause B: Required status checks failing

      -
        -
      • Scroll to the "Checks" section of the PR
        • -
      • Click the failing check to see the error
        • -
      • Fix the issue and push a new commit
        • -
      -

      Cause C: Required reviews

      -
        -
      • The repository requires one or more approving reviews before merging
        • -
      • Request a review from a teammate or the maintainer
        • -
      -

      Cause D: Branch protection rules

      - -

      Problem: PR shows wrong base branch

      -

      Symptoms: Your PR targets the wrong branch (e.g., targeting your fork's main instead of the upstream main).

      -

      Solution:

      -
        -
      1. On the PR page, click "Edit" next to the base branch
        2. -
      2. Change the base repository and branch to the correct target
        3. -
      3. If you cannot edit it, close the PR and create a new one with the correct base
        4. -
      -

      Problem: PR "Files Changed" tab shows too many changes

      -

      Symptoms: Your PR shows changes you did not make - dozens or hundreds of files.

      -

      Solution:

      -
        -
      1. Your branch likely diverged from main. Update it:
        git checkout your-branch
-git fetch upstream
-git rebase upstream/main
-git push --force-with-lease origin your-branch
        -
        2. -
      2. The PR should now show only your changes
        3. -
      3. If you are unsure, close the PR, create a fresh branch from main, re-apply your changes, and open a new PR
        4. -
      -

      Templates and YAML

      -

      Problem: Template not showing in GitHub issue creation

      -

      Symptoms: Click "New Issue" but your custom template does not appear - only "Blank" shows.

      -

      Cause A: File in wrong location

      -
        -
      • Must be: .github/ISSUE_TEMPLATE/your-template.yml
        • -
      • Not: .github/ISSUE_TEMPLATE/your-template.md (wrong extension for form templates)
        • -
      • Not: .github/your-template.yml (wrong folder)
        • -
      • Not: .github/issue_template/ (case-sensitive on some systems)
        • -
      -

      Cause B: YAML syntax errors

      -
        -
      • Check for:
          -
        • Missing colons: name: not name
          • -
        • Tabs instead of spaces (YAML requires spaces)
          • -
        • Mismatched or unclosed quotes
          • -
        • Wrong indentation level
          • -
        -
        • -
      • Validate at: https://www.yamllint.com/
        • -
      -

      Cause C: Not on the default branch

      -
        -
      • Templates must be on the main (or master) branch
        • -
      • Verify: git branch → push to main: git push origin main
        • -
      • Check on GitHub.com: browse to .github/ISSUE_TEMPLATE/ folder
        • -
      -

      Cause D: Browser cache

      -
        -
      • Hard refresh: Ctrl+Shift+R
        • -
      • Or try incognito/private browsing mode
        • -
      -

      Cause E: config.yml blocks blank issues but no templates exist

      -
        -
      • Check .github/ISSUE_TEMPLATE/config.yml - if blank_issues_enabled: false and no valid templates exist, the "New Issue" page will be empty
        • -
      -

      Problem: "Required field" validation not working in template

      -

      Symptoms: A field marked required: true allows submission without being filled.

      -

      Solution: The validations key must be at the same level as attributes, not inside it:

      -

      Correct:

      -
      - type: input
-  id: version
-  attributes:
-    label: Version
-  validations:
-    required: true
      -

      Wrong (too nested):

      -
      - type: input
-  attributes:
-    label: Version
-    validations:          # Wrong: inside attributes
-      required: true
      -

      After fixing, commit and push to main, then hard-refresh the browser.

      -

      Problem: Markdown inside template not rendering

      -

      Symptoms: Raw *asterisks* and #hashes appear instead of formatted text.

      -

      Solution:

      -
        -
      1. Use type: markdown for instructional text (not type: input or type: textarea)
        2. -
      2. Use the pipe | for multi-line content:
        - type: markdown
-  attributes:
-    value: |
-      ## Instructions
-      **Bold text** and *italic text*
        -
        3. -
      3. The | after value: tells YAML the content is multi-line and should preserve formatting
        4. -
      -

      Problem: YAML indentation error

      -

      Symptoms: Template fails to load or GitHub shows a YAML parse error.

      -

      Solution:

      -
        -
      1. YAML uses spaces only - never tabs. Configure your editor to insert spaces for tabs.
        2. -
      2. In VS Code: look at the bottom-right status bar - click "Spaces: 2" or "Tab Size" to set to spaces
        3. -
      3. Each nesting level should be 2 spaces
        4. -
      4. Validate your YAML at https://www.yamllint.com/ before committing
        5. -
      -

      VS Code Setup and Configuration

      -

      Problem: VS Code does not detect screen reader

      -

      Symptoms: VS Code opens but screen reader mode is not active - announcements are minimal or missing.

      -

      Solution:

      -
        -
      1. Press Shift+Alt+F1 to manually enable screen reader mode
        2. -
      2. Verify: Ctrl+Shift+P → type "accessibility" → "Toggle Screen Reader Accessibility Mode" should have a checkmark
        3. -
      3. Check setting: Ctrl+, → search editor.accessibilitySupport → set to on
        4. -
      4. If NVDA or JAWS was started after VS Code, restart VS Code
        5. -
      -

      Problem: VS Code is too verbose or too quiet with screen reader

      -

      Symptoms: Too many announcements, or important things are not announced.

      -

      Solution:

      -
        -
      • Too verbose: Open Settings (Ctrl+,) → search accessibility.verbosity → reduce verbosity for specific features
        • -
      • Too quiet: Check that editor.accessibilitySupport is set to on (not auto or off)
        • -
      • Audio signals: Search accessibility.signals in Settings → enable or disable specific sounds (error, warning, breakpoint, diff changes, etc.)
        • -
      -

      See Appendix M (VS Code Accessibility Reference) for all settings.

      -

      Problem: Cannot find a VS Code command

      -

      Symptoms: You know a command exists but cannot find it.

      -

      Solution:

      -
        -
      1. Open Command Palette: Ctrl+Shift+P
        2. -
      2. Start typing any part of the command name
        3. -
      3. Arrow through results - your screen reader announces each one
        4. -
      4. Press Enter to execute
        5. -
      5. If still not found, the command may require an extension to be installed
        6. -
      -

      Problem: VS Code terminal does not open

      -

      Symptoms: Ctrl+` (backtick) does not open the terminal, or the terminal panel is not accessible.

      -

      Solution:

      -
        -
      1. Try the command palette: Ctrl+Shift+P → "Terminal: Create New Terminal"
        2. -
      2. If the terminal opens but screen reader does not read it: the terminal uses a specialized accessibility mode. Press Alt+F2 to open the Accessible View of the terminal output.
        3. -
      3. Check that your default shell is configured: Ctrl+, → search "terminal.integrated.defaultProfile"
        4. -
      -

      Problem: VS Code settings changed unexpectedly

      -

      Symptoms: Colors, font size, or behavior changed without you doing anything.

      -

      Solution:

      -
        -
      1. A workspace settings file (.vscode/settings.json) may have been loaded when you opened the repository
        2. -
      2. Check: Ctrl+Shift+P → "Preferences: Open Workspace Settings"
        3. -
      3. Workspace settings override user settings. Remove entries you do not want.
        4. -
      4. To open your user settings instead: Ctrl+Shift+P → "Preferences: Open User Settings"
        5. -
      -

      VS Code Extensions

      -

      Problem: VS Code extensions not loading

      -

      Symptoms: Copilot or other extensions crash, do not appear, or show errors.

      -

      Solution:

      -
        -
      1. Reload the window: Ctrl+Shift+P → "Developer: Reload Window"
        2. -
      2. Check extension status: Ctrl+Shift+X → search for the extension → verify it shows as installed and enabled
        3. -
      3. Check for errors: View → Output → select the extension name from the dropdown
        4. -
      4. If an extension keeps crashing:
          -
        • Disable it: Ctrl+Shift+X → find extension → click Disable
          • -
        • Re-enable it and reload
          • -
        • If still broken, uninstall and reinstall the extension
          • -
        -
        5. -
      5. Check VS Code version: Ctrl+Shift+P → "About" - some extensions require recent VS Code versions
        6. -
      -

      Problem: GitHub Pull Requests extension not showing PRs

      -

      Symptoms: The extension is installed but no PRs appear in the sidebar.

      -

      Solution:

      -
        -
      1. Verify you are signed in: Click the GitHub icon in the lower-left → sign in if prompted
        2. -
      2. Make sure you opened a Git repository (not just a folder): Ctrl+Shift+G should show Source Control
        3. -
      3. Check that the repository has open PRs on GitHub
        4. -
      4. Reload: Ctrl+Shift+P → "Developer: Reload Window"
        5. -
      -

      Problem: Extension conflicts

      -

      Symptoms: Two extensions interfere with each other - duplicate features, broken shortcuts, or errors.

      -

      Solution:

      -
        -
      1. Open Extensions: Ctrl+Shift+X
        2. -
      2. Disable extensions one at a time to identify the conflict
        3. -
      3. Check the extension's marketplace page for known conflicts
        4. -
      4. If two extensions bind the same shortcut: Ctrl+Shift+P → "Preferences: Open Keyboard Shortcuts" → search for the shortcut → reassign one
        5. -
      -

      VS Code Source Control

      -

      Problem: Source Control panel is empty

      -

      Symptoms: Ctrl+Shift+G opens Source Control but no files or changes appear.

      -

      Solution:

      -
        -
      1. Verify you opened a Git repository: is there a .git folder in the root?
        2. -
      2. Make sure you made changes: edit a file, save it, then check Source Control again
        3. -
      3. If VS Code says "No source control providers registered": install the Git extension (usually built-in) or reload the window
        4. -
      -

      Problem: File saved but git status still shows as modified

      -

      Symptoms: You saved your work but git status says the file is changed.

      -

      Solution:

      -
        -
      1. Check for unsaved files: Look for a white dot on the editor tab (indicates unsaved)
        2. -
      2. Check line endings: The bottom-right of VS Code shows "LF" or "CRLF." If you changed the line ending, Git sees it as a modification.
        3. -
      3. Check for invisible whitespace changes: Open the diff in Source Control to see exactly what changed
        4. -
      4. If the diff shows no visible changes, it is likely a line ending or trailing whitespace issue
        5. -
      -

      Problem: Cannot stage or commit - "No changes to commit"

      -

      Symptoms: You made changes but Git does not see them.

      -

      Solution:

      -
        -
      1. Verify the file was saved: Ctrl+S
        2. -
      2. Check you are in the correct repository folder
        3. -
      3. Check if the file is in .gitignore: git status --ignored
        4. -
      4. If the file is new, it needs to be staged with git add [filename] before it appears
        5. -
      -

      Screen Readers - General

      -

      Problem: Screen reader does not read GitHub page content

      -

      Symptoms: Screen reader launches but GitHub content is silent or skips sections.

      -

      Solution:

      -
        -
      1. Verify you are in Browse Mode (document/virtual mode), not Focus Mode
        2. -
      2. Wait for the page to fully load - GitHub uses JavaScript rendering that may take a few seconds
        3. -
      3. Try refreshing: Ctrl+R or F5
        4. -
      4. Use heading navigation (H) to find the main content - skip past the navigation menus
        5. -
      5. Use landmark navigation (D) to jump to the main landmark
        6. -
      6. If a specific section is empty, it may be in a dynamically loaded area - press Tab to see if interactive elements appear
        7. -
      -

      Problem: Screen reader reads too much navigation before content

      -

      Symptoms: Every page starts with a long list of links and menus before reaching the actual content.

      -

      Solution:

      -
        -
      1. Press D (landmark navigation) to jump directly to the main content area
        2. -
      2. Or press 1 to jump to the first H1 heading (usually the page title)
        3. -
      3. GitHub pages have a "Skip to content" link - it is the first focusable element. Press Enter on it.
        4. -
      -

      Problem: Screen reader announces "[number] results" but does not read them

      -

      Symptoms: After filtering issues or searching, the screen reader says how many results but does not navigate to them.

      -

      Solution:

      -
        -
      1. The search results are usually in a list below the search bar
        2. -
      2. Press L to jump to the next list, then use arrow keys to navigate items
        3. -
      3. Or use K to jump through links - each result is a link
        4. -
      4. On the Issues/PRs page, press J and Shift+J to navigate between items (GitHub shortcut)
        5. -
      -

      Problem: Dropdown menus or popups disappear before you can read them

      -

      Symptoms: A menu opens but closes immediately when you try to navigate it.

      -

      Solution:

      -
        -
      1. For dropdown menus: activate the button, then use Arrow Down to navigate options
        2. -
      2. For dialog popups: press Tab to move between elements inside the dialog
        3. -
      3. If the popup closes on focus loss, try Escape to close it, then Enter to reopen, and immediately arrow into it
        4. -
      4. Some GitHub menus require Focus Mode - press NVDA+Space (NVDA) or Insert+Z (JAWS) to switch
        5. -
      -

      Problem: Interactive elements are announced as "clickable" without a specific role

      -

      Symptoms: Screen reader says "clickable" instead of "button," "link," or "checkbox."

      -

      Solution:

      -
        -
      1. Try pressing Enter or Space to activate the element
        2. -
      2. This indicates a potential accessibility issue with the page - the element is missing proper ARIA roles
        3. -
      3. If this happens consistently on a specific page, file an accessibility issue on the project with the page URL and element description
        4. -
      -

      NVDA-Specific Issues

      -

      Problem: NVDA not reading GitHub page at all

      -

      Symptoms: NVDA is running but produces no speech on GitHub pages.

      -

      Solution:

      -
        -
      1. Press NVDA+Space to verify you are in Browse Mode
        2. -
      2. Press NVDA+F7 to open the Elements List - if it shows headings and links, NVDA can see the page
        3. -
      3. Press Ctrl+Home to go to the top of the page, then Down Arrow through content
        4. -
      4. Try a different browser (Firefox often works best with NVDA)
        5. -
      5. Check NVDA preferences → Browse Mode → verify "Use browse mode on page load" is checked
        6. -
      -

      Problem: NVDA reads every character when typing in a form field

      -

      Symptoms: When typing in a GitHub comment box, NVDA reads each character but you cannot review what you wrote.

      -

      Solution:

      -
        -
      1. You are in Focus Mode (correct for typing). To review your text without leaving, press NVDA+Up Arrow to read the current line
        2. -
      2. Press NVDA+Space to switch to Browse Mode temporarily to review, then NVDA+Space again to return to Focus Mode for typing
        3. -
      3. In VS Code, use Alt+F2 (Accessible View) to review Copilot responses or other content
        4. -
      -

      Problem: NVDA add-ons conflict with VS Code

      -

      Symptoms: VS Code behaves strangely with certain NVDA add-ons enabled.

      -

      Solution:

      -
        -
      1. Temporarily disable add-ons: NVDA Menu → Tools → Manage Add-ons → disable suspected add-ons → restart NVDA
        2. -
      2. Common culprits: BrowserNav, Enhanced Touch Gestures, or older add-ons not updated for the current NVDA version
        3. -
      3. Update all add-ons to the latest versions compatible with NVDA 2025.3.3
        4. -
      -

      JAWS-Specific Issues

      -

      Problem: JAWS not announcing form fields correctly

      -

      Symptoms: JAWS skips form inputs, does not say "required," or reads field labels incorrectly.

      -

      Solution:

      -
        -
      1. Toggle Forms Mode: Insert+Z
        2. -
      2. List all form controls on the page: Insert+F6
        3. -
      3. Navigate form fields with F (next form field) or Tab
        4. -
      4. If labels are not announced, the HTML may be missing proper <label> elements - this is a page accessibility issue
        5. -
      5. Check JAWS version: ensure you are running JAWS 2026 or later for best GitHub compatibility
        6. -
      -

      Problem: JAWS virtual cursor conflicts with GitHub keyboard shortcuts

      -

      Symptoms: Pressing G in JAWS reads it as a virtual cursor command instead of triggering GitHub's keyboard shortcuts.

      -

      Solution:

      -
        -
      1. Toggle virtual cursor off: Insert+Z (enters Forms Mode / Application mode)
        2. -
      2. With virtual cursor off, G then I will trigger GitHub's "Go to Issues" shortcut
        3. -
      3. Toggle back to virtual cursor when done
        4. -
      -

      Problem: JAWS announces too much on GitHub pages

      -

      Symptoms: JAWS reads every ARIA attribute, region name, and role, making navigation slow.

      -

      Solution:

      -
        -
      1. Adjust verbosity: Insert+V → cycle through verbosity levels
        2. -
      2. Or go to JAWS Settings Center → Web/HTML/PDF → adjust "Navigation" and "Reading" verbosity
        3. -
      3. Use Skim Reading: Insert+Shift+Down Arrow to get a summary of the page
        4. -
      -

      VoiceOver-Specific Issues

      -

      Problem: VoiceOver on macOS not reading GitHub elements

      -

      Symptoms: VoiceOver skips buttons, links, or form fields on GitHub.

      -

      Solution:

      -
        -
      1. Open Rotor: VO+U (VO key is usually Caps Lock or Control+Option)
        2. -
      2. Use Left/Right arrows to switch rotor categories (Headings, Links, Form Controls)
        3. -
      3. Use Up/Down arrows to navigate within a category
        4. -
      4. If the rotor shows fewer elements than expected, the page may need to finish loading - wait and try again
        5. -
      5. Test in Safari first - it has the best VoiceOver compatibility among browsers
        6. -
      -

      Problem: VoiceOver Quick Nav conflicts with GitHub shortcuts

      -

      Symptoms: Single-letter navigation (H, B, K) is consumed by VoiceOver Quick Nav instead of GitHub.

      -

      Solution:

      -
        -
      1. Quick Nav on (default for web): Single letters are VoiceOver navigation commands (H for headings, etc.) - this is usually what you want for web browsing
        2. -
      2. Quick Nav off: Toggle with Left Arrow + Right Arrow simultaneously. With Quick Nav off, single letters type into the page - needed for some GitHub shortcuts
        3. -
      3. For GitHub shortcuts like G then I: turn Quick Nav off first
        4. -
      -

      Problem: VoiceOver cursor gets trapped in the VS Code editor

      -

      Symptoms: VoiceOver cannot leave the editor area to reach the sidebar or other panels.

      -

      Solution:

      -
        -
      1. Press VO+Shift+F5 to exit the current interaction context
        2. -
      2. Use VO+F6 to cycle between VS Code panels (sidebar, editor, terminal, etc.)
        3. -
      3. Use VS Code keyboard shortcuts directly: Ctrl+Shift+E (Explorer), Ctrl+Shift+G (Source Control), etc.
        4. -
      -

      GitHub Copilot

      -

      Problem: Copilot Chat panel will not open

      -

      Symptoms: Ctrl+Shift+I does nothing, or the Copilot Chat icon is grayed out.

      -

      Solution:

      -
        -
      1. Verify extension installed: Ctrl+Shift+X → search "GitHub Copilot Chat" → should show installed
        2. -
      2. If not installed, install both "GitHub Copilot" and "GitHub Copilot Chat"
        3. -
      3. If installed but grayed out: Ctrl+Shift+P → "Developer: Reload Window"
        4. -
      4. Verify you are signed in to GitHub: look for the GitHub icon in the status bar (bottom-left). Click to sign in if needed.
        5. -
      5. Check subscription: Copilot requires a paid plan, organization access, or the free tier. See https://github.com/features/copilot
        6. -
      -

      Problem: "You don't have access to Copilot"

      -

      Symptoms: Chat says you do not have Copilot access, even though the extension is installed.

      -

      Solution:

      -
        -
      1. Check your subscription at https://github.com/settings/copilot
        2. -
      2. GitHub Copilot offers a free tier with limited usage - verify you have not exceeded limits
        3. -
      3. For full access: Copilot Individual (~$10/month), Copilot Business (via organization), or Copilot Enterprise
        4. -
      4. Students/educators: Free access at https://education.github.com/
        5. -
      5. If your organization provides Copilot, ask your admin to enable it for your account
        6. -
      -

      Problem: Copilot inline suggestions not appearing

      -

      Symptoms: Copilot is installed and signed in, but no code suggestions appear while typing.

      -

      Solution:

      -
        -
      1. Verify Copilot is enabled for the current file type: check the Copilot icon in the status bar - it should show a checkmark
        2. -
      2. Click the Copilot icon to see if suggestions are enabled or disabled for this language
        3. -
      3. Check Settings: Ctrl+, → search github.copilot.enable → verify your language is not disabled
        4. -
      4. Open a new file and type a comment like // function to add two numbers - suggestions should appear below
        5. -
      5. Copilot needs an active internet connection
        6. -
      -

      Problem: Copilot suggestions are wrong or unhelpful

      -

      Symptoms: Copilot generates irrelevant or incorrect code/text.

      -

      Solution:

      -
        -
      1. This is normal - Copilot is a suggestion tool, not a decision-maker. Always review its output.
        2. -
      2. Press Alt+] or Alt+[ to cycle through alternative suggestions
        3. -
      3. Provide more context: add comments explaining what you want, open related files, or use Copilot Chat for more detailed instructions
        4. -
      4. Reject suggestions with Escape
        5. -
      -

      Copilot Chat

      -

      Problem: Copilot Chat freezes or stops responding

      -

      Symptoms: Chat input becomes unresponsive, or it shows a loading spinner indefinitely.

      -

      Solution:

      -
        -
      1. Wait 10-15 seconds - the API may be processing a complex request
        2. -
      2. Close and reopen Chat: click the X on the Chat panel → reopen with Ctrl+Shift+I
        3. -
      3. Check your internet connection
        4. -
      4. Check for errors: View → Output → select "GitHub Copilot" from the dropdown → look for error messages
        5. -
      5. If the problem persists, restart VS Code: save all work → close completely → reopen
        6. -
      -

      Problem: Chat responses are cut off or incomplete

      -

      Symptoms: Copilot starts answering but stops mid-sentence.

      -

      Solution:

      -
        -
      1. Type "continue" in the chat to ask Copilot to continue its response
        2. -
      2. If the response is consistently too long, break your question into smaller parts
        3. -
      3. Try a different model (click the model selector in Chat) - some models handle longer outputs better
        4. -
      -

      Problem: Chat does not know about my files or project

      -

      Symptoms: Copilot Chat gives generic answers that do not reference your repository.

      -

      Solution:

      -
        -
      1. Use @workspace before your question: @workspace how is authentication handled?
        2. -
      2. Open relevant files in the editor before asking - Copilot uses open files as context
        3. -
      3. Select specific code, then ask about it - Copilot uses the selection as context
        4. -
      4. Make sure you opened the correct folder in VS Code (not a parent folder)
        5. -
      -

      Problem: Chat response is hard to read with screen reader

      -

      Symptoms: Copilot Chat outputs formatted content that the screen reader does not navigate well.

      -

      Solution:

      -
        -
      1. Press Alt+F2 (Accessible View) - this renders the response as plain, navigable text
        2. -
      2. In the Accessible View, use standard screen reader commands (arrows, H for headings) to read the response
        3. -
      3. This is the recommended workflow for all screen reader users using Copilot Chat
        4. -
      -

      Accessibility Agents

      -

      Problem: Cannot find an agent (e.g., @template-builder)

      -

      Symptoms: Typing @template-builder in Copilot Chat does not autocomplete or does not trigger the agent.

      -

      Solution:

      -
        -
      1. Verify the .agent.md file exists: check .github/agents/template-builder.agent.md in your repository
        2. -
      2. Verify you have GitHub Copilot with agent support (requires a qualifying plan)
        3. -
      3. Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"
        4. -
      4. Open Copilot Chat: Ctrl+Shift+I → type @ → scroll through available agents
        5. -
      5. If the file exists but the agent does not appear:
          -
        • Verify the file is on your current branch
          • -
        • Wait 2-3 minutes for the agent index to refresh
          • -
        • Check that the YAML frontmatter in the .agent.md file is valid
          • -
        -
        6. -
      -

      Problem: Agent gives generic advice instead of using its persona

      -

      Symptoms: You ask @template-builder a question but it responds like a general-purpose assistant.

      -

      Solution:

      -
        -
      1. Close and reopen Copilot Chat: Ctrl+Shift+I
        2. -
      2. Verify you typed the agent name exactly: @template-builder (with the hyphen)
        3. -
      3. Type / to see available slash commands for that agent
        4. -
      4. Check the .agent.md file: the YAML frontmatter must include the agent's name and description
        5. -
      5. Try a simpler query to test if the agent responds correctly
        6. -
      -

      Problem: Agent cannot access repositories or data

      -

      Symptoms: Agent says it cannot find your repositories or data.

      -

      Solution:

      -
        -
      1. Verify you are signed in to GitHub in VS Code
        2. -
      2. Check .github/agents/preferences.md - is it configured with your repositories?
        3. -
      3. If preferences.md does not exist, copy from preferences.example.md and customize it
        4. -
      4. The agent needs read access to the repositories listed in preferences
        5. -
      -

      Problem: Slash commands do not appear

      -

      Symptoms: Typing / in Chat does not show the expected custom commands.

      -

      Solution:

      -
        -
      1. Custom slash commands come from .github/prompts/ in your repository
        2. -
      2. Verify the prompt files exist and are on your current branch
        3. -
      3. Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"
        4. -
      4. Type / in Chat and wait - the list may take a moment to populate
        5. -
      -

      Exercises and the Learning Room

      -

      Problem: Exercise tells me to look for a file but I cannot find it

      -

      Symptoms: An exercise says "open the template file" but the file is not in the expected location.

      -

      Solution:

      -
        -
      1. Check the exercise prerequisites - some files are created in earlier exercises
        2. -
      2. For templates: check .github/ISSUE_TEMPLATE/ folder
        3. -
      3. For agents: check .github/agents/ folder
        4. -
      4. List all files: git ls-files or in VS Code use Ctrl+P and type part of the filename
        5. -
      5. You may be on the wrong branch: git checkout main
        6. -
      6. The Learning Room files are in learning-room/docs/ (not in the root docs/ folder)
        7. -
      -

      Problem: Cannot understand what the exercise is asking

      -

      Symptoms: Exercise steps are confusing or the goal is unclear.

      -

      Solution:

      -
        -
      1. Read the prerequisites section at the start of each exercise
        2. -
      2. Each exercise follows a pattern: Try It → You're done when → What success feels like
        3. -
      3. Look for the "What you should see" checkpoint after each step
        4. -
      4. If your results do not match, re-read the step - the issue is usually a small detail
        5. -
      5. Check if there is an "If you're stuck" section within the exercise
        6. -
      6. Ask for help: open an issue describing the step you are on and what you see
        7. -
      -

      Problem: Bot does not respond to my PR in the Learning Room

      -

      Symptoms: You opened a PR but the automated bot did not post a review comment.

      -

      Solution:

      -
        -
      1. Wait 30-60 seconds - the bot runs via GitHub Actions and may take a moment
        2. -
      2. Check the Actions tab on the repository - is there a workflow run for your PR?
        3. -
      3. If the workflow failed, click it to see the error
        4. -
      4. Verify your PR targets the correct branch (usually main)
        5. -
      5. If the bot still does not respond, ask the facilitator - the automation may need to be configured
        6. -
      -

      Problem: Learning Room challenges are too easy or too hard

      -

      Symptoms: Individual challenges do not match your skill level.

      -

      Solution:

      -
        -
      1. Challenges are progressive - start with #1 and work up
        2. -
      2. Too easy: Skip ahead to the group challenges in learning-room/docs/GROUP_CHALLENGES.md
        3. -
      3. Too hard: Go back to the relevant chapter and review the concepts
        4. -
      4. The 12 individual challenges span four skill levels - find the range that stretches you without frustrating you
        5. -
      -

      HTML Build System

      -

      Problem: npm run build:html fails

      -

      Symptoms: Running the build command produces errors or no output.

      -

      Solution:

      -
        -
      1. Verify Node.js is installed: node --version (must be v14+)
        2. -
      2. Install dependencies first: npm install
        3. -
      3. Check the error message:
          -
        • marked is not defined → run npm install to install dependencies
          • -
        • ENOENT: no such file or directory → verify you are in the repository root
          • -
        • SyntaxError → a markdown file may have unusual characters. Check the error output for the filename.
          • -
        -
        4. -
      4. Try removing node_modules and reinstalling: delete the node_modules folder → npm install → npm run build:html
        5. -
      -

      Problem: HTML build produces files but they look wrong

      -

      Symptoms: HTML files are generated but formatting is broken, styles are missing, or navigation is wrong.

      -

      Solution:

      -
        -
      1. Verify github-markdown-css is installed: check node_modules/github-markdown-css/
        2. -
      2. Open an HTML file in your browser - if styles are missing, the CSS link may be broken
        3. -
      3. Check scripts/build-html.js for any custom configuration that may have been changed
        4. -
      4. Try a clean rebuild: delete the html/ folder contents → npm run build:html
        5. -
      -

      Problem: HTML files are outdated after editing markdown

      -

      Symptoms: You edited a .md file but the corresponding .html file still shows old content.

      -

      Solution:

      -
        -
      1. Rebuild: npm run build:html
        2. -
      2. The HTML build is manual - it does not auto-update when you edit markdown
        3. -
      3. After rebuilding, commit both the .md and html/ changes together
        4. -
      4. For live preview during editing, use npm run watch if available, or use VS Code's built-in Markdown preview (Ctrl+Shift+V)
        5. -
      -

      GitHub Pages and Online Access

      -

      Problem: GitHub Pages site is not updating

      -

      Symptoms: You pushed changes but the live site still shows old content.

      -

      Solution:

      -
        -
      1. GitHub Pages can take 2-10 minutes to rebuild after a push
        2. -
      2. Check build status: repository Settings → Pages → look for build status
        3. -
      3. Hard refresh in your browser: Ctrl+Shift+R
        4. -
      4. Check that GitHub Pages is configured to serve from the correct branch and folder
        5. -
      -

      Problem: Cannot access workshop materials

      -

      Symptoms: You want to read the materials but cannot find where they are hosted or how to download them.

      -

      Solution: See Appendix Y (Accessing Workshop Materials) for complete instructions covering:

      -
        -
      • Reading on GitHub Pages (if hosted)
        • -
      • Reading directly on GitHub.com
        • -
      • Cloning the repository with Git
        • -
      • Downloading as a ZIP file
        • -
      • Downloading individual files
        • -
      -

      Performance and Network

      -

      Problem: GitHub is slow or unresponsive

      -

      Symptoms: Pages take a long time to load, or actions time out.

      -

      Solution:

      -
        -
      1. Check GitHub's status page: https://www.githubstatus.com/
        2. -
      2. Try a different browser
        3. -
      3. Check your internet connection by visiting other sites
        4. -
      4. If behind a corporate network, some GitHub features may be blocked - check with your IT department
        5. -
      5. Disable browser extensions that may interfere (ad blockers, privacy tools)
        6. -
      -

      Problem: VS Code is slow or laggy

      -

      Symptoms: VS Code takes a long time to open files, respond to keyboard input, or load extensions.

      -

      Solution:

      -
        -
      1. Close unused editor tabs and panels
        2. -
      2. Disable extensions you are not using: Ctrl+Shift+X → disable non-essential extensions
        3. -
      3. Check for large files: VS Code may struggle with very large files or repositories
        4. -
      4. Increase memory: VS Code Settings → search files.maxMemoryForLargeFilesMB
        5. -
      5. Restart VS Code
        6. -
      -

      Problem: Operations fail behind a corporate proxy or firewall

      -

      Symptoms: git clone, npm install, or Copilot fail with network errors.

      -

      Solution:

      -
        -
      1. Configure Git proxy: git config --global http.proxy http://proxy:port
        2. -
      2. Configure npm proxy: npm config set proxy http://proxy:port
        3. -
      3. If SSH is blocked, use HTTPS for Git operations: git remote set-url origin https://github.com/...
        4. -
      4. Some firewalls block VS Code's telemetry or extension marketplace - ask IT to whitelist *.visualstudio.com, *.github.com, and *.githubusercontent.com
        5. -
      -

      Getting More Help

      -

      If your issue is not listed here:

      -
        -
      1. FAQ - Answers to common questions about the workshop
        2. -
      2. Quick Reference - Condensed keyboard shortcuts and commands
        3. -
      3. Glossary - Term definitions
        4. -
      4. Screen Reader Cheat Sheet - NVDA, JAWS, VoiceOver commands
        5. -
      5. Resources - External documentation and links
        6. -
      6. Open an issue on this repository with:
          -
        • What you tried
          • -
        • What happened (exact error messages)
          • -
        • What you expected
          • -
        • Your operating system, browser, screen reader, and versions
          • -
        • The chapter or exercise you were working on
          • -
        -
        7. -
      -

      Last updated: February 2026 | Maintained by GitHub Learning Community

      - -
      - - - \ No newline at end of file diff --git a/html/admin/ACCESSIBILITY_TESTING.html b/html/admin/ACCESSIBILITY_TESTING.html index 211ff75..d94b266 100644 --- a/html/admin/ACCESSIBILITY_TESTING.html +++ b/html/admin/ACCESSIBILITY_TESTING.html @@ -65,34 +65,34 @@

      Quick Checklist for Templates

      Use before deploying any new issue template or form.

      Form Fields & Labels

        -
      • Every form field has a visible label
        • -
      • Label text is clear and describes what's needed (not "Please enter")
        • -
      • Required fields are marked and announced as required
        • -
      • Help text is associated with each field (not just placeholder text)
        • -
      • No fields rely on color alone to indicate required/error status
        • +
      • Every form field has a visible label
        • +
      • Label text is clear and describes what's needed (not "Please enter")
        • +
      • Required fields are marked and announced as required
        • +
      • Help text is associated with each field (not just placeholder text)
        • +
      • No fields rely on color alone to indicate required/error status

      Form Structure

        -
      • Form inputs are in logical order (top to bottom)
        • -
      • Dropdown options are readable and include blank option or instruction
        • -
      • Checkboxes and radio buttons are grouped and labeled
        • -
      • No more than 6-8 required fields (reduces cognitive load)
        • -
      • Preview or review step before submission (allows verification)
        • +
      • Form inputs are in logical order (top to bottom)
        • +
      • Dropdown options are readable and include blank option or instruction
        • +
      • Checkboxes and radio buttons are grouped and labeled
        • +
      • No more than 6-8 required fields (reduces cognitive load)
        • +
      • Preview or review step before submission (allows verification)

      Instructions & Guidance

        -
      • Markdown section explains what's needed and why
        • -
      • Instructions use simple language (8th grade reading level)
        • -
      • Headings are in order (H2, H3, H4 - not H2, H4)
        • -
      • Links have descriptive text (not "click here")
        • -
      • Code examples are formatted clearly (not in plain text)
        • +
      • Markdown section explains what's needed and why
        • +
      • Instructions use simple language (8th grade reading level)
        • +
      • Headings are in order (H2, H3, H4 - not H2, H4)
        • +
      • Links have descriptive text (not "click here")
        • +
      • Code examples are formatted clearly (not in plain text)

      YAML & Technical

        -
      • YAML passes syntax validation (https://www.yamllint.com/)
        • -
      • No trailing spaces or mixed indentation
        • -
      • All required fields present: name:, description:, body:
        • -
      • Field IDs are unique and lowercase with hyphens (e.g., browser_type)
        • +
      • YAML passes syntax validation (https://www.yamllint.com/)
        • +
      • No trailing spaces or mixed indentation
        • +
      • All required fields present: name:, description:, body:
        • +
      • Field IDs are unique and lowercase with hyphens (e.g., browser_type)

      Screen Reader Testing Workflow

      Before Testing

      @@ -115,11 +115,11 @@

      NVDA Testing (Windows)

      9. Verify instructions between fields are heard

      What to listen for:

        -
      • Every field label is announced
        • -
      • "Required" is announced for required fields
        • -
      • No fields are skipped
        • -
      • Field types are clear (edit text, dropdown, checkbox, etc.)
        • -
      • Help text is read before or near the field
        • +
      • Every field label is announced
        • +
      • "Required" is announced for required fields
        • +
      • No fields are skipped
        • +
      • Field types are clear (edit text, dropdown, checkbox, etc.)
        • +
      • Help text is read before or near the field

      JAWS Testing (Windows)

      1. Press Spacebar to enter browse mode
@@ -135,11 +135,11 @@ 
      JAWS Testing (Windows)
      
 6. Press Insert+Down to read entire form (simulates form-scanning)

      What to listen for:

        -
      • Form start is announced
        • -
      • All fields are listed in Forms List
        • -
      • Required fields say "required"
        • -
      • Field order matches logical reading order
        • -
      • No unlabeled fields
        • +
      • Form start is announced
        • +
      • All fields are listed in Forms List
        • +
      • Required fields say "required"
        • +
      • Field order matches logical reading order
        • +
      • No unlabeled fields

      VoiceOver Testing (macOS)

      1. Press VO+U to open Web Rotor
@@ -155,119 +155,119 @@ 
      VoiceOver Testing (macOS)
      
    "[Label], [field type] [required if applicable]"

      What to listen for:

        -
      • Rotor shows all form controls
        • -
      • Heading levels are correct (no 1 → 3 jumps)
        • -
      • Field labels are adjacent to fields
        • -
      • Instructions are readable
        • +
      • Rotor shows all form controls
        • +
      • Heading levels are correct (no 1 → 3 jumps)
        • +
      • Field labels are adjacent to fields
        • +
      • Instructions are readable

      Accessibility Testing by Component

      Checkboxes & Radio Buttons

        -
      • Grouped label describes the entire group
        • -
      • Individual labels describe each option
        • -
      • Screen reader announces number of options
        • -
      • Example: Screen reader says: "Browser, radio button group, 3 items. Chrome, radio button, not selected"
        • +
      • Grouped label describes the entire group
        • +
      • Individual labels describe each option
        • +
      • Screen reader announces number of options
        • +
      • Example: Screen reader says: "Browser, radio button group, 3 items. Chrome, radio button, not selected"

      Test: Tab to group, use arrow keys to select. Screen reader should guide you clearly.

        -
      • Visible label above or adjacent to dropdown
        • -
      • Dropdown shows currently selected value
        • -
      • Opening dropdown announces all options (or "expandable menu")
        • -
      • Options include instruction or blank option if optional
        • -
      • Focus style is visible (not invisible on dark backgrounds)
        • +
      • Visible label above or adjacent to dropdown
        • +
      • Dropdown shows currently selected value
        • +
      • Opening dropdown announces all options (or "expandable menu")
        • +
      • Options include instruction or blank option if optional
        • +
      • Focus style is visible (not invisible on dark backgrounds)

      Test: Tab to dropdown, press Down/Space to open, arrow through options.

        -
      • Link text describes where it goes (not "click here", "link", "read more")
        • -
      • Button text describes what happens (not "submit", "go", "continue")
        • -
      • Focuses visible with keyboard (Tab key shows clear highlight)
        • -
      • No links that are only images (images need alt text)
        • +
      • Link text describes where it goes (not "click here", "link", "read more")
        • +
      • Button text describes what happens (not "submit", "go", "continue")
        • +
      • Focuses visible with keyboard (Tab key shows clear highlight)
        • +
      • No links that are only images (images need alt text)

      Test: Press Tab to navigate, read labels aloud.

      Text Fields (Input, Textarea)

        -
      • Label directly associated with field (via label tag or aria-label)
        • -
      • Placeholder text is NOT a substitute for label
        • -
      • Example: Bad: Empty field with gray "Enter email" (disappears when you type)
        • -
      • Example: Good: Visible label "Email address:" + field
        • +
      • Label directly associated with field (via label tag or aria-label)
        • +
      • Placeholder text is NOT a substitute for label
        • +
      • Example: Bad: Empty field with gray "Enter email" (disappears when you type)
        • +
      • Example: Good: Visible label "Email address:" + field

      Test: Tab to field, screen reader announces label, then focus moves into field.

      Instructions & Help Text

        -
      • Help text appears visually near the field
        • -
      • Help text is announced by screen reader (not hidden)
        • -
      • Instructions use simple language
        • -
      • No abbreviations without explanation
        • +
      • Help text appears visually near the field
        • +
      • Help text is announced by screen reader (not hidden)
        • +
      • Instructions use simple language
        • +
      • No abbreviations without explanation

      Test: Tab to field, screen reader should announce label, field type, help text, and required status.

      Color & Contrast Testing

        -
      • Text contrast is 4.5:1 or higher (WCAG AA for normal text)
        • -
      • Color is not the only way to show information
          +
        • Text contrast is 4.5:1 or higher (WCAG AA for normal text)
          • +
        • Color is not the only way to show information
          • Example: Bad: "Red fields are errors" (only color indicates error)
          • Example: Good: "Error" label + red color + error icon
          • -
        • Required fields marked with or "required" text (not just color)
          • -
        • Disabled fields are visually distinct
          • +
        • Required fields marked with or "required" text (not just color)
          • +
        • Disabled fields are visually distinct

        Test: Use WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/

        Keyboard Navigation Testing

        Test WITHOUT using the mouse.

          -
        • Tab key navigates to all interactive elements
          • -
        • Tab order follows logical reading order (left-to-right, top-to-bottom)
          • -
        • Shift+Tab goes backwards
          • -
        • Focus indicator is visible (not hidden or very faint)
          • -
        • Can activate buttons with Enter or Space
          • -
        • Can select radio buttons and checkboxes with arrow keys
          • -
        • Can open dropdowns with Space or Down arrow
          • -
        • Can submit form with Enter from submit button
          • +
        • Tab key navigates to all interactive elements
          • +
        • Tab order follows logical reading order (left-to-right, top-to-bottom)
          • +
        • Shift+Tab goes backwards
          • +
        • Focus indicator is visible (not hidden or very faint)
          • +
        • Can activate buttons with Enter or Space
          • +
        • Can select radio buttons and checkboxes with arrow keys
          • +
        • Can open dropdowns with Space or Down arrow
          • +
        • Can submit form with Enter from submit button

        Test: Close trackpad, use Tab/Shift+Tab/Enter/Space only.

        Mobile & Responsive Testing

          -
        • Form is readable on small screens (mobile, tablet)
          • -
        • Form is usable with touch (buttons large enough: 44x44px minimum)
          • -
        • Form labels don't disappear on narrow screens
          • -
        • Touch targets don't overlap
          • -
        • No horizontal scrolling required to use form
          • +
        • Form is readable on small screens (mobile, tablet)
          • +
        • Form is usable with touch (buttons large enough: 44x44px minimum)
          • +
        • Form labels don't disappear on narrow screens
          • +
        • Touch targets don't overlap
          • +
        • No horizontal scrolling required to use form

        Test: Resize browser to mobile width (375px), or use phone/tablet to fill form.

        Multilingual & Plain Language Testing

          -
        • Instructions use simple, clear language (avoid jargon)
          • -
        • No unexplained abbreviations (spell out first use, then abbreviate)
          • -
        • Text can be enlarged to 200% without breaking layout
          • -
        • If translated, consider cultural appropriateness of images/phrasings
          • +
        • Instructions use simple, clear language (avoid jargon)
          • +
        • No unexplained abbreviations (spell out first use, then abbreviate)
          • +
        • Text can be enlarged to 200% without breaking layout
          • +
        • If translated, consider cultural appropriateness of images/phrasings

        Test: Select browser zoom 200% (Ctrl+Plus / Cmd+Plus), or use browser reader mode.

        Testing Checklist Summary

        Before Deploying (Must-Have)

          -
        • All form fields have labels
          • -
        • Required fields marked and announced
          • -
        • Tab order is logical
          • -
        • Focus styles are visible
          • -
        • Color contrast is adequate (4.5:1 minimum)
          • -
        • Heading hierarchy is correct
          • -
        • YAML syntax is valid
          • +
        • All form fields have labels
          • +
        • Required fields marked and announced
          • +
        • Tab order is logical
          • +
        • Focus styles are visible
          • +
        • Color contrast is adequate (4.5:1 minimum)
          • +
        • Heading hierarchy is correct
          • +
        • YAML syntax is valid

        Before Workshop/Training (Should-Have)

          -
        • Tested with at least 1 screen reader (NVDA, JAWS, or VoiceOver)
          • -
        • Keyboard-only workthrough (no mouse)
          • -
        • Mobile/responsive check
          • -
        • Plain language review
          • +
        • Tested with at least 1 screen reader (NVDA, JAWS, or VoiceOver)
          • +
        • Keyboard-only workthrough (no mouse)
          • +
        • Mobile/responsive check
          • +
        • Plain language review

        Best Practice (Nice-to-Have)

          -
        • Tested with all 3 screen readers
          • -
        • Tested with multiple browsers (Chrome, Firefox, Safari, Edge)
          • -
        • Tested with actual users with disabilities
          • -
        • Performance tested (forms load quickly)
          • +
        • Tested with all 3 screen readers
          • +
        • Tested with multiple browsers (Chrome, Firefox, Safari, Edge)
          • +
        • Tested with actual users with disabilities
          • +
        • Performance tested (forms load quickly)

        Common Accessibility Failures & How to Test Them

        @@ -340,7 +340,7 @@

        After Testing: Recording Issues

        Title: [Accessibility] Form label missing on email field
 
 Description:
-When tabbing to the email input on the issue template, the screen reader 
+When tabbing to the email input on the issue template, the screen reader
 announces "edit text, required" but does not announce what the field is for.
 
 Steps to reproduce:
@@ -361,27 +361,27 @@ 
        Testing the Built HTML Output
        
 
        This repository includes a build system that converts all Markdown files to HTML (see BUILD.md). If participants will use the HTML versions, test them separately:
        
 
        Heading Hierarchy
        
 
          
-
        •   Each HTML page has exactly one <h1> element
          • 
-
        •   Heading levels don't skip (no <h1> → <h3> jumps)
          • 
-
        •   Navigation footers don't break the heading outline
          • 
+
        •  Each HTML page has exactly one <h1> element
          • 
+
        •  Heading levels don't skip (no <h1> → <h3> jumps)
          • 
+
        •  Navigation footers don't break the heading outline
          • 
 
        
 
 
          
-
        •   Internal links resolve correctly (.md links are converted to .html)
          • 
-
        •   Anchor links (#section-name) scroll to the correct position
          • 
-
        •   External links open and are not broken
          • 
+
        •  Internal links resolve correctly (.md links are converted to .html)
          • 
+
        •  Anchor links (#section-name) scroll to the correct position
          • 
+
        •  External links open and are not broken
          • 
 
        
 
        Landmark Structure
        
 
          
-
        •   The <main> element wraps the primary content
          • 
-
        •   Navigation elements are properly structured
          • 
-
        •   Screen reader can identify page regions using landmarks (D key in NVDA/JAWS)
          • 
+
        •  The <main> element wraps the primary content
          • 
+
        •  Navigation elements are properly structured
          • 
+
        •  Screen reader can identify page regions using landmarks (D key in NVDA/JAWS)
          • 
 
        
 
        Validation
        
 
          
-
        •   Run pages through the W3C HTML Validator - check for errors
          • 
-
        •   Run pages through WAVE - check for accessibility errors
          • 
-
        •   Verify syntax-highlighted code blocks are readable (not color-only)
          • 
+
        •  Run pages through the W3C HTML Validator - check for errors
          • 
+
        •  Run pages through WAVE - check for accessibility errors
          • 
+
        •  Verify syntax-highlighted code blocks are readable (not color-only)
          • 
 
        
 
        Quick test: Open html/index.html in a browser, enable your screen reader, and navigate using H (headings) and K (links). Every heading and link should be announced clearly.
        
 
        Questions or Feedback?
        
@@ -397,5 +397,6 @@ 
        Questions or Feedback?
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/admin/ANNOUNCEMENT.html b/html/admin/ANNOUNCEMENT.html
index 6ffef9a..5b29c20 100644
--- a/html/admin/ANNOUNCEMENT.html
+++ b/html/admin/ANNOUNCEMENT.html
@@ -79,11 +79,11 @@ 
        A Two-Day Workshop by Zoom
+
        @@ -104,6 +104,9 @@

        A Two-Day Workshop by 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.

        @@ -112,11 +115,11 @@

        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, your name will be in the commit history of a live, public open source project. Not a sandbox. Not a simulation. The real thing.

        +

        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. By the end of the workshop, your name is in its commit history.

        +

        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:

          @@ -331,6 +334,7 @@

          GitHub Account

          Our Pre-Workshop Setup Guide walks through every one of these steps with detailed screen reader instructions for NVDA, JAWS, and VoiceOver.

          Registration Closed

          Registration for GIT Going with GitHub is now closed. Thank you to all who registered!

          +

          If you want to be considered for the next cohort, complete the Student Opt-In page. The form is processed automatically and supports waitlist handling when needed.

          Already registered? Complete the Pre-Workshop Setup Guide before Day 1 to make sure you are ready.

          What Makes This Workshop Different

          Most GitHub tutorials tell you what buttons to click. This one starts from a different place entirely: what does your screen reader announce when the page loads?

          @@ -373,5 +377,6 @@

          Acknowledgments

          GIT Going with GitHub - A workshop by Community Access

          View on GitHub · community-access.org

          + - \ No newline at end of file + diff --git a/html/admin/COHORT_PROVISIONING.html b/html/admin/COHORT_PROVISIONING.html index 0dbbcdf..25bbffe 100644 --- a/html/admin/COHORT_PROVISIONING.html +++ b/html/admin/COHORT_PROVISIONING.html @@ -70,5 +70,6 @@

          Cohort Provisioning -- Deprecated

          GIT Going with GitHub - A workshop by Community Access

          View on GitHub · community-access.org

          + - \ No newline at end of file + diff --git a/html/admin/DAY1_AGENDA.html b/html/admin/DAY1_AGENDA.html index 9c658a8..4562a4e 100644 --- a/html/admin/DAY1_AGENDA.html +++ b/html/admin/DAY1_AGENDA.html @@ -62,8 +62,16 @@

          Day 1 Agenda

          Open Source Assistive Technology Workshop - GitHub Classroom Edition

          Day 1 Focus: The GitHub web interface -- navigating repositories, filing and responding to issues, understanding pull requests, and contributing through the browser using only your keyboard and screen reader.

          -

          How learning works today: Each participant has their own private repository, created automatically when you accept the Classroom assignment. Inside that repo, an automation system called Aria guides you through a series of challenges delivered as GitHub Issues. When you complete one challenge and close the issue, Aria unlocks the next. You work at your own pace through Challenges 1-9 during the structured blocks below, with facilitator guidance and peer collaboration throughout.

          +

          How learning works today: Each participant has their own private repository, created automatically when you accept the Classroom assignment. Inside that repo, an automation system called Aria guides you through a series of challenges delivered as GitHub Issues. The live session prioritizes the core path through repository navigation, issues, branches, commits, and a first pull request. The remaining challenges stay available for async completion during open lab time or after the event.

          +

          Coverage Promise

          +

          This agenda is a live facilitation plan, not a requirement that every chapter and challenge be completed in the room. The full curriculum contains more material than a shortened live day can responsibly cover.

          +
            +
          • Live core: Participants should leave able to navigate a repository, file and discuss issues, create a branch, edit a file, commit, and open a pull request.
            • +
          • Live support if time allows: Merge conflicts, review practice, labels, milestones, notifications, and culture exercises.
            • +
          • Async follow-up: Challenges 7-9 and the reference chapters remain available after the live session. Facilitators can use open lab time for catch-up instead of moving the whole room forward.
            • +
          • Remote-ready delivery: Remote participants should receive the same Classroom links, Slack channel, CART/ASL access where available, and written checkpoints. Every block should include a clear "you are done when" checkpoint so people can pause and resume later.
            • +

          Your Classroom Repository

          When you accept the Day 1 assignment link, GitHub creates a private copy of the template repository for you in the workshop classroom organization. You do not work directly in the template repository. Your private Learning Room repo comes pre-configured with:

            @@ -82,89 +90,102 @@

            Your Classroom Repository

            Why this matters: You are not reading about GitHub. You are doing GitHub, in your own repository, and an automated system is verifying your work and giving you feedback. The mechanics are identical to what happens when you contribute to any real open source project.

            At a Glance

            +

            The following table summarizes the Pacific-time live agenda and identifies which blocks are required live coverage versus stretch or async material.

        GitHub headquarters in San Francisco, with remote-ready materials for future cohorts
        Cost
        + - - + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + - - - - + + + + + + + + + + + + + + + +
        Time (Pacific) BlockTime (Eastern) TopicChallengesCoverage
        012:00 PMWelcome, setup verification, and accept Classroom assignment--9:00-9:30 AMEvent welcomeCheck-in, breakfast, access services, and orientationRequired live
        112:30 PMScreen reader orientation to GitHubChallenge 1: Find Your Way9:30-10:00 AMKeynoteMaking real change through real learningRequired live
        21:10 PMNavigating repositories, issues, and conversationsChallenges 2-310:00-10:15 AMOpening remarksEvent goals, agenda, and participation normsRequired live
        --2:00 PMBreak--10:15-10:45 AMBlock 0Learning Room setup and Classroom assignment acceptanceRequired live
        32:15 PMBranching, editing, and committingChallenges 4-510:45-11:20 AMBlock 1Screen reader orientation to GitHubRequired live: Challenge 1
        43:10 PMPull requests, review, and merge conflictsChallenges 6-711:20 AM-12:00 PMBlock 2Issues and conversationsRequired live: Challenges 2-3
        --4:00 PMDinner break--12:00-1:00 PMLunchFood, rest, informal supportRequired break
        55:00 PMCulture, triage, and merge dayChallenges 8-91:00-1:50 PMBlock 3Branching, editing, and committingRequired live: Challenges 4-5
        --6:00 PMBreak--1:50-2:45 PMBlock 4Pull requests and review basicsRequired live: Challenge 6; Challenge 7 if time allows
        66:15 PMCommunity: communication, labels, and notifications--2:45-3:00 PMBreakRest and facilitator triageRequired break
        --7:30 PMWrap-up and reflections--3:00-4:00 PMBlock 5Contribution lab and merge-conflict supportLive support: finish Challenges 4-7
        4:00-4:30 PMBlock 6Culture, triage, labels, and notificationsAsync or stretch: Challenges 8-9
        4:30-5:00 PMWrap-upReflection, next steps, remote catch-up pathRequired live
        -

        Total: ~7.5 hours of structured time (12:00 PM - 8:00 PM Eastern)

        +

        Total: 8 hours of event time (9:00 AM - 5:00 PM Pacific), with about 5 hours of hands-on GitHub instruction after keynote, opening remarks, lunch, and breaks.

        Pre-Day Checklist

        Before entering the room (or joining the call), participants should have completed everything in Pre-Workshop Setup. The facilitator will do a quick verification at the start.

        -

        Block 0 - Welcome and Orientation (12:00 PM, 30 min)

        +

        Block 0 - Learning Room Setup and Orientation (10:15 AM, 30 min)

        Date and Location

        -

        Day 1: May 21, 2026 | 12:00 PM - 8:00 PM Eastern -Day 2: May 22, 2026 | 12:00 PM - 8:00 PM Eastern

        +

        Day 1: May 21, 2026 | 9:00 AM - 5:00 PM Pacific +Day 2: May 22, 2026 | 9:00 AM - 5:00 PM Pacific

        Facilitators

        • Jeff Bishop -- lead facilitator, maintainer of Accessibility Agents
          • @@ -204,7 +225,7 @@

          Activities

          • Each participant: your name, your screen reader and OS, what brings you here
          -

          Block 1 - Screen Reader Orientation to GitHub (12:30 PM, 40 min)

          +

          Block 1 - Screen Reader Orientation to GitHub (10:45 AM, 35 min)

          Purpose

          Establish a shared navigation foundation. Every participant leaves this block able to confidently navigate a GitHub repository page using their screen reader.

          Key Concepts Covered

          @@ -283,7 +304,7 @@

          Part B - Start C

      Reference Document

      Screen Reader Cheat Sheet

      -

      Block 2 - Issues and Conversations (1:10 PM, 50 min)

      +

      Block 2 - Issues and Conversations (11:20 AM, 40 min)

      Purpose

      Participants can file, read, respond to, and navigate issues -- and understand how GitHub's conversation model works.

      Key Concepts Covered

      @@ -325,9 +346,9 @@

      Part B - Challenge 3:

      After submitting your evidence, close Challenge 3. Challenge 4 opens.

      Reference Document

      Working with Issues | Glossary

      -

      Break (2:00 PM, 15 min)

      +

      Lunch (12:00 PM, 60 min)

      Encourage participants to stand, stretch, and rest their ears. Screen reader listening is cognitively demanding work.

      -

      Block 3 - Branching, Editing, and Committing (2:15 PM, 55 min)

      +

      Block 3 - Branching, Editing, and Committing (1:00 PM, 50 min)

      Purpose

      Participants create a branch, edit a file on GitHub, and commit with a meaningful message -- the core Git workflow that every contribution uses.

      Key Concepts Covered

      @@ -398,7 +419,7 @@

      Part C - Catch-Up and Explorat

      If you are still working on a challenge, use this time to finish.

      Reference Document

      Working with Pull Requests

      -

      Block 4 - Pull Requests, Review, and Merge Conflicts (3:10 PM, 50 min)

      +

      Block 4 - Pull Requests, Review, and Merge Conflicts (1:50 PM, 55 min)

      Purpose

      Participants open their first pull request, experience automated feedback from Aria bot, and resolve a facilitator-triggered merge conflict.

      Key Concepts Covered

      @@ -448,7 +469,7 @@

      Part B - Challenge

      What conflict markers look like:

      <<<<<<< HEAD
 The version currently on the target branch
-=======
+=======
 Your version from your branch
 >>>>>>> learn/your-username

      How to resolve:

      @@ -465,7 +486,7 @@

      Part B - Challenge

      Autograded: The autograder checks that no conflict markers remain in your file and that the file has meaningful content.

      Submit your evidence and close Challenge 7. Challenge 8 appears.

      Part C - Navigating a PR with Your Screen Reader (10 min)

      -

      Before lunch, practice navigating the PR you just opened:

      +

      Before the afternoon break, practice navigating the PR you just opened:

      1. Conversation tab: Read the PR title, description, and Aria's comment
      2. Commits tab: How many commits? Navigate the list
        3. @@ -475,8 +496,9 @@

        Part C - Naviga

      Reference Document

      Working with Pull Requests | Merge Conflicts

      -

      Dinner Break (4:00 PM, 60 min)

      -

      Block 5 - Culture, Triage, and Merge Day (5:00 PM, 60 min)

      +

      Break (2:45 PM, 15 min)

      +

      Block 5 - Contribution Lab and Merge-Conflict Support (3:00 PM, 60 min)

      +

      Use this block as supported lab time first. If most participants have already opened a pull request, move into culture, triage, and merge-day practice. If not, keep facilitators focused on helping participants finish Challenges 4-7.

      Purpose

      Participants reflect on open source culture, practice issue triage, and get their Day 1 PR merged.

      Part A - Challenge 8: The Culture Layer (25 min)

      @@ -502,10 +524,10 @@

      Part B - Challenge 9: Merge Day (

      Challenge 9 is the Day 1 capstone: get your PR merged.

      Merge checklist:

        -
      • Your PR has no merge conflicts (if it does, resolve them first)
        • -
      • Your PR links to your issue with Closes #XX
        • -
      • Your commit message is meaningful
        • -
      • You have reviewed your own changes one last time
        • +
      • Your PR has no merge conflicts (if it does, resolve them first)
        • +
      • Your PR links to your issue with Closes #XX
        • +
      • Your commit message is meaningful
        • +
      • You have reviewed your own changes one last time

      Steps:

        @@ -516,7 +538,7 @@

        Part B - Challenge 9: Merge Day (
      1. Check that your linked issue was automatically closed

      -

      Magic Moment: Navigate to the Code tab. Your changes are on main. The issue you filed is closed. Your name is in the commit history. This is how every open source contribution works -- everywhere, on every project, forever.

      +

      Magic Moment: If your PR merged today, navigate to the Code tab. Your changes are on main. The issue you filed is closed. Your name is in the commit history. If your PR is still in progress, you have the same path in front of you: finish the review, merge when ready, and the result is real.

      Submit your evidence and close Challenge 9.

      Part C - Help a Classmate (10 min)

      @@ -527,9 +549,8 @@

      Part C - Help a Classmate (10 min)

      Answer a question about something you figured out

    If everyone is done, browse the bonus challenges (A through E) for extra practice.

    -

    Break (6:00 PM, 15 min)

    -

    Stand, stretch, and rest your ears. The final block is discussion-centered and lower intensity.

    -

    Block 6 - Community: Communication, Labels, and Notifications (6:15 PM, 75 min)

    +

    Block 6 - Community: Communication, Labels, and Notifications (4:00 PM, 30 min)

    +

    This block is stretch content for live delivery. If participants are still finishing pull requests, use this time as supported lab time and assign the culture, triage, labels, and notifications material as async follow-up.

    Purpose

    Participants understand the human side of open source: how to communicate well, how to stay organized, and how to manage their GitHub notification experience.

    Part A - Community Health Files (15 min)

    @@ -609,7 +630,7 @@

    Part D - Not
  • Mark it as Done
  • Change your repository Watch settings to "Participating and @mentions only"
    • -

    Wrap-Up (7:30 PM, 30 min)

    +

    Wrap-Up (4:30 PM, 30 min)

    What You Built Today (10 min)

    Today you navigated real GitHub repositories, filed real issues, opened real pull requests, reviewed real contributions, and merged real changes -- in your own repository with automated feedback. Those skills work on every GitHub repository in the world, not just this workshop.

    Challenge Progress Check (10 min)

    @@ -721,5 +742,6 @@

    The Emotional Arc

    GIT Going with GitHub - A workshop by Community Access

    View on GitHub · community-access.org

    + - \ No newline at end of file + diff --git a/html/admin/DAY2_AGENDA.html b/html/admin/DAY2_AGENDA.html index 1e57514..eeefe53 100644 --- a/html/admin/DAY2_AGENDA.html +++ b/html/admin/DAY2_AGENDA.html @@ -60,13 +60,21 @@

    Day 2 Agenda

    From Contributor to Product Maker - Igniting the Forge

    -

    Date: May 22, 2026 | 12:00 PM - 8:00 PM Eastern

    +

    Date: May 22, 2026 | 9:00 AM - 5:00 PM Pacific

    The premise of Day 2: Whether you built your GitHub skills yesterday in Day 1 or you are joining today with existing GitHub experience, the foundation is the same: you know how to navigate repositories, file issues, open pull requests, and review someone else's work. Those skills are yours now.

    Day 2 is about what you can build with those skills. You will deepen your contributions using VS Code and GitHub Copilot. You will use Accessibility Agents - a live, public accessibility project built by your facilitator - not as a shortcut around the skills you learned, but as a product you can understand, evaluate, critique, and improve because you now know exactly what it is doing and why.

    You will leave with your name in the commit history of a real open source project and a set of tools you can use on any GitHub repository you ever work on.

    Joining on Day 2 without attending Day 1? See the Day 2 Quick Start guide to verify your setup and self-assess your readiness.

    +

    Coverage Promise

    +

    Day 2 is designed as a live contribution day with a self-paced continuation path. The complete Day 2 curriculum contains more material than the live schedule can cover, especially because participants will move at different speeds through setup, Git, Copilot, and project work.

    +
      +
    • Live core: Participants should leave able to work locally in VS Code, use Git with a branch and pull request, use Copilot as a reviewed writing partner, inspect accessibility agents, and identify one concrete contribution path.
      • +
    • Live support if time allows: Custom issue templates, full agent creation, cross-fork upstream pull requests, GitHub Agentic Workflows, and Spec Kit planning.
      • +
    • Async follow-up: Challenges 14-16, full capstone work, and upstream PR polish can continue after the event through the same repositories and Slack channel.
      • +
    • Remote-ready delivery: Remote participants need the repository links, Slack channel, CART/ASL access where available, and written checkpoints before each lab. Facilitators should state when a block is demo-only, hands-on, or async-safe.
      • +

    Prerequisites for Day 2

    Day 2 requires the following skills and setup. If you attended Day 1, you have all of these. If you are joining fresh, verify each item before the session.

    @@ -114,72 +122,85 @@

    Prerequisites for Day 2

    At a Glance

    +

    The following table summarizes the Pacific-time live agenda and marks which material is core, stretch, or async-friendly.

    - + + - + - + + - - - + + + + - + - + + - - - + + + + - + - + + - + - + + - - - + + + + - - - + + + + - + - + + - + - + + - + - + +
    TimeTime (Pacific) Block ThemeCoverage
    9:00-9:309:00-9:30 AM Block 0 - Welcome and OrientationOnboard all participants, verify setup, set goalsOnboard participants, verify setup, set goalsRequired live
    9:30-10:30Block 1 - VS Code SetupScreen reader mode, Accessibility Agents as workspace, navigation9:30-10:30 AMBlock 1 - VS Code and Local Git SetupScreen reader mode, local clone, branch, commit, pushRequired live
    10:30-10:4510:30-10:45 AM Break-Rest and facilitator triageRequired break
    10:45-12:00Block 2 - Deep ContributionCopilot Chat, inline suggestions, richer PR work10:45 AM-12:00 PMBlock 2 - Deep Contribution with CopilotCopilot Chat, inline suggestions, contribution draftingRequired live
    12:00-13:0012:00-1:00 PM Lunch-Food, rest, informal supportRequired break
    13:00-14:001:00-2:00 PM Block 3 - Activate the AgentsFirst live agent commands - after earning themAgent discovery, validation, and human reviewRequired live
    14:00-15:00Block 4 - Agentic WorkflowsCloud agents, GitHub Actions, the full reach2:00-2:15 PMBreakRest and facilitator triageRequired break
    15:00-15:15Break-2:15-3:00 PMBlock 4 - Agentic WorkflowsCloud agents, Actions, and broader automationStretch or demo
    15:15-16:153:00-4:15 PM Block 5 - Ship Your ContributionReal PR upstream to community-access/accessibility-agentsSupported project work and PR preparationRequired lab
    16:15-17:004:15-4:40 PM Block 6 - Spec Kit: Design the FutureGroup speccing session - what comes nextGroup speccing and future ideasStretch or async
    17:00-17:304:40-5:00 PM Wrap-UpNames in history, reflections, next stepsDemos, reflections, and continued contribution pathsRequired live

    Block 0 - Welcome and Orientation

    -

    9:00-9:30

    +

    9:00-9:30 AM Pacific

    Purpose

    Bring everyone to the same starting line -- whether they attended Day 1 or are joining fresh today. Celebrate what was shipped yesterday, onboard new participants, and set the Day 2 mindset: you are not a learner today - you are a product maker.

    Track A: Returning from Day 1 (Facilitator-Led, 15 min)

    @@ -206,11 +227,11 @@

    Day 2 Goal-Setting (Everyone, 10 min
  • "I want to improve the screen reader output of the @daily-briefing report."
  • "I want to write documentation for the @insiders-a11y-tracker agent."
    • -

    Write it down. You will check it against reality at 5pm.

    +

    Write it down. You will check it against reality during wrap-up.

    Block 1 - VS Code Setup

    -

    9:30-10:30

    +

    9:30-10:30 AM Pacific

    -

    This block builds on VS Code: Setup & Accessibility Basics, Git & Source Control in VS Code, and GitHub Pull Requests Extension for full reference.

    +

    This block builds on VS Code: Setup & Accessibility Basics, Git & Source Control in VS Code, and GitHub Pull Requests Extension for full reference.

    Purpose

    Move from browser-based GitHub to VS Code as your contribution environment. Set up screen reader mode. Open accessibility-agents as a workspace. Understand what you are looking at before any agent runs.

    @@ -323,7 +344,7 @@

    Step 4 - Open Copilot Chat

    JAWS users: The chat interface is a web-based panel. Switch to Forms Mode (Enter on the input field) to type. Tab out of the input to reach the conversation area in Virtual/Reading mode.

    VoiceOver users: VO+Tab to the chat input. VO+Shift+Down to interact with it. VO+Escape to stop interacting and navigate the response.

    Block 2 - Deep Contribution with Copilot

    -

    10:45-12:00

    +

    10:45 AM-12:00 PM Pacific

    Copilot Orientation (15 min)

    Before diving into contributions, get familiar with how Copilot works as a writing partner.

    Inline suggestions (Ctrl+I):

    @@ -408,7 +429,7 @@

    Contribution Checkpoint (before lu
  • Still exploring: You have not yet identified a file to improve. During lunch, read through the .github/agents/ files and pick one. When Block 3 starts, the facilitator will demo agents on the repository - watching those demos will help you see where improvements are needed.

    • Block 3 - Activate the Agents

    -

    13:00-14:00

    +

    1:00-2:00 PM Pacific

    This block is the payoff. You earned it yesterday. You understand what GitHub is, how repositories work, what issues and pull requests are, and how notifications flow. Now you watch an agent do the work you know how to verify.

    If you have any doubt about whether you have earned a particular agent: the prerequisite is simple. Can you do the equivalent step manually, right now, from memory? If yes - the agent is ready to amplify you. If no - do the manual step first. The block is structured so this never happens, but the standard is worth knowing.

    @@ -471,7 +492,7 @@

    3. @pr-review review PR #[yo
    • Did the agent catch things you missed?
    • Did the agent miss context you knew from the issue thread?
      • -
    • Is the agent's tone aligned with the community standards from Culture and Etiquette?
      • +
    • Is the agent's tone aligned with the community standards from Culture and Etiquette?

    Edit the agent's output before posting any of it. Your name goes on it.

    4. @insiders-a11y-tracker - Accessibility Change Monitoring

    @@ -481,9 +502,10 @@

    4. @ins

    Stand and Stretch (5 min)

    The agents are running. Step away from the screen for five minutes. Screen reader listening for an hour after lunch is demanding. When you return, Block 4 shows you how these same agents run in the cloud - without you pressing a key.

    Block 4 - GitHub Agentic Workflows

    -

    14:00-15:00

    +

    2:15-3:00 PM Pacific

    +

    This block is stretch material. If participants need more time to draft, commit, or push their contribution, convert this block into supported lab time and assign the workflow overview as async reading.

    -

    Reference: GitHub Actions and Workflows - read the "Day 2 Bridge" section at the bottom before this block.

    +

    Reference: GitHub Actions and Workflows - read the "Day 2 Bridge" section at the bottom before this block.

    The Cloud Extension: What Agentic Workflows Are

    Everything in Block 3 ran in VS Code - on your machine, on demand, when you asked for it. GitHub Agentic Workflows run in the cloud, inside GitHub Actions, on any trigger you define: when an issue is opened, on a schedule, when a PR is created.

    @@ -589,7 +611,7 @@

    The Reach of Agentic Thinking

    Block 5 - Ship Your Contribution

    -

    15:15-16:15

    +

    3:00-4:15 PM Pacific

    Purpose

    Polish and submit your real pull request upstream to community-access/accessibility-agents. Not to your fork - to the original. This is the moment the product maker mindset becomes tangible.

    If Your Contribution Is Still in Progress

    @@ -643,7 +665,8 @@

    Forge Partner Review

  • For each comment, ask: "Is this the kind of feedback I would want to receive?"

    • Block 6 - Spec Kit: Design the Future

    -

    16:15-17:00

    +

    4:15-4:40 PM Pacific

    +

    This block is optional when the contribution lab needs more time. For remote cohorts, it can become an async discussion thread where participants propose agent or project ideas after the live session.

    What is Spec-Driven Development? It is the practice of writing the intent of a feature before anyone builds it. The specification becomes the source of truth - AI uses it to plan tasks, contributors use it to stay aligned, and the community uses it to evaluate whether the feature actually delivered what was intended.

    @@ -673,7 +696,7 @@

    The Exerc
  • Slash commands: /specify → /plan → /tasks → implement

    • Wrap-Up

    -

    17:00-17:30

    +

    4:40-5:00 PM Pacific

    The Moment: Find Your Name in History

    1. Navigate to https://github.com/community-access/accessibility-agents
      2. @@ -759,14 +782,15 @@

      The Emotional Arc

    2. The name in history (Wrap-Up) - this should have a moment of silence and genuine acknowledgment

    Do not rush the wrap-up. The moment of seeing your name in a public commit history is one of the most meaningful things a first-time open source contributor experiences.

    -

    Previous: Notifications ← -Next: VS Code: Setup & Accessibility Basics -Related: Day 1 Agenda | GitHub Actions & Workflows | Resources

    +

    Previous: Notifications ← +Next: VS Code: Setup & Accessibility Basics +Related: Day 1 Agenda | GitHub Actions & Workflows | Resources

    + - \ No newline at end of file + diff --git a/html/admin/DAY2_QUICK_START.html b/html/admin/DAY2_QUICK_START.html index 2a0eba6..d539272 100644 --- a/html/admin/DAY2_QUICK_START.html +++ b/html/admin/DAY2_QUICK_START.html @@ -106,12 +106,12 @@

    Setup Checklist

    Complete every item before Day 2 starts. If you attended Day 1, these are already done.

    Required Accounts and Tools

      -
    • GitHub account with a verified email address (create one or verify yours at github.com/settings/emails)
      • -
    • GitHub Accessibility Settings configured: hovercards disabled, keyboard shortcuts enabled (github.com/settings/accessibility)
      • -
    • Git installed on your machine (download)
      • -
    • Visual Studio Code installed (download)
      • -
    • GitHub Copilot available in VS Code (Copilot Free is available to all GitHub users)
      • -
    • Screen reader running and tested with your browser
      • +
    • GitHub account with a verified email address (create one or verify yours at github.com/settings/emails)
      • +
    • GitHub Accessibility Settings configured: hovercards disabled, keyboard shortcuts enabled (github.com/settings/accessibility)
      • +
    • Git installed on your machine (download)
      • +
    • Visual Studio Code installed (download)
      • +
    • GitHub Copilot available in VS Code (Copilot Free is available to all GitHub users)
      • +
    • Screen reader running and tested with your browser

    Git Identity

    If you have not used Git on this machine before, configure your identity:

    @@ -137,7 +137,7 @@

    What You Missed on D

    Day 1 participants worked through Challenges 1-9 in their own Classroom repositories, covering repository navigation, issues, branching, commits, pull requests, merge conflicts, and open source culture. These activities taught the same skills listed in the self-assessment above.

    You do not need to complete those modules or practice files. If you already have GitHub fundamentals, you have the same foundation.

    What Happens When You Arrive

    -

    Day 2 Block 0 (9:00-9:30) includes time for Day-2-only participants to:

    +

    Day 2 Block 0 (9:00-9:30 AM Pacific) includes time for Day-2-only participants to:

    1. Introduce yourself to the group
    2. Verify your setup with a facilitator
      3. @@ -179,5 +179,6 @@

      Key Resources

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/admin/FACILITATOR_ASSESSMENT.html b/html/admin/FACILITATOR_ASSESSMENT.html index c0852f4..662b97b 100644 --- a/html/admin/FACILITATOR_ASSESSMENT.html +++ b/html/admin/FACILITATOR_ASSESSMENT.html @@ -74,5 +74,6 @@

      Facilitator Assessment

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/admin/FACILITATOR_CHALLENGES.html b/html/admin/FACILITATOR_CHALLENGES.html index 2dd5baa..6b5ce4b 100644 --- a/html/admin/FACILITATOR_CHALLENGES.html +++ b/html/admin/FACILITATOR_CHALLENGES.html @@ -363,14 +363,14 @@

      "Can I add more cha

      Yes. Add new issue templates to the learning-room-template repo and update the Progression Bot's challenge sequence in student-progression.yml. New challenges will only appear for students who have not yet passed the insertion point.

      Pre-Workshop Checklist

        -
      • Classroom created and assignments configured (see Workshop Deployment Guide)
        • -
      • Roster imported with all expected student usernames
        • -
      • Verification completed with a test account (Progression Bot, Aria, and autograding all confirmed working)
        • -
      • Classroom dashboard loads and shows the assignments
        • -
      • Facilitators have the classroom dashboard bookmarked
        • -
      • Grading guide reviewed by all facilitators
        • -
      • Invite links ready to share (posted in agenda documents and available for chat/email)
        • -
      • One facilitator has completed a full challenge end-to-end as a test run
        • +
      • Classroom created and assignments configured (see Workshop Deployment Guide)
        • +
      • Roster imported with all expected student usernames
        • +
      • Verification completed with a test account (Progression Bot, Aria, and autograding all confirmed working)
        • +
      • Classroom dashboard loads and shows the assignments
        • +
      • Facilitators have the classroom dashboard bookmarked
        • +
      • Grading guide reviewed by all facilitators
        • +
      • Invite links ready to share (posted in agenda documents and available for chat/email)
        • +
      • One facilitator has completed a full challenge end-to-end as a test run
      @@ -378,5 +378,6 @@

      Pre-Workshop Checklist

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/admin/FACILITATOR_CLASSROOM_TROUBLESHOOTING.html b/html/admin/FACILITATOR_CLASSROOM_TROUBLESHOOTING.html new file mode 100644 index 0000000..289ee7b --- /dev/null +++ b/html/admin/FACILITATOR_CLASSROOM_TROUBLESHOOTING.html @@ -0,0 +1,634 @@ + + + + + + + GitHub Classroom Troubleshooting Guide - GIT Going with GitHub + + + + + + + + +
      +

      GitHub Classroom Troubleshooting Guide

      +

      For Facilitators Managing Student Workflows

      +

      This document covers common issues that arise during GitHub Classroom workshops and how to resolve them quickly. Use this alongside FACILITATOR_GUIDE.md for general facilitation.

      +
      +

      🚨 Emergency: What to Do When Everything Stops Working

      +

      Bots Stopped Responding

      +

      Symptom: Students are creating PRs but Aria bot isn't commenting within 30 seconds.

      +

      Diagnostics:

      +
        +
      1. Check GitHub Status — is GitHub Actions down?
        2. +
      2. Check your test repo — try creating a PR yourself. Does Aria respond?
        3. +
      3. Check the workflow logs in the template repository:
          +
        • Go to your template repo → Actions tab
          • +
        • Look for recent Aria workflow runs
          • +
        • Do they show errors or successful completions?
          • +
        +
        4. +
      +

      Solutions:

      + + + + + + + + + + + + + + + + + + + + + + + +
      IssueFix
      GitHub Actions is downPost in chat: "We're experiencing a brief delay with our automated feedback. You can still work on challenges — we'll review PRs manually." Then skip to "Manual PR Review" below.
      Aria workflow is disabledGo to template repo → Actions → Enable Aria workflow → Re-run failed runs
      Aria workflow has an errorCheck the error log. If it's a configuration issue, fix the workflow file and re-run.
      Aria is working but slowWait a bit longer (sometimes takes 60 seconds). Refresh PR page. If still nothing, manually review.
      +

      Temporary Workaround — Manual PR Review:

      +

      If the bot is down and you need to review PRs:

      +
        +
      1. Go to student's PR
        2. +
      2. Comment with this template (copy Aria's format):
        Checking your work...
+
+✓ [thing that's good]
+✓ [thing that's good]
+
+Consider: [suggestion]
+Consider: [suggestion]
+
+Nice work! [personalized comment]
        +
        3. +
      3. Students continue as normal (they don't know the difference)
        4. +
      4. When bot comes back, future PRs will get automatic feedback
        5. +
      +

      Student Progression Bot Failed

      +

      Symptom: Student merged a PR, but the next challenge didn't appear. They're stuck waiting for Challenge 2.

      +

      Diagnostics:

      +
        +
      1. Go to student's repo → Issues tab
        2. +
      2. Check if the old challenge is closed
        3. +
      3. Check if the new challenge exists (might be closed too)
        4. +
      +

      Solutions:

      + + + + + + + + + + + + + + + + + + + +
      SymptomFix
      Old challenge is open, new challenge doesn't existProgression bot failed. Manually create the next challenge: Copy the old challenge issue, change the number, and assign to student.
      Both challenges exist but student can't see new oneRefresh their browser or have them sign out/in.
      Old challenge never closedManually close it (if student merged PR but it didn't auto-close). Then manually create the next challenge.
      +

      Video Call Is Down

      +

      Symptom: Zoom/Teams/Google Meet is disconnected. Students are isolated.

      +

      What to Do:

      +
        +
      1. Don't panic — GitHub Classroom work doesn't stop without the call
        2. +
      2. Create backup: Send message to any chat channel (email, GitHub Discussions):
        +

        "Video call dropped temporarily. You can keep working on your challenges — we're working on reconnecting. Use [Discussions/email/Slack] if you need help in the meantime."

        +
        +
        3. +
      3. Reconnect — Get the call back up within 5 minutes if possible
        4. +
      4. Continue async — If can't reconnect, facilitate async through chat/email until next day
        5. +
      +

      Co-Facilitator Is Unavailable

      +

      Symptom: You're alone and need to:

      +
        +
      • Monitor dashboard
        • +
      • Answer chat questions
        • +
      • Do a demo
        • +
      • Review PRs
        • +
      • Manage 20+ students
        • +
      +

      Solutions:

      +

      Short-term (next 30 min):

      +
        +
      • Shift to async mode: "We're doing async today. Post questions in chat and I'll respond promptly."
        • +
      • Use recorded demo if you have one
        • +
      • Focus on responding to questions quickly rather than real-time facilitation
        • +
      +

      Mid-term (next few hours):

      +
        +
      • Recruit a volunteer:
          +
        • Advanced student
          • +
        • TA or peer
          • +
        • Anyone who can watch chat
          • +
        • Give them these 3 jobs: (1) watch chat for "stuck" messages, (2) ping facilitator with blocking questions, (3) celebrate wins
          • +
        +
        • +
      • Put facilitator on mute except for key moments
        • +
      +

      Long-term:

      +
        +
      • Consider pausing until co-facilitator returns
        • +
      • Or shift to fully asynchronous (post challenges, respond to questions async)
        • +
      +
      +

      👤 Student-Level Issues

      +

      "I Can't Find My Repo"

      +

      Student is logged in, accepted the assignment, but can't find their repo.

      +

      First, clarify: "Can you get to github.com? What do you see?"

      +

      Solution Flowchart:

      +
      Q: Are you logged in?
+├─ No → Have them log in
+└─ Yes → Q: Do you see an organization name in your top-left?
+   ├─ No → They accepted but repo creation stalled
+   │   └─ Solution: Go to classroom.github.com, refresh the assignment
+   │      If still nothing, manually create repo in organization:
+   │      - Go to org
+   │      - Click "New repository"
+   │      - Name it: learning-room-[username]
+   │      - Use template
+   │      - Done
+   └─ Yes → Q: When you click your profile (top-right),
+              do you see "Your repositories"?
+      ├─ No → Permissions issue
+      │   └─ Solution: Go to github.com/settings/repositories
+      │      Filter by organization
+      │      Find your repo in the list
+      └─ Yes → They have repos but can't navigate
+          └─ Solution: Direct link:
+             github.com/community-access-classroom/learning-room-[username]
+             Share this link directly
      +

      "The Issue Isn't In My Repo"

      +

      Student accepted assignment, but Challenge 1 issue doesn't exist.

      +

      Causes:

      +
        +
      • Template repo doesn't have Challenge 1 issue
        • +
      • Issue exists but in wrong place
        • +
      • Student accepted but issue creation failed
        • +
      +

      Fix:

      +
        +
      1. Check template repo → Issues → Does Challenge 1 exist?
          +
        • If no: Create it in template, then re-create in student repo
          • +
        • If yes: Go to step 2
          • +
        +
        2. +
      2. Go to student repo → Issues → Is Challenge 1 there?
          +
        • If no: Manually create it by copying from template
          • +
        • If yes: Problem solved (they might not be looking in the right place)
          • +
        +
        3. +
      +

      Manual Creation:

      +
        +
      1. Student repo → Issues tab
        2. +
      2. Click "New issue"
        3. +
      3. Copy the Challenge 1 content from the template issue
        4. +
      4. Create it
        5. +
      5. Tell student: "Refresh your Issues page"
        6. +
      +

      "I Don't Know What the Challenge Is Asking"

      +

      Student is confused about the task.

      +

      First: Read the challenge text back to them aloud.

      +

      Then: Break it down:

      +
        +
      • What is it asking me to change? [Tell them]
        • +
      • Where is that in my repo? [Show them]
        • +
      • How will I know when I'm done? [Tell them the success criterion]
        • +
      +

      Next: Give them the first tiny step:

      +
      +

      "Start by [one specific action]. Do that, then come back and tell me what you see."

      +
      +

      Don't:

      +
        +
      • Do it for them
        • +
      • Overwhelm with the whole solution
        • +
      • Use jargon without explaining
        • +
      +

      "The Bot's Feedback Doesn't Make Sense"

      +

      Student is confused by Aria bot comment.

      +

      What the bot might say:

      +
      Consider: PR title should follow the pattern "Challenge X: [description]"
      +

      What you say:

      +
      +

      "Aria is asking you to change your PR title. Right now it says '[current title]'. +Change it to 'Challenge 1: [something describing the change]'. +Go back to your PR, click 'Edit' on the title, make the change, save."

      +
      +

      Practice Translation:

      +
        +
      • Bot: "Markdown formatting issue" → You: "Your description has an extra space somewhere. Check for weird spacing."
        • +
      • Bot: "File path incorrect" → You: "You edited the wrong file. Edit [correct filename] instead."
        • +
      • Bot: "Branch naming convention" → You: "Your branch name should be [format], not [what they did]."
        • +
      +

      "I Merged But Challenge 2 Didn't Appear"

      +

      Student merged PR. Old issue closed. New issue missing.

      +

      Causes:

      +
        +
      1. Progression bot is running late (just wait)
        2. +
      2. Progression bot failed
        3. +
      3. Student is looking in wrong place
        4. +
      +

      Fix:

      +
        +
      1. Ask: "Refresh your Issues page. Do you see Challenge 2 now?"
          +
        • If yes: Problem solved
          • +
        • If no: Go to step 2
          • +
        +
        2. +
      2. Manually create Challenge 2:
          +
        • Go to student repo → Issues
          • +
        • Click "New issue"
          • +
        • Copy Challenge 2 from template
          • +
        • Create it
          • +
        • Tell student: "Refresh and you should see it now"
          • +
        +
        3. +
      +

      "I Keep Getting an Error on PR Submit"

      +

      Student is trying to create PR but gets an error.

      +

      Common errors:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Error MessageFix
      "Nothing to commit"They didn't make any changes. Have them edit the file first.
      "Merge conflict"This is actually a good learning moment. See "Merge Conflict" section below.
      "Can't create branch"Check branch naming. May need to delete failed branch and try again.
      "Access denied"Check repo permissions. Should be able to write to their own repo.
      "File not found"They're trying to edit wrong file. Help them find correct one.
      +

      General troubleshooting:

      +
        +
      1. Have them refresh the repo
        2. +
      2. Have them close/reopen the file they're editing
        3. +
      3. Have them try a simpler edit (just one word) first
        4. +
      4. If still broken, escalate to facilitator manual review
        5. +
      +

      "I'm Done — What's Next?"

      +

      Student finished a challenge and wants to continue.

      +

      Options:

      +
        +

      1. Start the next challenge automatically:

        +
        +

        "Close this challenge issue (click 'Close issue' at the bottom) and the bot will create the next challenge for you."

        +
        +
        2. +

      2. Help a peer:

        +
        +

        "Great work! Could you review [peer's] PR? That's how real developers learn."

        +
        +
        3. +

      3. Explore bonus challenges:

        +
        +

        "You can also try some bonus challenges if you want to go deeper."

        +
        +
        4. +

      4. Take a break:

        +
        +

        "You've done great work. Take a break and come back when you're ready for the next one."

        +
        +
        5. +
      +
      +

      🔄 Specific Technical Scenarios

      +

      Merge Conflict

      +

      What it is: Two people edited the same file in incompatible ways. Git doesn't know which version to use.

      +

      When it happens: Usually Challenge 7 or later in the workshop.

      +

      Student sees:

      +
      This branch has conflicts that must be resolved
      +

      Your response:

      +
        +
      1. Don't panic — this is intentional (a learning challenge)
        2. +
      2. Don't try to fix it over chat — merge conflict resolution is hands-on
        3. +
      3. Do one of these:
          +
        • Pair the student with someone who's done merge conflicts → They learn from peer
          • +
        • Offer 1:1 help → This is worth 20 minutes of your time (real skill)
          • +
        • Have them post in Discussions → Someone can walk them through async
          • +
        +
        4. +
      +

      Teaching the fix:

      +
        +
      1. Go to the PR → click "Resolve conflicts"
        2. +
      2. GitHub shows the conflicting lines
        3. +
      3. The student picks which version is correct (or combines both)
        4. +
      4. Student marks conflict as resolved
        5. +
      5. Student completes merge
        6. +
      6. Done
        7. +
      +

      Key point: This is not a failure — this is GitHub's hardest challenge because conflicts ARE hard in real code.

      +

      Autograder Failed

      +

      What it is: Challenge X has an automated test. Student's submission failed the test.

      +

      Student sees:

      +
      Autograding failed (X failed)
      +

      Your steps:

      +
        +
      1. Go to student repo → Actions tab
        2. +
      2. Find the failed autograding run
        3. +
      3. Click it → look at the test output
        4. +
      4. Understand what failed
        5. +
      5. Explain to student in plain language:
        +

        "The test was checking for [thing]. You have [what they did]. Try [fix]."

        +
        +
        6. +
      +

      Common test failures:

      + + + + + + + + + + + + + + + + + + + + + + + +
      TestUsual Reason for Failure
      File existsFile named wrong or in wrong folder
      Content contains XText wasn't added; student edited wrong file
      Markdown formattingExtra spaces or wrong heading level
      Git historyWrong number of commits or wrong branch
      +

      Next step: Have student fix the issue and push a new commit. Autograder re-runs automatically.

      +

      Accidental Merge

      +

      What happened: Two students somehow merged the same file / repo / change.

      +

      Student panics: "I messed up!"

      +

      Your response:

      +
      +

      "This happens in real GitHub all the time. We just undo it."

      +
      +

      How to undo:

      +
        +
      1. Go to the merged PR
        2. +
      2. Look for "Revert this pull request" button
        3. +
      3. Click it
        4. +
      4. GitHub creates a new PR that reverses the change
        5. +
      5. Merge that PR
        6. +
      6. Done
        7. +
      +

      Teaching moment: Use this to explain why code review matters — this is why you have peers check your work.

      +

      Student Lost Their Work

      +

      Student says: "I was working on something and it's gone now."

      +

      Possible causes:

      +
        +
      1. They edited in GitHub web editor (not saved)
        2. +
      2. They refreshed before saving
        3. +
      3. They closed browser
        4. +
      4. They're looking in wrong repo/branch
        5. +
      +

      Your investigation:

      +
        +
      1. "What were you trying to change?" → You explain it
        2. +
      2. "Let's look at your repo" → You check it together
        3. +
      3. "Do you see a [branch/PR/draft]?" → Navigate together
        4. +
      +

      If truly lost:

      +
        +
      1. "It's okay, let's start fresh"
        2. +
      2. Help them re-do the work
        3. +
      3. This time, save properly by creating PR (not just editing)
        4. +
      +

      Prevention: Teach students: "Always create a PR before you finish. That saves your work."

      +
      +

      🌐 GitHub Platform Issues (Not Your Fault)

      +

      GitHub.com Is Down

      +

      How to know: You get an error like "502 Bad Gateway" when accessing any GitHub page.

      +

      What to do:

      +
        +
      1. Check GitHub Status
        2. +
      2. Post in chat: "GitHub.com is temporarily down. We're waiting for it to come back up. Keep your changes safe (don't refresh)."
        3. +
      3. Wait for GitHub to recover
        4. +
      4. Resume workshop
        5. +
      +

      In the meantime: Students can:

      +
        +
      • Read challenge instructions offline
        • +
      • Plan their approach
        • +
      • Discuss with peers
        • +
      +

      GitHub Actions is Slow/Down

      +

      Symptom: PRs are created but Aria bot takes 5+ minutes to respond.

      +

      What's happening: GitHub's infrastructure is overloaded.

      +

      What to do:

      +
        +
      • Let students know: "Feedback bot is running a bit slow today. Don't refresh — it'll show up in a few minutes."
        • +
      • Continue working while waiting
        • +
      • If it doesn't show up, manually review (as described earlier)
        • +
      +

      Organization Is Having Permission Issues

      +

      Symptom: Students can't create repos or write to repos.

      +

      Likely cause: Organization settings changed accidentally.

      +

      Fix:

      +
        +
      1. Go to Organization Settings
        2. +
      2. Check "Member privileges"
        3. +
      3. Make sure members can create public/private repos
        4. +
      4. Check "Repository creation" is enabled
        5. +
      +
      +

      📊 Dashboard & Monitoring Issues

      +

      Dashboard Shows Wrong Data

      +

      Symptom: Classroom dashboard shows "0 PRs merged" but you know students merged things.

      +

      Cause: Dashboard is cached or lagging behind.

      +

      Fix:

      +
        +
      1. Refresh the page
        2. +
      2. Wait a few minutes (GitHub's dashboard updates asynchronously)
        3. +
      3. Try incognito/private browser (clears cache)
        4. +
      +

      Can't Access Classroom Dashboard

      +

      Causes:

      +
        +
      1. Not logged in
        2. +
      2. Organization didn't set up Classroom
        3. +
      3. Permissions issue
        4. +
      +

      Fix:

      +
        +
      1. Go to https://classroom.github.com
        2. +
      2. Click "Sign in"
        3. +
      3. Select your organization
        4. +
      4. If not listed, go to organization settings and link GitHub Classroom
        5. +
      +

      Missing Students in Dashboard

      +

      Symptom: You know 30 people accepted the assignment, but dashboard shows only 25.

      +

      Cause: Dashboard is lagging or those people haven't been processed yet.

      +

      Fix:

      +
        +
      1. Refresh
        2. +
      2. Wait 5 minutes
        3. +
      3. Check directly: Go to org → Repositories → Look for new repos manually
        4. +
      +
      +

      🛠️ Facilitator Mistakes & Recovery

      +

      You Accidentally Closed the Wrong Challenge

      +

      You: Closed Challenge 2 in a student's repo by mistake.

      +

      Recovery:

      +
        +
      1. Go to the repo
        2. +
      2. Find the closed challenge in the Issues tab (closed filter)
        3. +
      3. Re-open it
        4. +
      4. Apologize to the student: "My mistake — I reopened it. You're good to go."
        5. +
      +

      You Created Duplicate Challenges

      +

      Symptom: Student sees Challenge 2 twice.

      +

      Cause: Manual creation while bot was also creating it.

      +

      Fix:

      +
        +
      1. Go to student repo
        2. +
      2. Close/delete the duplicate
        3. +
      3. Tell student: "Cleaned that up. You should see one Challenge 2 now."
        4. +
      +

      You Merged Something You Shouldn't Have

      +

      You: Accepted and merged a PR meant for a student to merge.

      +

      Recovery:

      +
        +
      1. Revert the PR (see "Accidental Merge" section)
        2. +
      2. Apologize: "I shouldn't have done that — I reverted it. Your merge is what counts."
        3. +
      3. Have student re-merge it (they'll get the learning)
        4. +
      +
      +

      🎯 Prevention Strategies

      +

      Before Workshop Even Starts

      +
        +
      • Test everything with your co-facilitator
        • +
      • Try breaking things intentionally to know how to fix them
        • +
      • Document the fixes in your notes
        • +
      • Create a shared "if this then that" troubleshooting doc with your co-facilitator
        • +
      +

      During Workshop

      +
        +
      • Monitor dashboard constantly (not just when someone asks for help)
        • +
      • Catch small issues before they become big ones
        • +
      • Celebrate successful workflows ("You're doing this perfectly!")
        • +
      • Keep a running log of issues that came up so you can add to this guide next time
        • +
      +

      Post-Workshop

      +
        +
      • What issues came up? Add them to this guide.
        • +
      • What took longer than expected? Update timelines.
        • +
      • What automation failed? Document the fix.
        • +
      • What did facilitators do well? Keep doing it.
        • +
      +
      +

      📞 When to Escalate

      +

      Escalate to: GitHub Support, your organization admins, or external help when:

      +
        +
      • GitHub itself is broken (Actions down, authentication issues, data loss)
        • +
      • Something is broken in the template repository (not a student issue)
        • +
      • You don't know how to fix it and neither does your co-facilitator
        • +
      • A student's entire repo is corrupted
        • +
      • Security issue (someone got access they shouldn't have)
        • +
      +

      Don't escalate for: Issues described in this guide. You can handle them.

      +
      +

      💪 You've Got This

      +

      Most issues in this guide have happened to facilitators before. You're not the first and won't be the last.

      +

      Key principles:

      +
        +
      1. Stay calm — The students are watching. If you're calm, they're calm.
        2. +
      2. Explain out loud — "Here's what I think is happening... let's check..."
        3. +
      3. Don't pretend to know — "I'm not sure. Let's figure this out together."
        4. +
      4. Celebrate the fix — "And we solved it! That's what debugging is."
        5. +
      5. Learn for next time — Note it so you're faster next time
        6. +
      +

      Every issue you solve is a story you'll tell at the next workshop.

      +
      +

      Last Updated: May 2026 | Version: 1.0 | Maintainer: Jeff Bishop

      + +
      + + + + diff --git a/html/admin/FACILITATOR_GUIDE.html b/html/admin/FACILITATOR_GUIDE.html index b3bc25d..bacd16a 100644 --- a/html/admin/FACILITATOR_GUIDE.html +++ b/html/admin/FACILITATOR_GUIDE.html @@ -4,7 +4,7 @@ - Facilitator Guide - GIT Going with GitHub + The Complete Facilitator Guide - GIT Going with GitHub @@ -28,7 +28,7 @@
      -

      Facilitator Guide

      +

      The Complete Facilitator Guide

      +

      Running GitHub Classroom Workshops for Blind and Low-Vision Students

      +

      This is your comprehensive guide to facilitate a two-day GitHub workshop. It covers everything from initial GitHub Classroom setup through post-workshop follow-up, with special attention to accessibility and student success in an open-enrollment environment.

      +
      +

      🎯 Quick Navigation

      +       +
      +

      About This Workshop

      +

      What: A two-day hybrid workshop where blind and low-vision students learn GitHub through hands-on collaboration.

      +

      Who: You're facilitating for students with varying GitHub experience (zero to intermediate). You won't know ahead of time exactly who will join.

      +

      Where: Hybrid — video call + individual GitHub Classroom repositories.

      +

      Why It Matters: GitHub is a critical skill for modern tech careers. This workshop makes GitHub accessible through:

      +
        +
      • Hybrid delivery (people can join sync or async)
        • +
      • Individual private repos (safe practice space)
        • +
      • Automated feedback (Aria bot)
        • +
      • Progressive challenges (no overwhelming leaps)
        • +
      • Peer community (students help each other)
        • +
      +

      Main Goal: Every student merges their first pull request and experiences successful collaboration.

      +
      +

      👥 Your Facilitation Team

      +

      This workshop is designed for 2 co-facilitators who can split roles:

      +
        +
      • Lead Facilitator -- Owns messaging, demos, and orchestration
        • +
      • Co-Facilitator -- Monitors chat, watches dashboard, helps individuals
        • +
      +

      If you're solo:

      +
        +
      • Recruit a volunteer (TA, peer mentor, or co-instructor)
        • +
      • Pre-record demos for asynchronous watching
        • +
      • Use GitHub Discussions more heavily for async Q&A
        • +
      +
      +

      🚀 GitHub Classroom Setup (Before Day 1)

      +

      This section is for someone (probably you!) setting up GitHub Classroom for the first time. If your Classroom is already configured, skip to Pre-Workshop Checklist.

      +

      What is GitHub Classroom?

      +

      GitHub Classroom is a free service that automatically creates private repositories for students. When a student clicks an invite link, GitHub Classroom:

      +
        +
      1. Creates a repo from your template
        2. +
      2. Assigns it to that student
        3. +
      3. Sets permissions (student owns it, you can see it)
        4. +
      4. Returns them to their new repo
        5. +
      +

      You get a dashboard showing all students' progress without manual intervention.

      +

      Prerequisites

      +

      Before setting up Classroom, you need:

      +
        +
      • A GitHub Organization (free plan works) — used to hold student repos +
        • +
      • At least one template repository in that organization
          +
        • Template includes: Challenge 1 issue, PR template, README
          • +
        • See classroom/README.md for template structure
          • +
        +
        • +
      • GitHub Classroom is linked to your organization (automatic if you're an org owner)
        • +
      +

      Step 1: Create Your First Assignment in GitHub Classroom

      +
        +
      1. Go to https://classroom.github.com
        2. +
      2. Click "New Classroom"
        3. +
      3. Select your Organization
        4. +
      4. Give it a name: learning-room-day1 (or similar)
        5. +
      5. Click "Create"
        6. +
      +

      Step 2: Add Your Co-Facilitator

      +
        +
      1. In the new classroom, click "Settings"
        2. +
      2. Under "Organization admins," add your co-facilitator's GitHub username
        3. +
      3. Save
        4. +
      +

      Step 3: Create Your First Assignment

      +
        +
      1. Click "New Assignment"
        2. +
      2. Enter title: Day 1: GitHub Basics
        3. +
      3. Select "Individual" (not group)
        4. +
      4. Under "Add your starter template repository," select your template repo
        5. +
      5. Under "Add auto-grading tests," skip this for Day 1 (optional for later challenges)
        6. +
      6. Click "Create assignment"
        7. +
      7. Copy the invite link and save it somewhere safe
        8. +
      +

      This link is what you'll share with students. It never expires.

      +

      Step 4: Create Your Second Assignment (for Day 2)

      +

      Repeat Step 3 but title it Day 2: Advanced Skills

      +

      Save both invite links in a safe place (notes, email yourself, password manager).

      +

      Step 5: Test the Automation

      +
        +
      1. Accept your own invite link (as if you were a student)
        2. +
      2. You should be asked to select your name from the roster
        3. +
      3. GitHub Classroom creates a repo for you
        4. +
      4. Verify:
          +
        • Challenge 1 issue exists in your repo
          • +
        • Aria bot is configured (check Actions tab)
          • +
        • Student Progression bot can create new issues when you close one
          • +
        +
        5. +
      5. Test creating and merging a PR to ensure:
          +
        • Aria bot comments within 30 seconds
          • +
        • Merging closes the issue
          • +
        • Next challenge issue appears
          • +
        +
        6. +
      +

      If anything is missing, see Troubleshooting GitHub Classroom Setup below.

      +

      ⚠️ Known Gotchas

      +

      "The invite link isn't working"

      +
        +
      • Make sure your Organization is created
        • +
      • Make sure the assignment is published (green checkmark in Classroom)
        • +
      • Make sure students have GitHub accounts (free account works)
        • +
      +

      "No one in my organization can accept the invite"

      +
        +
      • Students don't need to be org members
        • +
      • They just need a GitHub account
        • +
      • If issue persists, check if Classroom link was copied correctly
        • +
      +

      "Aria bot isn't commenting on PRs"

      +
        +
      • Verify Aria bot is installed in your Organization (Settings > GitHub Apps)
        • +
      • Check if the Actions workflow is enabled in the template repo
        • +
      • Manually test a PR in your test repo
        • +
      +

      "I created a second assignment but can't see an invite link"

      +
        +
      • Assignments don't have individual invite links
        • +
      • Use the classroom-wide invite link and let students select which assignment
        • +
      • Or create separate Classrooms for Day 1 and Day 2
        • +
      +
      +

      📋 Pre-Workshop Checklist (48 Hours Before)

      +

      You have two days until the workshop. Use this checklist:

      +

      72 Hours Before: Communication Sent

      +
        +
      • Email sent to all registered students with:
          +
        • Exact workshop date/time with time zone
          • +
        • Video call link + audio-only dial-in option
          • +
        • "Please test your setup 1 hour before start time"
          • +
        • FAQ link (see Appendix A)
          • +
        • Your emergency contact info
          • +
        • Screen reader accessibility note: "We've tested this with NVDA, JAWS, and VoiceOver"
          • +
        +
        • +
      +

      48 Hours Before: Infrastructure Verified

      +
        +
      • GitHub Classroom created with both Day 1 and Day 2 assignments
        • +
      • Invite links copied and ready to share
        • +
      • Template repo has Challenge 1 issue (will auto-create for each student)
        • +
      • Your test student repo exists (you accepted invite to test)
        • +
      • Aria bot installed and tested (posted to a PR, bot replied)
        • +
      • Student Progression bot works (closed an issue, new challenge appeared)
        • +
      • Both facilitators have admin access to the Classroom
        • +
      +

      24 Hours Before: Final Dry Run

      +
        +
      • You've sent the invite link to someone as a test
        • +
      • That person accepts and a repo is created successfully
        • +
      • Check the Classroom dashboard: the test student shows up
        • +
      • You can see their repo from the dashboard
        • +
      • Video call link and audio dial-in tested
        • +
      • Facilitator chat/question channel ready (Slack, Discord, GitHub Discussions, etc.)
        • +
      • Any visual slides or demos have been tested for screen reader compatibility
        • +
      +

      6 Hours Before: Day-Of Setup

      +
        +
      • GitHub Classroom dashboard open and logged in on facilitator computer
        • +
      • Student roster visible on a second monitor (or open in a tab)
        • +
      • First demo script ready (should be memorized, not read)
        • +
      • Chat moderator assigned to their role
        • +
      • Backup plan ready if:
          +
        • Video call has tech issues (phone dial-in number active)
          • +
        • Bot stops working (you'll manually review PRs)
          • +
        • Key facilitator unavailable (co-facilitator can lead)
          • +
        +
        • +
      • Coffee/water ready 😄
        • +
      +
      +

      ✨ Day 1: Live Operations

      +

      This section covers what you and your co-facilitator do during Day 1.

      +

      Hour 1: Welcome and GitHub Orientation (60 min)

      +

      What's Happening: Students are joining the call for the first time. They're nervous. Your job is to make them feel welcome and get them oriented to their GitHub repos.

      +

      Your Opening (First 5 Min)

      +

      Say something like:

      -

      This file has moved. The complete Facilitator Guide is now at facilitator/FACILITATOR_GUIDE.md.

      +

      "Welcome everyone! I'm [name], and I'm so glad you're here. This is a completely accessible workshop — we've tested everything with screen readers, and if something breaks or doesn't work for you, please tell us immediately.

      +

      Today we're learning GitHub, and in the next two days, every single one of you is going to merge your first pull request. That might not sound like a big deal, but it IS — it means you've collaborated with another person to improve code. That's a real developer skill.

      +

      We're hybrid, so you can work at your own pace. Some of you will finish fast, some will take your time, and both are completely fine.

      +

      Questions? Ask in chat anytime. That's what we're here for."

      -

      For challenge management, see FACILITATOR_CHALLENGES.md.

      -

      For workshop deployment, see classroom/README.md.

      +

      Your First Task: Get Everyone Into Their Repos

      +
        +
      1. Share the Day 1 invite link in chat
        2. +
      2. Say: "I'm giving you a link to create your private GitHub repo. Click it and GitHub will ask you to pick your name from a list. Go ahead and do that now."
        3. +
      3. Give them 5 minutes
        4. +
      4. Check the GitHub Classroom dashboard for incoming acceptances
        5. +
      5. Celebrate: "Great! I see people joining. When you accept, GitHub creates your repo automatically. You should see a Challenge 1 issue waiting for you. Find it in your Issues tab."
        6. +
      6. In chat: "Raise your hand (type in chat) when you see Challenge 1"
        7. +
      7. When 70%+ have confirmed: "Perfect! Everyone has their Challenge 1. Let's look at what you're going to do."
        8. +
      +

      Demo: Show a Challenge 1

      +
        +
      1. Open your test student repo on screen
        2. +
      2. Narrate out loud what you're seeing:
        +

        "I'm going to click the Issues tab... I see Challenge 1 here. It has a description of what I need to do. At the bottom there's a 'If You Get Stuck' section. If anything is confusing, that's where to start."

        +
        +
        3. +
      3. Read the challenge text aloud (slowly)
        4. +
      4. Ask in chat: "Does everyone see something similar in your Challenge 1? Say yes in chat"
        5. +
      5. Help anyone who doesn't see it:
          +
        • "Go to your repo page"
          • +
        • "Click the Issues tab"
          • +
        • "You should see a list; click the one that says Challenge 1"
          • +
        +
        6. +
      +

      Success Metric: Everyone has confirmed they can see Challenge 1.

      +

      Hour 2: Demo — Your First Pull Request (30 min)

      +

      What's Happening: You're showing students the exact workflow they'll repeat for every challenge. Make it crystal clear.

      +

      Your Narrated Demo

      +

      Open a challenge in your test repo and narrate every single step:

      +
      +

      "Okay, I'm going to do Challenge 1 right now, and you're going to watch me do it. I'm going to talk through every click so you know exactly what to do when it's your turn.

      +

      Step 1: Read the challenge +I'm looking at the Challenge 1 issue. It says [read it]. Okay, so I need to [summarize task]. Got it.

      +

      Step 2: Start editing +I see there's a file I need to edit. I'm going to find it in the file list and click the pencil icon to edit it. [Click pencil] +Now I'm in the editor. I can see the current text. I need to [describe what to change].

      +

      Step 3: Make my change +[Type the change while narrating] +Okay, I've made my change. Now I need to create a pull request to propose this change.

      +

      Step 4: Create a pull request +I'm scrolling down to find the 'Propose changes' button. [Click it] +GitHub is now asking me if I want to create a new branch. Yes, I do. [Click 'Create a new branch'] +Now I see the PR comparison page. It shows my old version and my new version.

      +

      Step 5: Fill out the PR form +I'm clicking the 'Create pull request' button [click] +Now I see a form with fields like title and description. There's a PR template here that helps me know what to fill in. +[Fill out form while narrating each field]

      +

      Step 6: Submit the PR +I'm clicking the green 'Create pull request' button [click] +Done! The PR is created.

      +

      Step 7: Wait for Aria bot feedback +Watch what happens next... Aria bot checks my work automatically. +[Wait 30 seconds] +See? The bot commented with feedback. It's checking if my change follows the rules.

      +

      Step 8: Address feedback (if any) +If the bot found an issue, I would go back and fix it. But my change looks good, so I'm ready to request a review.

      +

      Step 9: Request a review +I'm typing @[another student] in a comment to ask them to review my PR. +[Wait for their response in real life] +My peer approved it, so now I can merge.

      +

      Step 10: Merge the PR +I'm clicking the 'Merge pull request' button [click] +Done! The PR is merged. The issue closes automatically.

      +

      Step 11: See your next challenge +Watch — because the bot closes the Challenge 1 issue when I merged, the next challenge will appear automatically... +[Refresh Issues tab] +There it is! Challenge 2 just appeared. That's how progression works."

      +
      +

      Key Teaching Points

      +
        +
      • Don't rush — students are taking notes
        • +
      • Narrate actions before doing them: "I'm going to click the edit pencil now..." [then click]
        • +
      • Normalize mistakes: "Oops, that's not the right button. Let me click over here instead."
        • +
      • Stop and ask: "Does everyone see what I'm seeing? Type yes in chat."
        • +
      • Celebrate: "This workflow — read issue → edit → propose changes → request review → merge — you're going to do this same thing 15 times over two days. You're going to be amazingly good at it."
        • +
      +

      Success Metric: Students say things like "I see how this works" or "That was clear" in chat.

      +

      Hours 3-6: Supervised Working Session (Approximately 4.5 Hours)

      +

      What's Happening: Students are working on their challenges while you monitor and help.

      +

      Your Role During This Time

      +

      Primary: Monitor the GitHub Classroom dashboard

      +
        +
      • Refresh it every 5-10 minutes
        • +
      • Look for:
          +
        • New commits (student is active)
          • +
        • PRs being created (they're progressing)
          • +
        • Autograding failures (might need help)
          • +
        • Students with zero activity (might need a nudge)
          • +
        +
        • +
      +

      Secondary: Be responsive in chat and comments

      +

      When you notice something:

      +
        +

      1. Student hasn't started after 20 min → Chat message:

        +
        +

        "Hey @student! How's it going? Found your Challenge 1? If you need a hint, just ask in chat."

        +
        +
        2. +

      2. Student created a PR → Check it

        +
          +
        • Did Aria bot comment?
          • +
        • Does the student understand the feedback?
          • +
        • Comment if needed: "Looking good! I see the bot asked you to [X]. Give that a try!"
          • +
        +
        3. +

      3. Student merged a PR → Celebrate publicly:

        +
        +

        "🎉 Awesome work @student! You just merged your first pull request! That's huge."

        +
        +
        4. +

      4. Aria bot gave confusing feedback → Translate it:

        +
        +

        "I see Aria's feedback. Let me explain what it means: [plain language explanation]. Try [specific fix]."

        +
        +
        5. +

      5. Student is stuck and says so → Help them

        +
          +
        • Look at their repo
          • +
        • Read the "If You Get Stuck" section of their challenge
          • +
        • Comment: "I see where you're stuck. Try [specific step]. Let me know how it goes!"
          • +
        +
        6. +
      +

      Expected Rhythm

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TimeWhat to Expect
      Min 1-15Students opening PRs on their first challenge
      Min 15-30Aria bot feedback flowing; students starting fixes
      Min 30-60First reviews happening; students requesting merges
      Min 60-120Early merges happening; progression bot creating Challenge 2
      Min 120-180Second wave of PRs; momentum building; some finishing Challenge 2
      Min 180-270Mixed activity: some on Challenge 3+, others still on Challenge 1, all valid
      +

      Facilitator Interventions

      +

      If a student says "I don't understand this challenge":

      +
        +
      1. Read the challenge text back to them
        2. +
      2. Break it into smaller steps
        3. +
      3. Give one next step: "Try [this specific thing] first"
        4. +
      4. Offer to look at their repo: "Send me the link and I'll take a look"
        5. +
      +

      If a student says "I'm done, what do I do next?":

      +
        +
      • Option A: "Start Challenge 2 (it will appear automatically when the bot processes)"
        • +
      • Option B: "Can you review someone else's PR? That helps them and teaches you code review"
        • +
      • Option C: "Help a peer who's still working. Teaching others is real learning"
        • +
      +

      If Aria bot stops responding:

      +
        +
      1. Check GitHub Actions status page
        2. +
      2. If it's down, post in chat: "We're experiencing a brief delay with our feedback bot. We're looking into it."
        3. +
      3. Manually review PRs and post feedback in Aria's format (see Troubleshooting)
        4. +
      +

      If two students want to peer review:

      +
        +
      • Perfect! Encourage it. That's the whole point.
        • +
      • Remind them: "Click the 'Files changed' tab to see the code. Leave thoughtful comments."
        • +
      +

      Managing Energy

      +
        +
      • Every 60 minutes: "Quick break everyone. Stand up, stretch, grab water."
        • +
      • Answer the same question multiple times without sighing
        • +
      • Celebrate effort, not just finished work: "Nice debugging work!" (even if they haven't finished)
        • +
      • If energy is low: "We're doing amazing. Look at how many PRs have been merged!"
        • +
      +

      Hour 7: Q&A and Reflection (30 min)

      +

      What's Happening: You're wrapping up Day 1, celebrating progress, and setting up for Day 2.

      +

      Reflection Prompt

      +

      Ask in chat or video:

      +
      +

      "Tell us in chat: What was one thing you learned today about GitHub? Or what surprised you?"

      +
      +

      Listen and affirm:

      +
        +
      • "GitHub is [student answer]" ✓
        • +
      • "Peer review helps [student answer]" ✓
        • +
      • "I struggled with [thing] but I figured it out" ✓ CELEBRATE THIS
        • +
      +

      Share Day 1 Stats

      +

      Pull from the Classroom dashboard:

      +
      +

      "Today, X students joined, Y PRs were merged, Z students completed multiple challenges. That's real progress. You all should be proud."

      +
      +

      Troubleshoot Remaining Issues

      +
        +
      • Students still stuck: "We can help you after this call. Don't leave without asking."
        • +
      • Questions about tomorrow: "Tomorrow we'll do deeper work. Same process, harder challenges."
        • +
      • Access issues: "If you have anything that didn't work for your screen reader, email us. We fix it before tomorrow."
        • +
      +

      Send Them Off

      +
      +

      "Great work today! Rest well. Tomorrow we go deeper. See you at [time]!"

      +
      +

      Hour 8: Optional Office Hours (60 min)

      +
        +
      • Stay available in chat or on call
        • +
      • Help any student who wants to:
          +
        • Finish their first PR
          • +
        • Start Challenge 2
          • +
        • Ask follow-up questions
          • +
        • Troubleshoot issues
          • +
        +
        • +
      +
      +

      🎉 Day 2: Deeper Skills and Celebration

      +

      Hour 1: Recap and Momentum (30 min)

      +

      What's Happening: Students join fresh. You remind them of their progress and introduce Day 2 assignment.

      +

      Your Opening

      +
      +

      "Welcome back! Let me tell you what you did yesterday...

      +

      X students completed Challenge 1 and merged their first PR. That's huge. +Y students are already on Challenge 2 or beyond. +Z students are working async and will finish today.

      +

      That means you all know:

      +
        +
      • How to navigate GitHub
        • +
      • How to edit and create a PR
        • +
      • How to request a review
        • +
      • How to merge a PR
        • +
      +

      You did that in one day. That's amazing.

      +

      Today we go deeper. New challenges, more complex scenarios, and you're all ready for it."

      +
      +

      Day 2 Assignment

      +
        +
      1. Share the Day 2 invite link in chat
        2. +
      2. Say: "Click this link and accept Day 2 assignment. It's separate from Day 1."
        3. +
      3. Give them 5 minutes
        4. +
      4. Check the Classroom dashboard
        5. +
      5. When most have accepted: "Perfect! Challenge 10 is waiting for you. This one is a step up in difficulty. You've got this."
        6. +
      +

      Hour 2: Code Review Deep Dive (60 min)

      +

      What's Happening: You're teaching the skill of reviewing someone else's code professionally.

      +

      Demo: How to Review a PR

      +
        +
      1. Open a student's PR from yesterday (ask permission or use your test repo)
        2. +
      2. Narrate while reviewing:
        +

        "Okay, someone asked me to review their PR. Here's what I do:

        +

        Step 1: Read the description — What are they changing and why? [read it]

        +

        Step 2: Click 'Files changed' — Now I see the code diff. Red means removed, green means added. [click and show]

        +

        Step 3: Read the code carefully — Does it make sense? Is it following the guidelines? [read and comment]

        +

        Step 4: Leave feedback — I click the comment button next to lines I have thoughts about. [click]

        +

        Step 5: Be specific and kind — Instead of 'this is wrong,' I say 'I notice this could be [better]. Consider [suggestion].'

        +

        Step 6: Approve or request changes — At the top, I click 'Approve' if I'm happy with it, or 'Request changes' if I want fixes."

        +
        +
        3. +
      +

      Pair Review Activity

      +
        +
      1. Assign pairs: "Student A, you review Student B's PR. Student B, you'll review Student C's. Etc."
        2. +
      2. Give them a template for feedback:
        - What I liked about this PR: [specific thing]
+- One question I have: [genuine question]
+- One suggestion: [improvement idea]
        +
        3. +
      3. Give them 20 minutes to do reviews
        4. +
      4. Check back and celebrate: "I see great comments happening!"
        5. +
      +

      Hours 3-7: Progressive Challenges (Approximately 4.5 Hours)

      +

      What's Happening: Students are working through Challenges 10-16, which are harder and more realistic.

      +

      Challenge Progression Map

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TrackChallengesTopicsExpected Time
      Core10-13VS Code, Git locally, branching, conflict resolution4-6 hrs
      Advanced14-16Issue templates, fork-and-contribute workflow, capstone6-8 hrs
      Bonusbonus-a through bonus-eCLI, search, branch protection, cloud editors2-4 hrs each
      +

      Students don't see challenges that aren't unlocked yet. The progression bot unlocks them when challenges are closed.

      +

      Your Facilitation During Hour 3-7

      +

      Dashboard monitoring: Every 10 minutes, check:

      +
        +
      • Who's on which challenge
        • +
      • Any students still on Challenge 10 (might need help)
        • +
      • Any autograding failures
        • +
      • Recent merges (celebrate them)
        • +
      +

      Proactive help:

      +
        +
      • Students on Challenge 14+ → Extra encouragement: "You're getting into real developer territory!"
        • +
      • Students still on Challenge 10-12 → Gentle check-in: "How's it going? Stuck on anything?"
        • +
      • Peer reviews → Encourage more: "I see reviewers doing great work!"
        • +
      +

      Responsive help:

      +
        +
      • Student asks "What's Git?" → Explain clearly, add to a running glossary
        • +
      • Student's PR has autograder failure → Check what test failed, help them debug
        • +
      • Student at same place as another → Suggest they collaborate: "You two are both on Challenge 11 — want to pair?"
        • +
      +

      Managing Different Paces

      +

      Faster students (on Challenge 14+):

      +
        +
      • Give them bonus challenges to explore
        • +
      • Invite them to help peers
        • +
      • Recognize their ambition: "You're flying through these!"
        • +
      +

      Average pace students (on Challenge 11-13):

      +
        +
      • Keep them engaged with encouragement
        • +
      • Help when they hit roadblocks
        • +
      • Celebrate steady progress
        • +
      +

      Slower pace students (still on Challenge 10-12):

      +
        +
      • NO pressure — this is fine
        • +
      • Check if they need help or prefer async
        • +
      • Offer 1:1 support after main session
        • +
      • Include them in celebrations: "X students working on foundational skills"
        • +
      +

      Key Facilitator Moves

      +
        +
      1. Answer the same question multiple ways — someone will finally get it
        2. +
      2. Celebrate effort — "I see you troubleshooting that error. That's exactly what real developers do."
        3. +
      3. Normalize struggle — "Everyone gets stuck. That's where learning happens."
        4. +
      4. Bridge knowledge gaps — If someone doesn't know Git, teach it briefly, add to resources
        5. +
      5. Keep energy positive — Day 2 is harder; your enthusiasm carries them
        6. +
      +

      Hour 7: Final Q&A and Celebration (60 min)

      +

      What's Happening: You're wrapping up the two-day journey, celebrating progress, and sending students off with confidence.

      +

      Pull the Dashboard Data

      +

      From GitHub Classroom, collect:

      +
        +
      • Total students enrolled
        • +
      • Total students who merged at least one PR
        • +
      • Total PRs merged (all challenges combined)
        • +
      • Fastest student (by PRs merged)
        • +
      • Students who completed code review cycle
        • +
      • Students who made it to advanced challenges
        • +
      • Students still actively working (will continue async)
        • +
      +

      Say something like:

      +
      +

      "Over two days, we had X students join. Here's what we accomplished:

      +
        +
      • Y students merged their first PR
        • +
      • Z total PRs were merged — that's real code changes
        • +
      • N students made it to advanced challenges
        • +
      • Everyone who's here learned something new about GitHub
        • +
      +

      That's incredible. You should all be proud."

      +
      +

      Celebrate Specific Wins

      +

      Call out individuals by name (with permission):

      +
      +

      "@student1 — you merged 5 PRs! That's impressive velocity." +"@student2 — you helped three peers debug their code. That's mentorship." +"@student3 — you hit Challenge 15 on day 2. You went deep."

      +
      +

      Next Steps Guidance

      +

      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. +
      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. Build something — Use GitHub as your project portfolio"
        5. +
      +
      +

      Share Resources

      +

      Point to:

      +
        +
      • CONTRIBUTING.md — How to contribute to open source
        • +
      • docs/ — All the reference guides
        • +
      • Alumni community link
        • +
      • Your contact info for questions
        • +
      +

      Thank You Note

      +
      +

      "Thank you for being here, for asking great questions, for helping each other, and for giving GitHub a real try. The fact that you're learning this skill — that you know GitHub — that matters. Use it well.

      +

      We're so glad you were here."

      +
      +

      Hour 8: Informal Hangout / Office Hours (60 min)

      +
        +
      • Keep call open for students who want to:
          +
        • Continue working (keep dashboard accessible)
          • +
        • Chat with peers
          • +
        • Ask final questions
          • +
        • Exchange GitHub usernames / social
          • +
        +
        • +
      • Optional: Have facilitators available in chat for async follow-ups
        • +
      +
      +

      📊 Post-Workshop Tasks (Week After)

      +

      Day 3 (Next Day)

      +
        +
      • Export GitHub Classroom dashboard data
          +
        • Total students, PRs merged, challenges completed
          • +
        • Save as CSV or screenshot
          • +
        +
        • +
      • Identify students who are stuck/need follow-up
          +
        • Email them: "You're doing great! Need any help finishing?"
          • +
        +
        • +
      • Document any automation failures
          +
        • If Aria bot or progression bot had issues, log them for your next setup
          • +
        +
        • +
      • Thank your co-facilitator
          +
        • Debrief on what went well and what to improve
          • +
        +
        • +
      +

      Days 4-7

      +
        +
      • Send personalized email to each student
          +
        • Reference something specific they accomplished
          • +
        • Point them to next resource (alumni channel, open source guide)
          • +
        • Leave door open for questions
          • +
        +
        • +
      • Update your facilitator notes
          +
        • What questions came up most?
          • +
        • What accessibility issues appeared?
          • +
        • What challenges took longer than expected?
          • +
        +
        • +
      • Invite students to alumni community
          +
        • Slack / Discord / GitHub Discussions channel
          • +
        • Encourage them to stay in touch and help future students
          • +
        +
        • +
      +

      Weeks 2+

      +
        +
      • Monitor alumni community
          +
        • Answer questions
          • +
        • Celebrate project shares
          • +
        • Offer 1:1 mentorship if interested
          • +
        +
        • +
      • Prepare for next cohort
          +
        • Update facilitator guide based on learnings
          • +
        • Update challenge content based on student feedback
          • +
        • Test GitHub Classroom automation again
          • +
        +
        • +
      +
      +

      🆘 Quick Troubleshooting Reference

      +

      During Workshop

      +

      "I can't see my GitHub repo" +→ Have them go to github.com/settings/repositories and look for repo with their name +→ Or share the direct link: community-access-classroom/learning-room-[username]

      +

      "The bot didn't comment on my PR" +→ Refresh the page +→ Wait 30 seconds (bot takes a bit) +→ If still nothing, manually review and comment with feedback

      +

      "I merged but Challenge 2 didn't appear" +→ Refresh their issues page +→ If still nothing, manually create Challenge 2 issue (copy Challenge 1, change number)

      +

      "Two students merged the same PR by accident" +→ No problem! It happens in real GitHub too. +→ Revert the merge: "Revert this PR" button +→ 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 +→ Students can continue async

      +

      For more, see FACILITATOR_CLASSROOM_TROUBLESHOOTING.md

      +
      +

      📚 Appendices

      +

      Appendix A: Facilitator Communication Templates

      +

      Pre-Workshop Email

      +

      Subject: Your GitHub Workshop Starts Tomorrow!

      +
      +

      Hi [Name],

      +

      We're excited to have you join us tomorrow at [TIME] for our two-day GitHub workshop!

      +

      Quick checklist:

      +
        +
      • GitHub account created? (Go to github.com)
        • +
      • Can you join the video call? (Link: [URL]) or dial audio-only: [NUMBER]
        • +
      • Do you have a screen reader installed? (NVDA, JAWS, or VoiceOver work great with GitHub)
        • +
      +

      Tomorrow's plan:

      +
        +
      • Hour 1: Welcome and GitHub orientation
        • +
      • Hour 2: Demo of your first PR
        • +
      • Hours 3-6: You work on challenges, we help
        • +
      • Hour 7: Q&A and celebration
        • +
      +

      If you have questions before we start: Email us or chat us — we're here to help!

      +

      See you tomorrow!

      +
      +

      "Student is Stuck" Response

      +
      +

      Hi @[Name],

      +

      I see you working on Challenge [X]. Let me help.

      +

      The challenge is asking you to [rephrase in plain language].

      +

      Here's the next step: [ONE specific thing to do]

      +

      Try that and let me know how it goes!

      +
      +

      Post-Workshop Thank You

      +
      +

      Hi [Name],

      +

      Thank you so much for joining our GitHub workshop! I wanted to reach out and tell you what an awesome job you did.

      +

      You merged [X] pull requests and worked through [Y] challenges. That shows real growth.

      +

      I especially appreciated when you [specific moment they did well].

      +

      Keep learning:

      +
        +
      • Check out CONTRIBUTING.md for contributing to open source
        • +
      • Join our alumni community: [LINK]
        • +
      • Email if you have any GitHub questions — we're here
        • +
      +

      Great work, and keep building!

      +
      +

      Appendix B: Screen Reader Quick Reference

      +

      For NVDA Users:

      +
        +
      • Insert + Down Arrow — Read all
        • +
      • H — Jump to next heading
        • +
      • Tab — Jump to next button/link
        • +
      • F — Jump to next form field
        • +
      • A — Jump to next button or clickable element
        • +
      +

      For JAWS Users:

      +
        +
      • Insert + Down Arrow — Read all
        • +
      • H — Jump to next heading
        • +
      • Tab — Jump to next button/link
        • +
      • R — Jump to next form field
        • +
      • B — Jump to next button
        • +
      +

      For VoiceOver (Mac) Users:

      +
        +
      • VO + Down Arrow — Read continuously
        • +
      • H — Jump to next heading
        • +
      • Tab — Jump to next button/link
        • +
      • F — Jump to next form field
        • +
      +

      GitHub.com Keyboard Shortcuts (Most Important):

      +
        +
      • T — Open file finder
        • +
      • I — Jump to Issues
        • +
      • P — Jump to Pull requests
        • +
      • G then C — Go to Code
        • +
      • ? — Show all keyboard shortcuts
        • +
      +

      Appendix C: Common Challenge "If You Get Stuck" Phrases

      +

      These are used in each challenge issue. Paste them into challenge issues to guide stuck students:

      +

      For editing challenges:

      +
      +

      If you get stuck: Look for the pencil icon (✏️) to edit the file. Type your change, then scroll down and click "Propose changes."

      +
      +

      For PR challenges:

      +
      +

      If you get stuck: Don't refresh the page yet! GitHub is still processing. Wait 30 seconds. If still nothing, paste this link in chat: [direct link to PR]

      +
      +

      For review challenges:

      +
      +

      If you get stuck: Click the "Files changed" tab on the PR. Click the comment bubble next to lines you want to comment on. Type your feedback and click "Comment."

      +
      +

      For merge conflicts:

      +
      +

      If you get stuck: This is the hardest challenge because merge conflicts are tricky in real life too. Post your question in chat — this is not something to figure out alone.

      +
      +
      +

      💡 Philosophy and Final Thoughts

      +

      This workshop succeeds because of you — the facilitator. Here's what you bring:

      +
        +
      • Patience — Answer the same question 10 times without frustration
        • +
      • Clarity — Explain complex things in simple language
        • +
      • Celebration — Make everyone feel like their progress matters (it does)
        • +
      • Accessibility — Test everything with screen readers, adapt for each student
        • +
      • Humanity — You're not perfect, and that's okay. Normalize mistakes.
        • +
      • Community — Build an environment where students help each other
        • +
      +

      You're not just teaching GitHub. You're teaching inclusion — showing students that tech spaces can and should be accessible to everyone, including blind and low-vision people.

      +

      Every student who merges their first PR is a student who now knows they belong in tech.

      +

      That's the real goal. Everything else follows from that.

      +
      +

      📞 Need Help?

      +

      If something goes wrong:

      +
        +
      1. Automation failing? → See FACILITATOR_CLASSROOM_TROUBLESHOOTING.md
        2. +
      2. Student having issues? → See FACILITATOR_OPERATIONS.md
        3. +
      3. Setting up for first time? → Scroll back to GitHub Classroom Setup
        4. +
      4. Can't find what you need? → Email or ping us — we'll help and update this guide
        5. +
      +
      +

      Last Updated: May 2026 | Version: 2.0 | Maintainer: Jeff Bishop

      + - \ No newline at end of file + diff --git a/html/admin/FACILITATOR_OPERATIONS.html b/html/admin/FACILITATOR_OPERATIONS.html new file mode 100644 index 0000000..3fdad66 --- /dev/null +++ b/html/admin/FACILITATOR_OPERATIONS.html @@ -0,0 +1,654 @@ + + + + + + + Facilitator Operations Guide - GIT Going with GitHub + + + + + + + + +
      +

      Facilitator Operations Guide

      +

      Real-Time Workshop Management Procedures

      +

      This guide provides step-by-step procedures for facilitators during the workshop. Use this alongside FACILITATOR_GUIDE.md for the big picture and FACILITATOR_CLASSROOM_TROUBLESHOOTING.md for problem-solving.

      +
      +

      Pre-Workshop Setup (3 Hours Before)

      +

      Facilitator Workstation Setup

      +

      Physical Setup:

      +
        +
      • Primary monitor: GitHub Classroom dashboard
        • +
      • Secondary monitor (or browser tab): Student repo template / demo repo
        • +
      • Laptop: Video call software tested
        • +
      • Phone: Audio dial-in number saved
        • +
      • Notepad: For tracking student issues in real-time
        • +
      • Water/coffee within reach
        • +
      • Noise-canceling headphones (optional but helpful)
        • +
      +

      Software Setup:

      +
        +
      • GitHub Classroom dashboard open and logged in +
        • +
      • Test student repo open in a tab (your repo you created during setup)
        • +
      • GitHub Discussions / chat channel open
        • +
      • Timer or stopwatch ready (for tracking session times)
        • +
      • Email client visible (for student emails)
        • +
      +

      Communication Setup:

      +
        +
      • Co-facilitator has your phone number
        • +
      • You have their phone number
        • +
      • Both have chat channel open
        • +
      • Backup communication method agreed on (Slack, Discord, etc.)
        • +
      +

      Dashboard Orientation

      +

      Open classroom.github.com:

      +
        +

      1. Click your classroom → You see:

        +
          +
        • Assignment name
          • +
        • Number of students who've accepted
          • +
        • List of all students + their repo status
          • +
        • Recent commit activity
          • +
        +
        2. +

      2. Key columns to watch:

        +
          +
        • ✓ Accept status — Click to see if student repo was created
          • +
        • Last commit time — When they last pushed code
          • +
        • Autograding status — Pass/fail on any tests
          • +
        +
        3. +

      3. Filter by status:

        +
          +
        • Accepted → Students who have repos
          • +
        • Pending → Students who haven't accepted yet (you might need to follow up)
          • +
        +
        4. +
      4. Favorite this page — You'll visit it constantly
        5. +
      +

      Notification Setup

      +

      Ask GitHub or chat platform to notify you of:

      +
        +
      • GitHub Discussions (if using for questions)
        • +
      • Mentions in chat (@facilitator)
        • +
      • Direct messages from students
        • +
      +

      Test notifications: Have your co-facilitator ping you to confirm alerts work.

      +
      +

      Starting Day 1 (15 Minutes Before Call Starts)

      +

      Final Checklist (5 min before start)

      +
        +
      • Yourself: Bathroom break done, water nearby, headphones on
        • +
      • Software: All tabs open, no unexpected pop-ups
        • +
      • Dashboard: Refreshed, showing latest data
        • +
      • Co-facilitator: Online and confirmed in chat
        • +
      • Students: Should be joining now — check incoming attendees
        • +
      • Recording: If recording, make sure it's recording
        • +
      • Slides: If using slides, they're visible and tested
        • +
      +

      First 60 Seconds on Call

      +
        +

      1. Welcome message to chat:

        +
        Welcome to the GitHub Workshop! 👋
+If you can see this message, you're connected.
+Video or audio-only? Both are fine.
+Screen reader users: All of GitHub.com is accessible.
+Questions? Ask in chat anytime!
        +
        2. +

      2. Monitor arrivals:

        +
          +
        • Watch participant list
          • +
        • Greet people by name as they join
          • +
        • "Hi [name], welcome! Glad you made it!"
          • +
        +
        3. +

      3. Quick accessibility check:

        +
          +
        • "If your screen reader is working and you can hear me, say so in chat"
          • +
        • Confirm at least 70% have confirmed
          • +
        • If issues: "Let's get those fixed. Chat or email me."
          • +
        +
        4. +

      4. Settle the room:

        +
          +
        • "We'll start in about 5 minutes. Get comfortable, grab water, etc."
          • +
        +
        5. +
      +
      +

      During Hour 1: Welcome and Orientation

      +

      0:00-0:05: Your Opening

      +

      Talking points (say these out loud):

      +
      +

      "Welcome everyone. I'm [name], and this is [co-facilitator name]. We're going to spend the next two days learning GitHub together.

      +

      [Pause for acknowledgment]

      +

      This is a completely accessible workshop. We've tested it with NVDA, JAWS, and VoiceOver. If something doesn't work for your screen reader, tell us immediately and we'll fix it.

      +

      [Pause]

      +

      Over the next two days, every single one of you is going to merge your first pull request. That might not sound like a big deal, but it is. It means you've collaborated with another person to improve code. That's a real developer skill.

      +

      [Pause]

      +

      We're hybrid, so you can work at your own pace. Some will finish fast, some will take time, and both are completely valid. No pressure.

      +

      [Pause]

      +

      Questions? Ask in chat anytime. That's what we're here for. Let's get started."

      +
      +

      0:05-0:15: Getting Into Repos

      +

      Step 1: Share the invite link

      +

      In chat, post:

      +
      Here's your Day 1 invite link:
+[PASTE YOUR INVITE LINK]
+
+Click it and GitHub will ask you to pick your name from a list.
+Accept and GitHub creates your repo.
      +

      Step 2: Monitor the Classroom dashboard

      +
        +
      • Refresh every 30 seconds
        • +
      • Watch for new acceptances
        • +
      • Count them out loud: "I see 3... 5... 10 people joining..."
        • +
      +

      Step 3: Guide through the process

      +

      In chat as things happen:

      +
      Great! I see people accepting the invite.
+You should now be in your private repo.
+Look for "Challenge 1" in your Issues tab.
+When you see it, say so in chat!
      +

      Step 4: Help people who are stuck

      +

      After 5 minutes, if someone hasn't said they found Challenge 1:

      +
        +
      • Message them directly: "Hey @[name], did you find your Challenge 1? Let me know if you need help."
        • +
      • Check dashboard: Did their repo get created?
        • +
      • If repo created but they can't find issue: Direct link: github.com/community-access-classroom/learning-room-[username]/issues
        • +
      +

      Step 5: Confirm everyone is in

      +

      Wait until 70%+ have said they see Challenge 1 before moving forward.

      +

      0:15-0:25: Demo Reading Challenge 1

      +

      Your actions:

      +
        +
      1. Open your test repo on screen
        2. +
      2. Narrate what you're doing:
        "I'm going to show you what Challenge 1 looks like.
+I'm clicking the Issues tab...
+I see Challenge 1 here...
+Let me read it to you..."
        +
        3. +
      3. Read the challenge issue text out loud (slowly, pausing between sentences)
        4. +
      4. Point out key sections:
          +
        • "Here's what I need to do: [describe]"
          • +
        • "At the bottom, there's a 'If You Get Stuck' section — that's your safety net"
          • +
        • "This is a great challenge to learn the basics"
          • +
        +
        5. +
      +

      Ask in chat: "Does everyone see something similar in their Challenge 1?"

      +

      Wait for confirmations. Help anyone who sees something different.

      +
      +

      During Hour 2: Demo PR Workflow

      +

      Demo Repo: Do Challenge 1 for Real

      +

      Setup: You're using your test repo (the one you created during setup).

      +

      Narration Style: Talk through EVERY action before doing it.

      +
      +

      "Okay, I'm going to complete Challenge 1 right now. Watch what I do, because you're going to do the same thing 15 times this week.

      +

      Step 1: Read the challenge +The challenge is asking me to [describe]. Okay, I understand what I need to do.

      +

      Step 2: Find the file +I need to edit a file called [filename]. Let me look in the file list... there it is.

      +

      Step 3: Click edit +I'm clicking the pencil icon (✏️) to edit the file.

      +

      Step 4: Make my change +[Type while narrating] I'm adding this text... done.

      +

      Step 5: Create PR +I'm scrolling down... I see 'Propose changes' button. I'm clicking it.

      +

      Step 6: Create new branch +GitHub is asking if I want a new branch. Yes, I do. Clicking 'Create branch'...

      +

      Step 7: Compare PR +Now I see the comparison. My change is in green. Looks good!

      +

      Step 8: Review PR template +I'm clicking 'Create pull request'... +Now I see a form with a template. The template tells me what to fill in. +[Fill form while narrating each field]

      +

      Step 9: Create PR +I'm clicking the green 'Create pull request' button... done!

      +

      Step 10: Wait for Aria +Now watch... Aria bot automatically checks my work... +[Wait 30 seconds] +There! The bot commented. It's checking if I followed the rules.

      +

      Step 11: If I need to fix it +If Aria said I need to change something, I would go back to the PR and push a new commit. +Since my PR is good, I'm ready to ask for a review.

      +

      Step 12: Request review +I'm typing @[another-student] to ask them to review my PR.

      +

      Step 13: Get approval +They reviewed it and approved.

      +

      Step 14: Merge +I'm clicking 'Merge pull request'... done!

      +

      Step 15: See next challenge +Now watch the Issues tab... +[Refresh] +Challenge 2 just appeared! That's how progression works.

      +

      That's the workflow. You'll repeat this for every challenge. By the end of Day 2, you'll be excellent at this."

      +
      +

      Post-Demo Q&A

      +

      In chat: "Questions about what you just watched?"

      +

      Answer a few questions, then:

      +
      +

      "Great. Any more questions? If not, let's move to working session. You've got this!"

      +
      +
      +

      During Hours 3-6: Working Session Management

      +

      Facilitator Dashboard Monitoring Routine

      +

      Every 5-10 minutes:

      +
        +
      1. Refresh Classroom dashboard
        2. +

      2. Scan for:

        +
          +
        • New repos created (scroll Accepted column)
          • +
        • Recent commits (look at timestamps)
          • +
        • PRs appearing (check student repos)
          • +
        • Autograding failures (if applicable)
          • +
        • Zero activity students (might need nudge)
          • +
        +
        3. +

      3. Make notes:

        +
          +
        • "Student A has PR open — review when bot done"
          • +
        • "Student B has zero commits — check in at 45-min mark"
          • +
        • "Student C merged — celebrate in chat!"
          • +
        +
        4. +
      +

      Proactive Interventions (By Time)

      +

      0-15 min:

      +
        +
      • Monitor dashboard constantly
        • +
      • Expect: First PRs being created
        • +
      • If nothing: "Anyone need help with their first PR?"
        • +
      +

      15-30 min:

      +
        +
      • Aria bot feedback should be flowing
        • +
      • Look for confused students
        • +
      • In chat: "Anyone see feedback from Aria? Let me know if it's confusing!"
        • +
      +

      30-60 min:

      +
        +
      • First merges happening
        • +
      • New challenges appearing
        • +
      • Celebrate: "🎉 @student1 just merged their first PR! Nice work!"
        • +
      +

      60-120 min:

      +
        +
      • Mixed activity
        • +
      • Some on Challenge 2, others still on Challenge 1 — both OK
        • +
      • Check on quiet students: "How's it going, @student2?"
        • +
      +

      120-180 min:

      +
        +
      • Momentum building
        • +
      • Multiple PRs happening simultaneously
        • +
      • Watch for: Stuck students (same challenge 60+ min)
        • +
      +

      180-270 min:

      +
        +
      • Peak activity
        • +
      • Help focuses on blockers, not starters
        • +
      • Celebrate milestones: "Wow, @student3 is on Challenge 3!"
        • +
      +

      Responding to Common Chat Messages

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Student SaysYour Response
      "I'm stuck""Tell me what challenge you're on and what's confusing." (Then see troubleshooting guide)
      "Is this right?""What did you create? Show me a link." (Then validate)
      "I merged!""🎉 Awesome! You just merged your first PR! That's huge!"
      "What's next?""Your next challenge should appear soon. Refresh your Issues. If not, let me know!"
      "Is [technology] important?""Great question! [Short answer]. Let's talk more after this challenge."
      "My screen reader glitched""Which screen reader? What glitched? Let's fix it." (Then escalate if needed)
      +

      Peer Review Encouragement

      +

      What to look for:

      +
        +
      • Student A finishes Challenge 1
        • +
      • Student B also finished Challenge 1
        • +
      • Opportunity: Have them review each other!
        • +
      +

      What to say:

      +
      +

      "@student1 and @student2 — you both finished Challenge 1! Want to review each other's PRs? That's how real developers work."

      +
      +

      Guide them:

      +
        +
      • "Go to their PR"
        • +
      • "Click 'Files changed'"
        • +
      • "Leave a comment on lines you have thoughts about"
        • +
      • "Then approve or request changes"
        • +
      +
      +

      During Hour 7: Q&A and Wrap-Up

      +

      0:00-0:10: Celebration

      +

      Pull Classroom dashboard data:

      +
        +
      • X students accepted
        • +
      • Y PRs merged
        • +
      • Z students on Challenge 2+
        • +
      +

      Say:

      +
      +

      "Okay everyone, look at what you did today:

      +
        +
      • of you joined the workshop
        • +
      • [Y] pull requests were merged
        • +
      • [Z] of you are already on Challenge 2
        • +
      +

      That is incredible. You learned GitHub in one day. Give yourselves a hand."

      +
      +

      0:10-0:20: Reflection Prompt

      +

      In chat or on call:

      +
      +

      "Tell us in chat: What was one thing you learned about GitHub today? Or something that surprised you?"

      +
      +

      Read responses out loud and affirm them:

      +
        +
      • "GitHub is [response]" ✓
        • +
      • "Peer review is [response]" ✓
        • +
      • "I struggled with [thing] but figured it out" ✓✓✓ BIG CELEBRATION
        • +
      +

      0:20-0:30: Troubleshoot Stragglers

      +
      +

      "Anyone still stuck on Challenge 1 and want help?"

      +
      +

      Help them:

      +
        +
      • Offer to review their PR if Aria bot isn't responding
        • +
      • Give them a nudge in right direction
        • +
      • Or schedule 1:1 after call
        • +
      +

      0:30-0:35: Preview Day 2

      +
      +

      "Tomorrow we go deeper. Same process, harder challenges. You've got the skills now.

      +

      Here's what to expect:

      +
        +
      • Code review deep dive
        • +
      • Challenges 10-16 (progressively harder)
        • +
      • More peer collaboration
        • +
      • By the end, you'll have real skills
        • +
      +

      See you tomorrow at [time]!"

      +
      +

      0:35-0:45: Accessibility Check-In

      +
      +

      "Before you go: Did your screen reader work well the whole time? Any accessibility issues we should fix before tomorrow?"

      +
      +

      Listen and note anything that broke. Fix it that night if possible.

      +

      0:45-1:00: Optional Office Hours

      +
      +

      "We're staying on the call for office hours. If you want to:

      +
        +
      • Finish your first PR
        • +
      • Start Challenge 2
        • +
      • Ask follow-up questions
        • +
      +

      Stay online and we'll help!"

      +
      +

      Monitor chat and help individuals.

      +
      +

      Managing the Working Session Like a Pro

      +

      Energy Management

      +

      Every 60 minutes:

      +
        +
      • Announce: "Quick break everyone. Stand up, stretch, grab water. We'll resume in 5."
        • +
      • Facilitators: Actually take a break too
        • +
      • Mental check: Are you OK? Hydrated? Focused?
        • +
      +

      Every 120 minutes:

      +
        +
      • Celebrate progress: "Look at the dashboard! So many merges today!"
        • +
      • Remind students: "This is normal pace. Everyone's doing great."
        • +
      • Check co-facilitator: "How are you doing? Need to switch tasks?"
        • +
      +

      Dashboard Fatigue Prevention

      +

      Don't:

      +
        +
      • Stare at dashboard constantly (you'll miss chat questions)
        • +
      • Check every 1 minute (data doesn't change that fast)
        • +
      • Panic if someone is quiet (they might be concentrating)
        • +
      +

      Do:

      +
        +
      • Refresh every 5-10 minutes
        • +
      • Trust that bots are working
        • +
      • Pay attention to chat too (it's often where real help requests go)
        • +
      +

      When Students Help Students

      +

      This is great. When you notice:

      +
        +
      • "I see @student1 helping @student2 with merge conflicts!"
        • +
      +

      Publicly celebrate it:

      +
      +

      "@student1 — thank you for helping. That's exactly what real developer teams do."

      +
      +

      This reinforces the collaborative culture and takes pressure off you.

      +
      +

      Day 2 Operations (Similar Structure)

      +

      Key Differences from Day 1

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Day 1Day 2
      Intro focusSkill-building focus
      1 assignmentNew (2nd) assignment
      Challenges 1-9Challenges 10-16+
      Basic workflowComplex scenarios (merge conflicts, CLI, etc.)
      Lots of encouragementChallenge + celebrate
      +

      Day 2 Hour 1: Recap Opening

      +

      Pull Classroom dashboard (Day 1 assignment):

      +
      +

      "Yesterday, X of you joined and Y PRs were merged. Z of you kept working async.

      +

      You all know:

      +
        +
      • How to navigate GitHub
        • +
      • How to edit and create a PR
        • +
      • How to request a review and merge
        • +
      +

      That's real skills. Today we go deeper."

      +
      +

      Then: Share Day 2 assignment invite link

      +

      Day 2 Code Review Demo

      +

      This is YOUR demo, not the bot's:

      +
        +
      1. Open a student's Day 1 PR (with permission or use your test repo)
        2. +
      2. Narrate the review process:
          +
        • "Here's what I do when reviewing someone's code..."
          • +
        • "I read the description first..."
          • +
        • "Then I click 'Files changed'..."
          • +
        • "I think about: Is this right? Does it follow the rules? Is it clear?"
          • +
        • "I leave kind, specific feedback..."
          • +
        • "I either approve or ask for changes..."
          • +
        +
        3. +
      3. Have students practice in pairs reviewing each other's Day 1 PRs
        4. +
      +

      Day 2 Dashboard Monitoring

      +

      Same as Day 1, but looking for:

      +
        +
      • Students on Challenge 10+ (new territory)
        • +
      • Autograding failures (these get harder)
        • +
      • Merge conflicts (look for red flags in PR comments)
        • +
      • Students helping with complex problems
        • +
      +
      +

      Post-Workshop Operations

      +

      Immediately After (Last 15 min of Day 2)

      +
        +
      • Screenshot Classroom dashboard showing final stats
        • +
      • Note any broken automations or issues
        • +
      • Thank your co-facilitator
        • +
      • Send students a closing message
        • +
      +

      That Night (Day 3)

      +
        +
      • Export Classroom data (total PRs, students, completion rates)
        • +
      • Identify students still in progress (email: "Need any help finishing?")
        • +
      • Document what worked and what broke
        • +
      • Send thank you emails to co-facilitators and volunteers
        • +
      +

      Following Week

      +
        +
      • Send personalized email to each student
        • +
      • Invite them to alumni community
        • +
      • Offer 1:1 mentorship if interested
        • +
      • Update this guide with lessons learned
        • +
      +
      +

      Emergency Procedures Reference

      +

      If Aria Bot Stops

      +
        +
      1. Check GitHub status
        2. +
      2. Manually review PRs (use Aria's format)
        3. +
      3. Post in chat: "Brief delay with feedback bot, manually reviewing"
        4. +
      +

      If Student Repo Won't Create

      +
        +
      1. Check Classroom assignment published
        2. +
      2. Manually create repo in org using template
        3. +
      3. Share direct link with student
        4. +
      +

      If Your Voice Fails

      +
        +
      1. Use chat for all instructions
        2. +
      2. Have co-facilitator do vocal work
        3. +
      3. Use pre-recorded video if available
        4. +
      4. Type in chat for important messages
        5. +
      +

      If You Lose the Call

      +
        +
      1. Post in chat: "Video call dropped, reconnecting..."
        2. +
      2. Send email to all: "Continuing asynchronously"
        3. +
      3. Facilitate through chat/email until reconnected
        4. +
      +
      +

      Facilitator Self-Care

      +

      During the workshop:

      +
        +
      • Drink water
        • +
      • Stretch every 60 minutes
        • +
      • Answer questions but don't obsess
        • +
      • If co-facilitator is struggling, offer to swap tasks
        • +
      • Remember: You can't help everyone at once
        • +
      +

      After the workshop:

      +
        +
      • Take a break (don't immediately plan next cohort)
        • +
      • Celebrate what went well
        • +
      • Document issues objectively (not as failures)
        • +
      • Get feedback from co-facilitator
        • +
      +

      Before next cohort:

      +
        +
      • Update this guide based on lessons learned
        • +
      • Test automation fresh
        • +
      • Add your own notes and strategies
        • +
      • Build on what worked
        • +
      +
      +

      Last Updated: May 2026 | Version: 1.0 | Maintainer: Jeff Bishop

      + +
      + + + + diff --git a/html/admin/FACILITATOR_RESOURCES.html b/html/admin/FACILITATOR_RESOURCES.html new file mode 100644 index 0000000..7ef1145 --- /dev/null +++ b/html/admin/FACILITATOR_RESOURCES.html @@ -0,0 +1,378 @@ + + + + + + + Facilitator Resource Index - GIT Going with GitHub + + + + + + + + +
      +

      Facilitator Resource Index

      +

      Complete Guide to Running GitHub Classroom Workshops

      +

      Welcome, facilitator! This page helps you navigate all the documentation for running an accessible GitHub workshop for blind and low-vision students.

      +
      +

      🎯 Start Here Based on Your Situation

      +

      "I've Never Run This Workshop Before"

      +

      → Read in this order:

      +
        +
      1. FACILITATOR_GUIDE.md — GitHub Classroom Setup section
        2. +
      2. FACILITATOR_GUIDE.md — Pre-Workshop Checklist
        3. +
      3. FACILITATOR_OPERATIONS.md — For hands-on procedures
        4. +
      +

      "Workshop Is Tomorrow"

      +

      → Quick tasks:

      +
        +
      1. FACILITATOR_GUIDE.md — Pre-Workshop Checklist (all boxes)
        2. +
      2. FACILITATOR_OPERATIONS.md — 3-Hour Prep
        3. +
      3. FACILITATOR_OPERATIONS.md — Day-Of Checklist
        4. +
      +

      "Workshop Is Happening Right Now"

      +

      → Reference:

      + +

      "A Student Got Stuck"

      +

      → Go to:

      + +

      "Something Technical Broke"

      +

      → Check:

      + +

      "Workshop Just Ended, What's Next?"

      +

      → See:

      + +
      +

      📚 Complete Resource Reference

      +

      Primary Documents

      +

      FACILITATOR_GUIDE.md (33 KB)

      +

      The complete workshop bible. Everything from GitHub Classroom setup through post-workshop follow-up.

      +

      Main sections:

      +
        +
      • GitHub Classroom Setup (first-time setup)
        • +
      • Pre-Workshop Checklist (48 hours before)
        • +
      • Day 1 Live Operations (hour-by-hour)
        • +
      • Day 2 Live Operations (hour-by-hour)
        • +
      • Post-Workshop Tasks (week after)
        • +
      • Quick Troubleshooting Reference
        • +
      • Appendices (templates, keyboard shortcuts)
        • +
      +

      When to use:

      +
        +
      • First-time workshop setup
        • +
      • Planning a cohort
        • +
      • During workshop (overview reference)
        • +
      +
      +

      FACILITATOR_OPERATIONS.md (18 KB)

      +

      Real-time, hands-on procedures. Step-by-step what to do during each hour of the workshop.

      +

      Main sections:

      +
        +
      • Pre-Workshop Workstation Setup
        • +
      • Hour-by-Hour Procedures
        • +
      • Dashboard Monitoring Routines
        • +
      • Chat Response Templates
        • +
      • Emergency Procedures
        • +
      • Facilitator Self-Care
        • +
      +

      When to use:

      +
        +
      • During workshop (follow procedures hour-by-hour)
        • +
      • Preparing facilitator workstation
        • +
      • Real-time student support
        • +
      +
      +

      FACILITATOR_CLASSROOM_TROUBLESHOOTING.md (18 KB)

      +

      Problem-solving guide. Specific issues and their solutions.

      +

      Main sections:

      +
        +
      • Emergency Scenarios (bots down, video call broken, etc.)
        • +
      • Student-Level Issues (can't find repo, confused by feedback, etc.)
        • +
      • Specific Technical Scenarios (merge conflicts, autograder failures, etc.)
        • +
      • GitHub Platform Issues (GitHub down, Actions slow, etc.)
        • +
      • Facilitator Mistakes & Recovery
        • +
      • Prevention Strategies
        • +
      +

      When to use:

      +
        +
      • Something is broken and you need to fix it
        • +
      • Student is confused or stuck
        • +
      • Automation failed
        • +
      +
      +

      Supporting Documents

      +

      FACILITATOR_CHALLENGES.md (11.6 KB)

      +

      Operations guide for managing the challenge system and student progression during a live cohort.

      +

      Covers:

      +
        +
      • How the challenge system works
        • +
      • Monitoring student progress
        • +
      • Responding to help requests
        • +
      • Common issue patterns
        • +
      +

      When to use:

      +
        +
      • Understanding the challenge flow
        • +
      • Monitoring student progression
        • +
      • Identifying stuck students
        • +
      +
      +

      FACILITATOR_ASSESSMENT.md (0.4 KB)

      +

      Assessment rubric and grading guidance (brief reference).

      +

      Covers:

      +
        +
      • How to assess student work
        • +
      • What "success" looks like
        • +
      +

      When to use:

      +
        +
      • Providing meaningful feedback to students
        • +
      • Deciding if student meets learning goals
        • +
      +
      +

      🎓 Typical Workflow

      +

      Weeks 1-2 Before Workshop

      +
        +
      1. Read FACILITATOR_GUIDE.md GitHub Classroom Setup
        2. +
      2. Create your GitHub Classroom and assignments
        3. +
      3. Follow setup checklist in FACILITATOR_GUIDE.md
        4. +
      +

      48 Hours Before

      +
        +
      1. Complete FACILITATOR_GUIDE.md checklist
        2. +
      2. Test everything one more time
        3. +
      3. Read FACILITATOR_OPERATIONS.md overview
        4. +
      +

      Day Before

      +
        +
      1. Final checklist items
        2. +
      2. Setup workstation per FACILITATOR_OPERATIONS.md
        3. +
      3. Message co-facilitator: "Ready for tomorrow?"
        4. +
      +

      Day 1 During

      +
        +
      1. Follow FACILITATOR_OPERATIONS.md hour-by-hour
        2. +
      2. Keep FACILITATOR_CLASSROOM_TROUBLESHOOTING.md open in another tab
        3. +
      3. Reference FACILITATOR_GUIDE.md for overview
        4. +
      +

      Day 2 During

      +
        +
      1. Same as Day 1, but reference FACILITATOR_GUIDE.md Day 2 section
        2. +
      2. Be ready for harder scenarios and more independence from students
        3. +
      +

      After Workshop

      +
        +
      1. Follow FACILITATOR_GUIDE.md post-workshop tasks
        2. +
      2. Note what worked and what didn't
        3. +
      3. Update this guide for next time
        4. +
      +
      +

      🔧 How to Use These Documents

      +

      During Workshop: Have These Open

      +

      Browser tabs:

      +
        +
      1. FACILITATOR_OPERATIONS.md (current section)
        2. +
      2. FACILITATOR_CLASSROOM_TROUBLESHOOTING.md (troubleshooting reference)
        3. +
      3. Your GitHub Classroom dashboard
        4. +
      4. GitHub Discussions / chat with students
        5. +
      +

      Physical:

      + +

      Quick Reference: Keyboard Shortcuts

      +

      Jump to sections fast:

      +

      In your browser: Ctrl+F (or Cmd+F on Mac)

      +

      Then search for:

      +
        +
      • ### Hour — Jump to specific hour procedures
        • +
      • **Student Says** "... — Jump to chat response template
        • +
      • **Symptom:** ... → Jump to troubleshooting scenario
        • +
      +

      Getting Help

      +

      If you can't find something:

      +
        +
      1. Check "Start Here Based on Your Situation" above
        2. +
      2. Use browser search (Ctrl+F)
        3. +
      3. Check the table of contents in individual documents
        4. +
      4. Ask co-facilitator or post in team chat
        5. +
      +
      +

      📊 Document Overview at a Glance

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      DocumentPurposeLengthBest For
      FACILITATOR_GUIDE.mdComplete workshop bible33 KBPlanning, overview, templates
      FACILITATOR_OPERATIONS.mdHour-by-hour procedures18 KBDuring workshop, real-time decisions
      FACILITATOR_CLASSROOM_TROUBLESHOOTING.mdProblem-solving18 KBWhen things break or students stuck
      FACILITATOR_CHALLENGES.mdChallenge management11.6 KBUnderstanding progression system
      FACILITATOR_ASSESSMENT.mdGrading rubric0.4 KBQuick reference for assessment
      +
      +

      🎯 Key Principles Across All Documents

      +

      These principles appear repeatedly because they're that important:

      +
        +
      1. Accessibility First — Test with NVDA, JAWS, VoiceOver before every workshop
        2. +
      2. Async-Friendly — Students can join sync or async; both are valid
        3. +
      3. No Pressure — Fast pace and slow pace are both OK
        4. +
      4. Narrate Everything — Say what you're doing before you do it
        5. +
      5. Celebrate Effort — Not just finished work; recognition matters
        6. +
      6. Ask for Help — "I don't know but let's figure it out together" is OK
        7. +
      7. Community — Build an environment where students help each other
        8. +
      +
      +

      💡 Pro Tips from Experienced Facilitators

      +
        +
      • Bookmark the documents — You'll reference them constantly
        • +
      • Add your own notes — Margin notes about what worked for you
        • +
      • Screenshot the dashboard — Keep records of student progress
        • +
      • Keep student emails — Reference them when sending thank-yous
        • +
      • Document failures — So next time is easier
        • +
      • Celebrate publicly — Recognize achievements in real-time
        • +
      • Stay hydrated — Drink water throughout the day
        • +
      • Sync with co-facilitator — Check in every 60 minutes
        • +
      +
      +

      🚀 Related Resources

      +

      In this repository:

      + +

      External:

      + +
      +

      ✅ Pre-Workshop Sanity Check

      +

      Before your first workshop, verify:

      +
        +
      • I've read FACILITATOR_GUIDE.md GitHub Classroom Setup
        • +
      • I've created a test GitHub Classroom
        • +
      • I've accepted my own invite link
        • +
      • Aria bot commented on my test PR
        • +
      • Progression bot created Challenge 2 when I closed Challenge 1
        • +
      • I've read FACILITATOR_OPERATIONS.md procedures
        • +
      • I've set up my facilitator workstation per the guide
        • +
      • I've tested video call + audio dial-in
        • +
      • Co-facilitator has confirmed they're ready
        • +
      • I've reviewed FACILITATOR_CLASSROOM_TROUBLESHOOTING.md emergency section
        • +
      +

      If all checked: You're ready!

      +

      If any unchecked: That item is probably your next task. Don't skip it — it matters.

      +
      +

      📞 Questions or Feedback?

      +

      Found an error or unclear section? Help improve this guide:

      +
        +
      1. Make a note of what confused you
        2. +
      2. After the workshop, update the relevant document
        3. +
      3. Tag it with what you learned
        4. +
      4. Share with next facilitator
        5. +
      +

      This guide evolves with each cohort. Your experience makes it better for the next facilitator.

      +
      +

      Last Updated: May 2026 | Maintainer: Jeff Bishop | Version: 2.0

      +

      Navigation: ← Back to Admin | View All Docs | Classroom Setup

      + +
      + + + + diff --git a/html/admin/FAQ.html b/html/admin/FAQ.html index eaf83be..ac37937 100644 --- a/html/admin/FAQ.html +++ b/html/admin/FAQ.html @@ -375,7 +375,7 @@

      Q: How do I recognize a merge con

      A: Git marks the conflicting sections with these markers:

      <<<<<<< HEAD
 Your changes
-=======
+=======
 Their changes
 >>>>>>> branch-name

      Your screen reader will read these markers as text. See Chapter 7 for how to interpret them.

      @@ -865,5 +865,6 @@

      Still Stuck?

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/admin/GITHUB_PROPOSAL.html b/html/admin/GITHUB_PROPOSAL.html index 9fea6b5..ad38c72 100644 --- a/html/admin/GITHUB_PROPOSAL.html +++ b/html/admin/GITHUB_PROPOSAL.html @@ -582,54 +582,54 @@

      Time Estimates for Facilitators

      Success Criteria & Metrics

      Learner Outcomes (Measurable)

        -
      • 100% of learners complete setup chapter successfully
        • -
      • 90%+ of learners complete at least one hands-on exercise
        • -
      • 80%+ of learners understand PR review process after Chapter 6
        • -
      • 70%+ of learners use agents in their workflows within 30 days
        • +
      • 100% of learners complete setup chapter successfully
        • +
      • 90%+ of learners complete at least one hands-on exercise
        • +
      • 80%+ of learners understand PR review process after Chapter 6
        • +
      • 70%+ of learners use agents in their workflows within 30 days
      • Satisfaction: Post-workshop survey shows 4.5+/5.0 average

      Organizational Outcomes

        -
      • Reduced onboarding time for new developers (5 hrs down from 20+ hrs of ad-hoc training)
        • -
      • More consistent issue templates across team repositories
        • -
      • Increased PR review quality (more complete feedback from reviewers)
        • -
      • Higher accessibility compliance (templates and workflows built-in accessibility checks)
        • +
      • Reduced onboarding time for new developers (5 hrs down from 20+ hrs of ad-hoc training)
        • +
      • More consistent issue templates across team repositories
        • +
      • Increased PR review quality (more complete feedback from reviewers)
        • +
      • Higher accessibility compliance (templates and workflows built-in accessibility checks)

      Accessibility Metrics

        -
      • 100% of templates tested with screen readers (NVDA, JAWS, VoiceOver)
        • -
      • WCAG 2.1 AA compliance verified for all guided workflows
        • -
      • Keyboard-only functionality tested on all exercises
        • -
      • Color contrast verified (4.5:1 minimum for all text)
        • +
      • 100% of templates tested with screen readers (NVDA, JAWS, VoiceOver)
        • +
      • WCAG 2.1 AA compliance verified for all guided workflows
        • +
      • Keyboard-only functionality tested on all exercises
        • +
      • Color contrast verified (4.5:1 minimum for all text)

      Phase 1: Finalize & Polish (1 week)

        -
      • Convert all Markdown to HTML for web deployment
        • -
      • Create landing page with learning path selector
        • -
      • Set up GitHub Pages or web server for hosting
        • -
      • Gather feedback from 5-10 pilot users
        • +
      • Convert all Markdown to HTML for web deployment
        • +
      • Create landing page with learning path selector
        • +
      • Set up GitHub Pages or web server for hosting
        • +
      • Gather feedback from 5-10 pilot users

      Phase 2: Pilot Program (2-3 weeks)

        -
      • Run 1-2 beta workshops with external participants
        • -
      • Collect feedback: What worked? What needs clarification?
        • -
      • Iterate based on learner feedback
        • -
      • Update exercises with common questions
        • +
      • Run 1-2 beta workshops with external participants
        • +
      • Collect feedback: What worked? What needs clarification?
        • +
      • Iterate based on learner feedback
        • +
      • Update exercises with common questions

      Phase 3: Public Release (1 month)

        -
      • Launch curriculum publicly (GitHub Pages, blog announcement)
        • -
      • Promote in GitHub education channels, open-source communities
        • -
      • Establish feedback/issue tracking for curriculum improvements
        • -
      • Plan first live workshop (in-person or virtual)
        • +
      • Launch curriculum publicly (GitHub Pages, blog announcement)
        • +
      • Promote in GitHub education channels, open-source communities
        • +
      • Establish feedback/issue tracking for curriculum improvements
        • +
      • Plan first live workshop (in-person or virtual)

      Phase 4: Long-Term Maintenance (Ongoing)

        -
      • Monitor GitHub API/UI changes; update curriculum as needed
        • -
      • Collect learner feedback quarterly
        • -
      • Rotate facilitators for fresh perspectives
        • -
      • Expand to additional topics (GitHub Security, GitHub Actions deep dive, etc.)
        • +
      • Monitor GitHub API/UI changes; update curriculum as needed
        • +
      • Collect learner feedback quarterly
        • +
      • Rotate facilitators for fresh perspectives
        • +
      • Expand to additional topics (GitHub Security, GitHub Actions deep dive, etc.)

      Why GitHub Should Support This

      1. Education Mission

      @@ -857,5 +857,6 @@

      Signature & Approval

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/admin/PODCASTS.html b/html/admin/PODCASTS.html index e149f3b..905ef21 100644 --- a/html/admin/PODCASTS.html +++ b/html/admin/PODCASTS.html @@ -60,4516 +60,22561 @@

      Podcasts

      Git Going with GitHub - Audio Series

      -
      -

      Architecture update (May 2026): Some episodes (notably Episode 4: The Learning Room) were recorded under the original "single shared learning-room repository" model. The workshop has since moved to a GitHub Classroom model where each participant gets their own private copy of learning-room-template. The high-level concepts (PR-driven practice, automated bot feedback, peer review) are still accurate. The bot is now called Aria, and your Learning Room repo is private to you. Refer to the live chapters in docs/ for the current architecture; the audio remains a useful conceptual overview.

      -
      -

      Listen to companion audio episodes for every chapter and appendix in this workshop. Each episode is a conversational overview between hosts Alex and Jamie that previews or reviews the key concepts - perfect for learning on the go or reducing screen reader fatigue. Every episode includes a full transcript below the player.

      +

      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 preview the concepts. You will know what to expect before diving into the exercises.
        • -
      • After a chapter: Listen to reinforce what you learned and catch anything you missed.
        • +
      • 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

      - - -

      Download Episode 0 (MP3)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 0: Welcome to Git Going with GitHub

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is episode zero, titled Welcome to Gitt Going with GitHub. I am your host, Alex, and I am thrilled to be starting this journey with you. Whether you are a seasoned programmer who is just now moving over to GitHub, or you are completely new to version control, this audio series is designed to be your companion. We are going to explore open source collaboration using GitHub, Visual Studio Code, and GitHub Copilot, all with a strict focus on screen reader and keyboard-only navigation.

      -

      Jamie: And I am Jamie! I am so excited to be here. I will be learning right alongside you, asking the questions, and probably sharing a few embarrassing stories from my own learning journey. Because let me tell you, I learned GitHub just two years ago, and I remember exactly how overwhelming it felt. When I first heard people throwing around words like clone, fork, and branch, I thought we were doing some weird mix of agriculture and science fiction.

      -

      Alex: That is a perfect description of how it sounds at first. And that is exactly why we are doing this. Before we dive into the deep end, we want to give you a map of the territory. This episode is an overview of the entire two-day workshop. We are going to talk about what open source actually means, how this course is structured, the philosophy behind how we teach, and we will preview some of the core vocabulary you will be using every single day.

      -

      Jamie: But before we get into all of that, a quick public service announcement. If you are listening to this and you have not yet completed Chapter 0, which is the Pre-Workshop Setup, you will want to navigate to that chapter and complete it before Day 1 officially begins. It takes about thirty minutes. It walks you through creating your GitHub account, installing Git, setting up VS Code, and configuring your screen reader specifically for GitHub.

      -

      Alex: Exactly. Getting your environment set up correctly is half the battle. Once your screen reader is optimized for the web interface, everything else flows much more smoothly. So, let us start with the big picture. The entire goal of this workshop is built around one single idea. By the end of these two days, you will make real contributions to a real open source project. Not a simulated sandbox. Not pretend. Real open source.

      -

      Jamie: Which brings up a great question. For someone entirely new to this space, what exactly does open source mean, and why does it matter so much?

      -

      Alex: Open source refers to software where the original source code is made freely available. Anyone can navigate to the code, read it, modify it, and distribute it. But more importantly, open source is a collaborative community. It is a way of building software where thousands of people from all over the world work together to solve problems, rather than one closed-off team in a single company.

      -

      Jamie: I always like to think of open source as a massive community potluck dinner. Someone brings the main dish, which is the core software. But then someone else says, hey, this needs salt, and they add a new feature. Someone else brings dessert, which might be a documentation update. And someone else fixes the wobbly table, which is a bug fix. Anyone is allowed to walk into the room, taste the food, and contribute their own recipe to make the whole meal better for everyone.

      -

      Alex: I love that analogy. And what makes GitHub so powerful is that it provides the kitchen, the tables, and the recipe cards for that potluck. GitHub is the platform where millions of these open source projects live. It matters because much of the modern internet, including the tools we use for accessibility, runs on open source software. When you learn how to contribute, you get a voice in how the software you use every day is built.

      -

      Jamie: Okay, so we are going to be cooking at the open source potluck. How exactly are we going to learn all of this in just two days?

      -

      Alex: We divide the workshop into two distinct phases. Day 1 is all about GitHub Foundations in the browser. You will learn the GitHub web interface using only your keyboard and your screen reader. We will not touch a command line. We will not open a desktop application. You will learn how to navigate projects, find issues, propose changes, and review other people's work, entirely through the GitHub website.

      -

      Jamie: And I really appreciate this approach. When I started two years ago, I tried to learn the command line, the website, and the code editor all on the same day. It was a disaster. I did not know which program was throwing an error, or what the error even meant.

      -

      Alex: That is incredibly common, and it is the reason for our core learning philosophy in this workshop. We believe you must learn the manual skill first, before you introduce automation. If you try to use advanced tools before you understand what they are doing behind the scenes, you will get lost the moment something goes wrong. By spending all of Day 1 in the browser, you build a mental model of how GitHub is structured. You learn the concepts deeply.

      -

      Jamie: So Day 1 is building the foundation. What happens on Day 2?

      -

      Alex: Day 2 is when we move to the desktop. We transition into Visual Studio Code, which we often just call VS Code. This is a powerful, accessible code editor. Once we are in VS Code, we introduce GitHub Copilot, which is an artificial intelligence coding assistant, and we activate the Accessibility Agents ecosystem.

      -

      Jamie: Okay, hold on. Accessibility Agents? That sounds like something out of a spy movie. What are they?

      -

      Alex: They do sound a bit like secret agents. On Day 2, you will be introduced to a system of fifty-five accessibility agents working across three different teams. These agents are AI assistants configured specifically to help with accessibility tasks. For example, one team of agents acts as your daily briefing and issue tracking squad. They can summarize what happened in a project overnight so your screen reader does not have to read through fifty individual comments. Another team focuses on pull request reviews, helping you spot missing alternative text or improper heading structures in code before you submit it.

      -

      Jamie: Oh, that is clever! It is like having a team of expert accessibility consultants sitting in the room with you, ready to review your work or summarize long threads.

      -

      Alex: Exactly. But again, tying back to our philosophy, these agents only make sense if you already know what an issue or a pull request is. If you do not know how to manually review code, the agent's advice will not mean anything to you. That is why Day 2 is all about taking the manual skills you mastered on Day 1 and amplifying them with these fifty-five agents. By the end of Day 2, you will use these tools to ship a real contribution, and your name will be permanently recorded in the commit history of an open source project.

      -

      Jamie: Alex, you just used a few terms that I want to make sure we define, because I remember being so confused by them. We have an entire glossary in Appendix A, but can we do a high-level preview of the core vocabulary right now? Let us start with Repository.

      -

      Alex: Absolutely. A repository, or repo for short, is the container for an entire project. It holds all the files, the folders, the documentation, and, most importantly, the complete history of every change ever made.

      -

      Jamie: I remember someone telling me a repository is just a folder. But it is more than that, right?

      -

      Alex: It is much more than that. Think of a repository as a project folder that has a time machine built into it. Because it tracks every single modification, you can ask the repository to show you exactly what the project looked like last Tuesday at noon, or who added a specific line of code three years ago. It never forgets.

      -

      Jamie: Okay, next term. What is an Issue?

      -

      Alex: An issue is essentially a discussion item within a repository. If you find a bug, you open an issue to report it. If you want to request a new feature, you open an issue.

      -

      Jamie: So it is like a digital to-do list combined with a discussion forum. When I want to fix something, I navigate to the Issues section, find one that sounds interesting, and announce that I am going to work on it.

      -

      Alex: That is exactly right. Issues are the starting point for almost all open source work. Now, once you have done the work and fixed the bug, you need a way to give that fix back to the project. That brings us to our third core term, the Pull Request.

      -

      Jamie: Ah, the famous PR. I used to hear people say, just submit a PR, and I would nod and pretend I knew what they meant.

      -

      Alex: A pull request, or PR, is a formal proposal to combine your changes into the main project. And I love that name, because you are literally requesting that the maintainer pull your changes into their repository. You are saying, here is the work I did to fix that issue, please review it.

      -

      Jamie: My favorite analogy for a pull request is publishing a book. Imagine the repository is the official, published book. You cannot just grab a pen and write your own paragraph directly onto the printed pages for everyone in the world to see. Instead, you write your changes on a separate piece of paper, which is your draft. A pull request is you handing that piece of paper to the editor and saying, I think this paragraph makes the book better. What do you think?

      -

      Alex: That is a brilliant comparison. And the editor, who in our world is called the project maintainer, will read your draft. They might leave comments asking you to change a sentence, or fix a typo. This is the code review process. You update your draft based on their feedback. And finally, when the editor is happy with it, they perform the fourth core concept, the Merge.

      -

      Jamie: And a merge is when the editor takes your piece of paper, types it into the official manuscript, and publishes it for real.

      -

      Alex: Exactly. Merging is the act of combining your approved pull request into the main repository. Once it is merged, your code is officially part of the project. So, to recap the lifecycle. You find a problem in a Repository. You discuss it in an Issue. You propose a solution with a Pull Request. And the maintainer accepts it with a Merge.

      -

      Jamie: Okay, that sounds like a lot of steps. And if I am being honest, thinking about doing all of this, plus moving over to VS Code on Day 2, feels a little intimidating. Especially for folks who might be totally new to the command line, or new to using version control.

      -

      Alex: It does sound like a lot! But here is the thing. You have already done most of this on Day 1 in the browser. You already know the workflow. When we move to VS Code, it is the exact same workflow, just with VS Code handling the heavy lifting. We are going to take it one step at a time.

      -

      Jamie: And there is actually a really cool bridge between Day 1 and Day 2, right? The period key trick. I wish I had known that when I started.

      -

      Alex: It is one of my favorite features on GitHub. When you are on any repository page in your browser, if you simply press the period key on your keyboard, GitHub will instantly open a web-based version of VS Code right there in your browser tab. It is called GitHub dot dev. You do not have to install anything. It uses the exact same screen reader mode and keyboard shortcuts as the desktop version. It is the perfect stepping stone. You get to feel what a code editor is like, but you are still in the safety of your web browser.

      -

      Jamie: That is amazing. You can literally just press period, and suddenly you are in an accessible editor.

      -

      Alex: Yes. And we deliberately designed this workshop so that you are never thrown into the deep end without a life vest. Every single chapter builds on the one right before it. If you look at the course guide, you will notice we have structured the materials very specifically. There are chapters, and there are appendices.

      -

      Jamie: How should we be using those? Should I read the appendices before I start the exercises?

      -

      Alex: No, please do not try to read the appendices straight through! The chapters, numbered one through sixteen, are your main journey. They are designed to be read and practiced in order. The appendices, labeled with letters like Appendix A for the Glossary, or Appendix B for the Screen Reader Cheat Sheet, are purely reference materials. You keep them open in a separate tab or window. When you encounter a term you do not know, or you forget a screen reader command, you navigate to the appendix, find what you need, and then jump right back into the chapter.

      -

      Jamie: That takes a lot of pressure off. I do not have to memorize every single command before I start. I can just look them up as I go.

      -

      Alex: Exactly. Memorization is not the goal. Navigation and confidence are the goals. And to build that confidence, we have included twenty-four structured exercises throughout the curriculum.

      -

      Jamie: I love the exercises in this course. They are so bite-sized. Can you explain the pattern we use for them?

      -

      Alex: Every single exercise follows the exact same three-part pattern. First is the Try It section, which gives you clear, step-by-step instructions on what to do. Second is the You Are Done When section. This tells you the specific outcome you are looking for, so there is no guessing about whether you finished it correctly. Finally, there is the What Success Feels Like section. This is incredibly important for screen reader users. We describe exactly what you should hear, or where your focus should land, when the task is completed successfully.

      -

      Jamie: That is so helpful. I remember reading tutorials that would just say, click the button and you are done. And I would press enter on a button, and my screen reader would say nothing, and I had no idea if it actually worked. Knowing what success feels like is a game changer.

      -

      Alex: It really is. Let me give you an example. In Chapter One, there is an exercise called the Sixty Second Orientation. The Try It section asks you to navigate to a repository page, and press a sequence of keyboard shortcuts. Press the number 1 key, then the letter D, then the number 2 key, then the letter H. The You Are Done When section says you have successfully navigated between the main content, the repository details, and the file list. And the What Success Feels Like section explains the specific auditory feedback you will get from your screen reader as you jump between those landmarks. Every exercise takes between one and five minutes, and they are designed to be impossible to fail. They are just stepping stones.

      -

      Jamie: I am feeling so much better about this. But what if I do get stuck? What if my screen reader starts reading a wall of text, or I press the wrong shortcut and suddenly I am in a completely different view?

      -

      Alex: First, take a breath. Getting lost is a normal part of learning a complex interface. If you get stuck, we have a whole section in the guide called Getting Help. You can reference the Troubleshooting guide, which has step-by-step solutions to common screen reader focus issues. You can check the Quick Reference guide for shortcuts. And if you are truly stuck, you can actually open an issue in the workshop repository itself! You will describe what you tried, what happened, and what you expected to happen. It is a safe environment to practice asking for help the open source way.

      -

      Jamie: I really appreciate that. It normalizes getting stuck. When I first started, I thought getting an error meant I was bad at programming. Now I know that getting errors just means I am programming.

      -

      Alex: That is a fantastic way to look at it. Professional developers get errors all day long. The difference is just that they have built up the muscle memory of how to recover from them. And that is exactly the muscle memory we are going to build over these two days.

      -

      Jamie: So, as we wrap up this introductory episode, what are the biggest takeaways we should keep in mind before we jump into Chapter One?

      -

      Alex: I would say there are four main takeaways. Number one, remember our philosophy. We learn the manual skill first, then we automate it. Do not rush to the fancy tools until you understand the basic concepts. Number two, lean heavily on your reference materials. Keep the Glossary and the Screen Reader Cheat Sheet open in another tab. Number three, trust the exercise pattern. Focus on what success feels like, and take it one small step at a time.

      -

      Jamie: And number four, be kind to yourself. You are learning a new language, a new platform, and a new way of collaborating all at once. If it feels like a lot, that is because it is a lot. But you are going to do great.

      -

      Alex: Well said, Jamie. Up next in episode one, we are going to dive into Chapter One, Understanding GitHub's Web Structure. We will explore how GitHub organizes its pages, how to orient yourself using headings and landmarks, and how to make your screen reader glide through the interface. We will see you there!

      +

      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 when you already understand what they are doing. 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 You Begin. Start with Get Going with GitHub if you want the most guided path. Put another way, 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.

      +

      Alex: Here is what that changes in practice. Creating a GitHub account. Installing Git. Setting up VS Code (optional for Day 1, required for Day 2). Configuring your screen reader for GitHub.

      +

      Alex: This is where the talk moves from concept to action. This is where Companion Audio Series becomes real: the audio track is a standalone teaching companion for the same concepts. That matters in practice: Use the episode whenever audio helps you enter or revisit the topic.

      +

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

      +

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      +

      Alex: Keep the learner anchored in Day 1: GitHub Foundations. These chapters are designed to be read and practiced in order. This is the part to say slowly: 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.

      +
      +

      Alex: Before the learner moves on. The reason Day 2: VS Code + Accessibility Agents matters is that day 2 moves you from the browser to the desktop. That gives the learner a simple foothold: every skill maps directly to what you learned on Day 1. 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 Appendices - Reference Material: Open these at any time during the workshop. The next useful detail is this: They are not part of the chapter sequence - use them when you need them.

      +

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

      +

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

      +
      +

      Alex: Here is the practical turn. Start with Step 1 - Know Your Starting Place: Before Day 1 starts, complete Chapter 00: Pre-Workshop Setup. The next useful detail is this: 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.

      +

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

      +

      Alex: Here is the plain-English version of Step 2 - Accept the GitHub Classroom Assignment. At the start of Day 1, the facilitator gives you a GitHub Classroom assignment link. Put another way, it usually starts with https://classroom.github.com/a/.

      +

      Alex: First, open the assignment link in the browser where you are signed in to GitHub. Then, if GitHub asks you to authorize GitHub Classroom, activate Authorize GitHub Classroom. After that, 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. Finally, activate Accept this assignment. 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, wait while GitHub Classroom creates your private repository. Then, refresh the page until the repository link appears. After that, open the repository link and bookmark it. 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 Step 3 - Understand the Learning Room becomes real: the Learning Room is a private repository created from a template. That matters in practice: Everyone starts from the same materials, but your work belongs to you. 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. 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.

      +
      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in Step 4 - Find Challenge 1. After your Learning Room repository is created, the Student Progression Bot creates your first challenge issue. This is the part to say slowly: When you close a challenge issue, the next challenge opens.

      +

      Alex: First, open your Learning Room repository. Then, navigate to the Issues tab. On GitHub, the keyboard shortcut is G then I. After that, find an issue titled Challenge 1: Find Your Way Around. Finally, open the issue and read the body from top to bottom. 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, follow the checklist in the issue. Then, post your evidence in the evidence field or as the requested comment. After that, close the challenge issue when the instructions tell you to close it. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Another way to ground it. The reason Step 5 - Choose the Tool That Fits the Moment matters is that there is no single correct way to use GitHub. That gives the learner a simple foothold: the workshop teaches the workflow first, then offers tool paths.

      +

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

      +

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

      +

      Alex: Start with Step 6 - What to Listen For with a Screen Reader: When you feel lost, listen for structure before you take action. The next useful detail is this: If you are not sure where you are, pause and navigate by headings or landmarks.

      +

      Alex: A few details make that real. Page title. Repository name heading. Landmark names such as main content or repository navigation. Tab names such as Code, Issues, and Pull requests.

      +

      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 the part worth saying out loud. Here is the plain-English version of Step 7 - Use the Support Built into the Course. If something does not work, do not start over silently. Put another way, read the latest bot message, check the challenge issue, and ask for help with the link to the page where you are stuck. It 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. 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.

      +

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

      +

      Alex: This is where Step 8 - Your First Success Check becomes real: you are ready to continue when you can say these four things. That matters in practice: You do not need to understand every GitHub feature before you begin.

      +

      Alex: First, I can open my Learning Room repository. Then, I can find the Issues tab. After that, I can open Challenge 1. Finally, I know where to post my evidence and how to ask for help. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

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

      +

      Alex: Keep the learner anchored in Where to Go Next. Use this order if you want the gentlest path. This is the part to say slowly: We will keep the path explicit, and we will keep giving you the next step.

      +

      Alex: First, chapter 00: Pre-Workshop Setup. Then, chapter 01: Choose Your Tools. After that, chapter 02: Understanding GitHub. Finally, chapter 03: Navigating Repositories. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Where to Go Next, what is the practical point?

      +

      Alex: First, chapter 04: The Learning Room. Then, your Challenge 1: Find Your Way Around issue in your Learning Room repository. 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 0. Next in the series is episode 1, where we keep building the same contributor muscles.

      - +

      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

      - - -

      Download Episode 1 (MP3)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 1: Pre-Workshop Setup

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is episode one, titled Pre-Workshop Setup. I am your host, Alex, and I am here with my co-host, Jamie. In this audio series, we are going to guide you through learning GitHub, version control, and open source collaboration, specifically designed for developers who use screen readers or magnification.

      -

      Jamie: Hi everyone. I am so excited to be here. I actually took this exact workshop about two years ago. I remember exactly what it feels like to hear all these new terms thrown around and feel completely overwhelmed. So I am here to ask Alex all the questions that are probably running through your head right now.

      -

      Alex: And those questions are exactly what we want. Today, our goal is to get your computer, your browser, and your screen reader completely set up and verified before day one of the workshop even begins. We will cover creating a GitHub account, understanding the difference between Git and GitHub, installing Visual Studio Code, turning on some essential accessibility settings, and verifying that everything works.

      -

      Jamie: Okay, that sounds like a lot of steps.

      -

      Alex: It does! But here is the thing, you have already done most of this on Day One of any new job or project. It is the exact same workflow, just with some new tools. Once we get the foundation set up today, the rest of the workshop is just learning how to use it.

      -

      Alex: Let us start with the biggest question people usually have. What is the difference between Git and GitHub? They sound like the same thing, but they serve two very completely different purposes.

      -

      Jamie: This confused me so much when I started. I thought GitHub was just the company that made Git.

      -

      Alex: That is a very common misconception. Let us break it down. Git is a version control system. Version control is basically a system that records changes to a file or set of files over time so that you can recall specific versions later. Think of Git as a time machine for your code. It runs locally on your computer. When you make a mistake, Git allows you to roll back your files to exactly how they were yesterday, or last week.

      -

      Jamie: So if Git is the time machine running on my local laptop, what is GitHub?

      -

      Alex: GitHub is a hosting platform for collaboration. If Git is your personal camera saving photos to your hard drive, GitHub is the social media platform where you upload those albums so your friends can see them, comment on them, and add their own photos. GitHub lives on the web. It takes the code you manage locally with Git and gives you a place to share it, review it, and collaborate with developers all over the world.

      -

      Jamie: That makes sense. Git is the local engine, and GitHub is the collaborative cloud platform. Which means to participate in the workshop, we need an account on that cloud platform.

      -

      Alex: Exactly. Step one is creating your GitHub account. You will navigate your browser to github dot com slash signup. The signup process is a single-page form. It will ask for your email address, a password, and a username.

      -

      Jamie: Let us talk about usernames for a second. Your GitHub username is public. It is going to appear on every piece of code you submit, every comment you make, and every project you contribute to.

      -

      Alex: Right. Keep it professional. It represents you in the open source community. You can only use lowercase letters, numbers, and hyphens.

      -

      Jamie: And we should warn people about the human verification step. When I signed up, I got completely stuck here because the default puzzle is highly visual.

      -

      Alex: I am really glad you brought that up. GitHub uses a visual capture puzzle to verify you are human, which is a known accessibility barrier. When your screen reader reaches that part of the form, you need to navigate to the button labeled Try an audio challenge. Activate that button. You will hear a short audio clip of spoken words or digits, and you will type what you hear into the text field. If that audio challenge does not load or fails, do not panic. Reach out to the workshop organizers and they can manually help verify your account.

      -

      Alex: Once your account is created, GitHub will send a launch code to your email. You copy that code, paste it into the browser, and you are in. But before we do anything else, we need to talk about security. Specifically, Two-Factor Authentication, or as you will often hear it called, two F A.

      -

      Jamie: I know a lot of people groan when they hear two F A, but it is actually required by most major open source projects now, right?

      -

      Alex: It is. Two-factor authentication means that to sign into your account, you need two things. First, something you know, which is your password. Second, something you have, like a code from an app on your phone. Think of it like withdrawing money from an ATM. You need your physical debit card, which is the thing you have, and your PIN, which is the thing you know. If a hacker steals your password, they still cannot get into your GitHub account without that second factor.

      -

      Jamie: So how do we set this up accessibly?

      -

      Alex: You will navigate to your account settings, move to the Password and authentication section, and activate the Enable two-factor authentication button. GitHub gives you a few options. The most common is an authenticator app, like Microsoft Authenticator or Google Authenticator.

      -

      Jamie: For screen reader users, scanning a visual QR code on the screen with a phone camera can be really frustrating.

      -

      Alex: Yes it can. And that is why you should navigate past the QR code graphic and activate the link that says enter this text code. That will reveal a long text string called a setup key. You just copy that text string and paste it into the manual entry field of your authenticator app.

      -

      Jamie: Okay, so I have two F A turned on. I am secure. But wait, if I am using Git on my laptop terminal to send code up to GitHub, how does my terminal know my second factor code?

      -

      Alex: That is a brilliant question. When you have two F A enabled, you can no longer use your standard GitHub password on the command line. Git will reject it. Instead, you need to use either a Personal Access Token, or an S S H key.

      -

      Jamie: Okay, define those for me.

      -

      Alex: Let us start with a Personal Access Token, often called a PAT. A PAT is a long, randomly generated string of characters that GitHub creates for you. You use it exactly like a password when Git asks for one. But unlike your main password, a PAT can be scoped.

      -

      Jamie: Scaped meaning limited?

      -

      Alex: Exactly. Think of your main GitHub password like the master key to your house. It opens every door. A Personal Access Token is like a valet key you give to a parking attendant. It only starts the ignition, but it will not unlock the glove box or the trunk. You can create a PAT that only has permission to read and write code repositories, but cannot delete your account or change your billing settings. And you can set it to automatically expire after thirty days.

      -

      Jamie: That is really smart. And what about the other option you mentioned, S S H keys?

      -

      Alex: S S H stands for Secure Shell. An S S H key is actually a pair of files generated on your computer. One is private, which stays securely on your hard drive, and one is public, which you upload to GitHub. Once they are linked, your computer and GitHub recognize each other automatically. No passwords or tokens to type ever again.

      -

      Jamie: I use S S H keys now and I love them, but I will say, generating them in the terminal was a bit intimidating on my first day.

      -

      Alex: Which is exactly why, for this workshop, we recommend starting with a Personal Access Token. It is entirely web-based, highly accessible to set up in the browser, and you just paste it into your credential manager once.

      -

      Alex: Now that we are authenticated, we need to adjust a few critical settings in the GitHub web interface. There is a dedicated Accessibility Settings page. You can reach it by opening the user navigation menu in the top right corner, selecting Settings, and then navigating to Accessibility in the left sidebar.

      -

      Jamie: If listeners only take one thing away from this episode, let it be this next setting. Please, for your own sanity, disable Hovercards.

      -

      Alex: I completely agree. A hovercard is a small pop-up window that appears when you move focus to a user's name or a repository link. It is meant to provide quick context. But for screen reader users, it is incredibly disruptive.

      -

      Jamie: It is the worst. When I had it turned on, every single time I tabbed past a link, my screen reader would start reading a massive paragraph of metadata, and then announce the keyboard shortcut to open the card. It was like having a tour guide who interrupts you every time you walk past a painting to read you the entire Wikipedia article about the artist, while you are just trying to find the restroom.

      -

      Alex: That is the perfect analogy. So, on the Accessibility Settings page, navigate to the checkbox labeled Hovercards or Link Previews, and uncheck it. It saves automatically. While you are on that page, we also recommend checking the box for Link underlines. This forces all links on GitHub to have a solid underline, which is incredibly helpful for low-vision users who might struggle to distinguish links by color alone.

      -

      Jamie: Are there any other settings we need to change?

      -

      Alex: Yes, we need to check your Feature Previews. GitHub is constantly improving its interface, and they let users opt into new designs before they become the default. Open the user menu again and activate Feature Preview. You are looking for two specific items. The New Issues Experience, and the New Files Changed Experience.

      -

      Jamie: What do those do?

      -

      Alex: The New Issues Experience completely rebuilds how issue lists are structured. It adds proper heading levels, accessible list structures, and live regions so your screen reader announces when you apply a filter. The New Files Changed Experience does the same thing for code reviews, adding a navigable file tree and turning visual code comparisons into structured tables.

      -

      Jamie: So basically, they make everything we are going to do in the workshop actually accessible.

      -

      Alex: Exactly. If you find them in the Feature Preview list, activate the Enable button for both. If you do not see them in the list at all, do not worry. That just means GitHub has already made them the default for everyone, and you are good to go.

      -

      Alex: Alright, our GitHub account is ready. Now we need to set up our local computer. That means installing Git, and installing our code editor.

      -

      Jamie: Let us start with Git. How do we get that time machine onto our laptop?

      -

      Alex: It depends on your operating system. If you are on Windows, you will navigate to git dash s c m dot com, download the Git for Windows installer, and run it. The default options are perfectly fine. If you are on a Mac, Git is often already there. You can open your Terminal application and type git space dash dash version. If it is not installed, the Mac will automatically pop up a dialog asking if you want to install the command line developer tools. Just agree to that. Linux users can install it using their standard package manager, like apt or dnf.

      -

      Jamie: Once it is installed, we have to introduce ourselves to Git, right? I remember this step. Configuring our Git identity.

      -

      Alex: That is right. Git embeds your name and your email address into every single snapshot, or commit, that you make. It needs to know who is making the changes. Think of it like signing the guestbook at an event. If you do not configure this, your commits might show up as authored by Unknown, which looks highly unprofessional, or Git might just refuse to save your changes entirely.

      -

      Jamie: How do we set that up?

      -

      Alex: You open your terminal and type two commands. The first is git space config space dash dash global space user dot name, followed by your full name in quotation marks. The second is git space config space dash dash global space user dot email, followed by the email address you used to sign up for GitHub.

      -

      Jamie: And a quick note here. The terminal is fully accessible. Whether you are using PowerShell on Windows with N V D A or JAWS, or the macOS Terminal with VoiceOver, you can read the output of your commands using your screen reader's review cursor or by simply arrowing up.

      -

      Alex: Now for the centerpiece of our local setup. Visual Studio Code, commonly called VS Code.

      -

      Jamie: This is the recommended editor for the workshop, right? Why do we use VS Code instead of something else?

      -

      Alex: VS Code is a free, open-source code editor built by Microsoft. We recommend it because its accessibility support is phenomenal. It has a dedicated team ensuring that screen readers can navigate complex codebases, interact with source control, and use artificial intelligence tools seamlessly. Think of VS Code as your digital workbench. It is where all your tools, your files, your terminal, and your version control live in one unified, accessible interface.

      -

      Jamie: You can download it at code dot visual studio dot com. The installer is standard. But once you open it, there is a very specific setting you have to turn on immediately.

      -

      Alex: Yes. Screen Reader Optimized Mode. This is absolutely critical. By default, VS Code renders text in a highly visual way that screen readers struggle to parse efficiently. When you turn on Screen Reader Optimized Mode, VS Code completely changes how it outputs information. It renders the editor as a plain text region so you can arrow through it linearly. It turns visual side-by-side code comparisons into readable text. And it enables audio cues, which are little sounds that play to indicate errors, folded code, or inline suggestions.

      -

      Jamie: How do we turn it on?

      -

      Alex: Often, VS Code will detect your screen reader on startup and present a dialog asking if you want to enable it. If it does, just press Enter to accept. If it does not, you can toggle it instantly by pressing Shift plus Alt plus F1.

      -

      Jamie: Or you can use the Command Palette, right? The Command Palette is my favorite feature. You press Control plus Shift plus P on Windows, or Command plus Shift plus P on Mac, and it opens a search box where you can type any command. Just type screen reader, and you will find the toggle.

      -

      Alex: Exactly. Once your screen reader mode is on, we need to install two extensions. Extensions are like adding new power tools to your workbench. They give VS Code new capabilities. You open the Extensions view by pressing Control plus Shift plus X, and search for the ones we need.

      -

      Jamie: The first one is the GitHub Pull Requests extension. What does that do?

      -

      Alex: A pull request is a request to merge your code changes into a main project. We will cover them deeply later. This extension allows you to review code, read comments, and manage pull requests entirely inside VS Code, without ever having to switch back to your web browser.

      -

      Jamie: And the second extension is GitHub Copilot Chat.

      -

      Alex: Yes. Copilot is an artificial intelligence pair programmer. The Copilot Chat extension gives you a conversational interface right in your editor. You can press Control plus Shift plus I to open the chat, and ask it questions like, how do I undo my last Git commit? Or, can you explain what this Python function does? It will read the code you currently have focused and give you plain text answers. It is fully accessible and incredibly helpful when you are learning.

      -

      Jamie: And Copilot has a free tier now, right?

      -

      Alex: It does. Copilot Free is available to all GitHub users. It gives you a limited number of chat messages and code completions per month, which is more than enough for this workshop. You just need to sign into your GitHub account inside VS Code to activate it.

      -

      Jamie: Alex, before we wrap up, I want to ask about something I heard some developers talking about. What if I am on a computer where I cannot install Git or VS Code? Like a library computer or a strict corporate laptop. Am I just locked out of contributing?

      -

      Alex: Not at all. This brings us to a fantastic feature called github dot dev. It is a completely browser-based alternative. If you are looking at any repository on GitHub dot com, you can simply press the period key on your keyboard.

      -

      Jamie: Wait, just the period key?

      -

      Alex: Just the period key. When you press it, the web page transforms into a lightweight version of VS Code, running entirely inside your browser. It looks and acts exactly like the VS Code you install on your desktop.

      -

      Jamie: That is amazing.

      -

      Alex: It really is. Think of it like a pop-up tent version of your digital workbench. You can take it anywhere, it requires absolutely zero installation, and because it is built on the same architecture as desktop VS Code, all the screen reader accessibility features still work. You can edit files, commit changes, and push them back to the repository without ever touching your local hard drive.

      -

      Jamie: I wish I had known about that trick when I started. Just press the period key. I love that.

      -

      Alex: It is incredibly handy for quick typo fixes or documentation updates. But for heavy development work, we still recommend the full desktop VS Code installation, because it gives you access to the local terminal and testing tools.

      -

      Alex: So, let us review our verification checklist before Day One. First, you have created your GitHub account, verified your email, and turned on Two-Factor Authentication.

      -

      Jamie: Second, you went into GitHub's Accessibility Settings, turned off the extremely noisy Hovercards, and turned on Link underlines.

      -

      Alex: Third, you installed Git, and configured your user dot name and user dot email in the terminal.

      -

      Jamie: Fourth, you installed Visual Studio Code, and immediately turned on Screen Reader Optimized Mode using Shift plus Alt plus F1.

      -

      Alex: And finally, you installed the GitHub Pull Requests and GitHub Copilot Chat extensions, and signed into your GitHub account inside the editor.

      -

      Jamie: If you can check all those boxes, you are completely ready for the workshop. But Alex, what if someone gets stuck on one of these steps? What if their terminal throws an error they do not understand, or their screen reader stops reading the editor?

      -

      Alex: Please do not suffer in silence. If you hit a roadblock, reach out to the workshop organizers immediately. You can file an issue on the Community Access repository, or send an email. We want to solve these setup quirks today. Every technical issue we fix before the workshop means more time for actual learning on Day One. You will not be left behind.

      -

      Jamie: This has been such a great overview. To summarize our key takeaways. Number one, Git is your local version control time machine, while GitHub is the web platform where you share and collaborate. Number two, disable Hovercards in your GitHub settings to keep your screen reader quiet and focused. Number three, always enable Screen Reader Optimized Mode in VS Code so your diffs and editor windows output clean, readable text.

      -

      Alex: Perfectly summarized. That brings us to the end of Episode One. Now that your tools are installed and configured, you are ready to start navigating. In Episode Two, we are going to dive into Understanding GitHub's Web Structure. We will explore how repository pages are laid out, which heading levels to jump to, and how to find exactly what you need without getting lost in the interface.

      -

      Jamie: I cannot wait. See you all in the next episode!

      -

      Alex: Thanks for listening to Gitt Going with GitHub. Keep practicing, and we will see you next time.

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 1: Pre-Workshop Setup. I am Alex, and today we are turning Pre-Workshop Setup 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: Creating your GitHub account, installing Git and VS Code, configuring your screen reader. 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 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.

      +

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

      +

      Alex: The practical anchors are these. A computer running Windows or macOS. A reliable internet connection. Headphones (recommended - screen reader audio during group sessions).

      +

      Jamie: What should feel predictable before the first live session starts?

      +

      Alex: Start with Software - Day 1. 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. 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).

      +
      +

      Alex: Now bring the learner back to the room. Start with Software - Required Before the Workshop. There is something to understand, something to try, and something that proves the try worked.

      +

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

      +

      Jamie: How should someone choose between those options?

      +

      Alex: The reason Screen Reader Options matters is that use whichever you are most comfortable with. That gives the learner a simple foothold: all workshop exercises are designed to work with any of these screen readers.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Screen Reader means Platform means Download. NVDA (NonVisual Desktop Access) means Download NVDA. JAWS (Job Access With Speech) means Paid (trial available) means Download JAWS.

      +

      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 Step 1 - Create Your GitHub Account: See also: Appendix D: Git Authentication covers SSH keys and personal access tokens in detail. The next useful detail is this: If you already have a GitHub account, skip to Step 2. 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: How would you walk the room through that step by step?

      +

      Alex: Here is the plain-English version of Create an account. GitHub presents a visual CAPTCHA puzzle to verify you are human. Put another way, follow the on-screen prompts - typically clicking images that match a category, or checking a box.

      +

      Alex: Here is what that changes in practice. Type your email address and press Tab or activate Continue. Choose a password of at least 8 characters (15+ recommended). Press Tab or Continue. Your username appears on every issue, PR, and comment you make. Guidelines. Use lowercase letters, numbers, and hyphens only.

      +

      Alex: First, open your browser and navigate to the GitHub signup page. Then, the page loads with focus on the first field: "Enter your email address". After that, the next field is "Create a password". Finally, the next field is "Enter a username". 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 next question asks whether you want to receive product updates by email. Then, human verification step. After that, activate the Create account button. Finally, GitHub sends a launch code (a short numeric code) to your email inbox. 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 Verify your email address becomes real: GitHub also sends a separate email verification link after account creation. That matters in practice: Check your inbox for an email from GitHub with subject "Please verify your email address" and activate the link inside it.

      +

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      +

      Alex: Keep the learner anchored in 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. This is the part to say slowly: GitHub now requires 2FA for all accounts, so you may already have it enabled.

      +
      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with Quick steps to enable 2FA. 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 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. 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.

      +

      Alex: First, open the GitHub security settings page while signed in. Then, under Two-factor authentication, choose Enable and follow the prompts. After that, choose one of the second-factor methods (recommended order). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Start with Detailed setup notes. There is something to understand, something to try, and something that proves the try worked.

      +

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

      +

      Alex: Hold that next to this. Start with Recovery and backup. 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. 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.

      +
      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: This is where Authenticating Git with GitHub: browser-based sign-in (OAuth) becomes real: when you use Git inside VS Code or GitHub Desktop, you do not need to manage passwords, tokens, or SSH keys manually. That matters in practice: These tools use browser-based OAuth sign-in - the same "Sign in with GitHub" flow you use on any website.

      +

      Alex: First, the first time you push or pull code, VS Code (or GitHub Desktop) opens your default web browser to a GitHub authorization page. Then, 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). After that, approve the authorization request. Finally, 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. 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.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Workshop policy. For this workshop, participants need a GitHub account with 2FA enabled. This is the part to say slowly: The browser-based sign-in described above handles all Git authentication automatically - no additional setup is required beyond having a working GitHub account. 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 Learning Cards: Create Your GitHub 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. 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. 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.

      +
      +

      Alex: Here is the practical turn. Start with Step 2 - Configure GitHub Accessibility Settings: These settings make GitHub significantly more usable with a screen reader. The next useful detail is this: Do not skip this section - one setting in particular (hovercards) adds significant noise to every page if left on.

      +

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

      +

      Alex: Here is the plain-English version of Navigate to Accessibility Settings. The fastest path for everyone: navigate directly to GitHub Accessibility Settings while signed in. Put another way, if you prefer to navigate through the interface.

      +

      Alex: First, click your profile picture (avatar) in the top-right corner of any GitHub page. Then, a dropdown menu appears - click Settings. After that, on the Settings page, scroll the left sidebar and click Accessibility. Finally, 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). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

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

      +

      Alex: First, press B repeatedly until you hear "Open user navigation menu, button" (top-right of the page) and press Enter. Then, navigate the menu with ↓ or K until you hear "Settings" and press Enter. After that, on the Settings page, press D to move through landmark regions until you reach the left sidebar navigation. Finally, press K or ↓ to navigate through sidebar links until you hear "Accessibility" and press Enter. 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 Settings to configure becomes real: all are on the Accessibility settings page unless noted. 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 1. Disable Hovercards (highest priority). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 1. Disable Hovercards (highest priority). Hovercards are the most disruptive default setting for screen reader users on GitHub. This is the part to say slowly: When enabled, every link announces its hover keyboard shortcut (H) as you navigate past it, dramatically slowing page reading.

      +

      Alex: First, on the Accessibility settings page, switch to Browse Mode if not already active. Then, press F or X to jump through form controls until you hear "Link previews" or "Hovercards". After that, if it is announced as checked or on, press Space to turn it off. Finally, the change saves automatically - no Submit button required. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      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 2. Enable Link Underlines. What should a learner take away from it?

      +

      Alex: The reason 2. Enable Link Underlines matters is that find the Link underlines checkbox or toggle and turn it on. That gives the learner a simple foothold: this adds underlines to all links on GitHub, making them distinguishable without relying on colour alone.

      +

      Alex: First, press F or X to navigate form controls until you hear "Link underlines". Then, if it is announced as unchecked, press Space to enable it. After that, the change saves automatically. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on 3. Character Key Shortcuts. What should a learner take away from it?

      +

      Alex: Start with 3. Character Key Shortcuts. There is something to understand, something to try, and something that proves the try worked.

      +

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

      +

      Alex: First, find "Character key shortcuts". Then, single-key shortcuts (H for next heading, I for next issue, etc.) speed up navigation but can conflict with screen reader quick-navigation keys. After that, leave at the default unless you have a reason to change 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 4. Set Your Theme (Appearance Settings). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 4. Set Your Theme (Appearance Settings). Theme is on a separate page: GitHub Appearance Settings. It 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: These are the details that keep the idea from floating away. 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.

      +

      Alex: First, navigate to that page. Then, find the "Theme mode" or "Theme" section. After that, options available. Finally, select your preferred theme and activate Save if prompted (some changes apply immediately). 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: Start with Learning Cards: Configure GitHub Accessibility Settings. There is something to understand, something to try, and something that proves the try worked.

      +

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

      +

      Alex: Another way to ground it. Keep the learner anchored in Step 3 - Configure Your Profile. Your GitHub profile is your public identity in the open source community. This is the part to say slowly: Setting it up properly helps maintainers know who you are.

      +
      +

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

      +

      Alex: The reason Who are maintainers? matters is that maintainers are the people who manage a repository -- they review contributions, respond to issues, merge pull requests, and keep the project running. That gives the learner a simple foothold: when you open an issue or submit a pull request, a maintainer is the person who will see it and respond.

      +

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

      +

      Alex: Start with Update your profile. There is something to understand, something to try, and something that proves the try worked.

      +

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

      +

      Alex: First, navigate to Settings → Public profile. Then, fill in. 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 Add a profile picture (strongly recommended). A profile picture is strongly recommended because it humanizes your contributions and helps maintainers and collaborators recognize you across issues, pull requests, and comments. Put another way, it can be a photo or any image that represents you.

      +
      +

      Jamie: Let's pause on Set your notification email. What should a learner take away from it?

      +

      Alex: Start with Set your notification email. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to Settings → Notifications. Then, add a custom routing email if you want GitHub notifications to go to a different address than your account email. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      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: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Keep the learner anchored in Step 4 - Check GitHub Feature Preview Settings. GitHub continuously rolls out improvements to its interface. This is the part to say slowly: Some enhancements start as opt-in Feature Previews before becoming the standard experience.

      +

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

      +

      Jamie: Let's pause on How to Check and Enable Feature Previews. What should a learner take away from it?

      +

      Alex: The reason How to Check and Enable Feature Previews matters is that source: accessibility.github.com/documentation/guide/issues/ and accessibility.github.com/documentation/guide/pull-requests/. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, sign in to GitHub and go to any page. Then, click your profile picture (avatar) in the top-right corner. After that, in the dropdown menu, click Feature preview. Finally, a panel opens on the right side of the screen listing available features. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave How to Check and Enable Feature Previews, what is the practical point?

      +

      Alex: First, click on New Issues Experience to expand its details. Then, if an Enable button appears, click it. If you see Disable, the feature is already active - no action needed. After that, return to the feature list and repeat for New Files Changed Experience. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +
      +

      Jamie: Let's pause on NVDA or JAWS (Windows). What should a learner take away from it?

      +

      Alex: Start with NVDA or JAWS (Windows): Screen reader users (VoiceOver on macOS).

      +

      Alex: The practical takeaway is this. An "Enable" button - press Enter to enable the feature. A "Disable" button - the feature is already enabled; no action needed.

      +

      Alex: First, sign into GitHub and open any page. Then, switch to Browse Mode if not already active (NVDA+Space / JAWS virtual cursor). After that, press H or Shift+H to navigate to the "Navigation Menu" heading, or press D to navigate landmark regions to the navigation section. Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave NVDA or JAWS (Windows), what is the practical point?

      +

      Alex: First, press Enter to activate it - a dropdown menu opens. Then, press ↓ or K to move through the menu items until you hear "Feature preview". After that, press Enter to select it - the Feature Preview panel opens. Finally, navigate through the list of features with ↓ or I (list item navigation). 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. Here is the plain-English version of 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. Put another way, it means both features have graduated to the standard GitHub interface and are active automatically for every user.

      +

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

      +

      Alex: This is where What Each Feature Enables becomes real: 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. That matters in practice: Enabling them before you begin ensures everything works as documented.

      +
      +

      Jamie: Let's pause on NVDA (Windows). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in NVDA (Windows). Install NVDA if you haven't already. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, download from the NVDA download page. Then, run the installer - you can install to your computer or run portably. After that, after launch, NVDA speaks "NVDA started" when running. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Configure NVDA for web browsing. What should a learner take away from it?

      +

      Alex: Start with Configure NVDA for web browsing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open NVDA Menu (NVDA+N). Then, go to Preferences → Settings → Browse Mode. After that, enable "Use screen layout" - this helps with GitHub's landmark navigation. Finally, under Document Formatting, disable announcements you find too verbose. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: This is the part worth saying out loud. Start with Recommended NVDA voice settings: Your NVDA key: By default it is Insert. The next useful detail is this: It can also be set to Caps Lock in NVDA preferences if that is more comfortable.

      +

      Alex: The practical takeaway is this. Rate: 60-75% (fast enough to be efficient, slow enough to be clear). Punctuation: "Most" (reads important symbols like and @ without reading every period).

      +
      +

      Jamie: Let's pause on JAWS (Windows). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of JAWS (Windows). If using a trial: JAWS runs in 40-minute sessions without a license.

      +

      Jamie: Let's pause on Configure JAWS for web browsing. What should a learner take away from it?

      +

      Alex: Start with Configure JAWS for web browsing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open JAWS Settings Center: Insert+F2 → Settings Center. Then, ensure "Virtual cursor" is active for web browsing. After that, in Chrome or Firefox, JAWS should automatically activate Virtual/Browse mode. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Recommended JAWS settings for GitHub. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Recommended JAWS settings for GitHub. Your JAWS key: Insert (or Caps Lock if using laptop layout).

      +

      Alex: The practical takeaway is this. Verbosity → Links: Read link text only (disable "opens in new window" if too verbose). Verbosity → Punctuation: "Most" for same reason as NVDA.

      +
      +

      Alex: Keep the teaching thread moving. The reason VoiceOver (macOS) matters is that activate VoiceOver: Command+F5 toggles VoiceOver on and off.

      +

      Jamie: Let's pause on Essential VoiceOver setup for web. What should a learner take away from it?

      +

      Alex: Start with Essential VoiceOver setup for web: Your VoiceOver modifier key: VO = Control+Option by default.

      +

      Alex: First, open VoiceOver Utility: VO+F8. Then, go to Web category → Web Rotor. After that, ensure these are checked: Headings, Landmarks, Links, Buttons, Form Controls, Tables. Finally, recommended browser: Safari (best VoiceOver integration on macOS). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Essential VoiceOver setup for web, what is the practical point?

      +

      Alex: First, firefox on macOS also has good VoiceOver support. 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 Turn on Quick Nav for fast navigation. There is something to understand, something to try, and something that proves the try worked.

      +

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

      +
      +

      Jamie: Let's pause on A note for Mac users about keyboard shortcuts. What should a learner take away from it?

      +

      Alex: This is where A note for Mac users about keyboard shortcuts becomes real: throughout this documentation, Windows keyboard shortcuts for VS Code are frequently referenced. That matters in practice: In general, these keyboard shortcuts work on the Mac, however, Mac users should substitute Command whenever Ctrl is referenced.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Browser Recommendations Summary. 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.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Start with Learning Cards: Set Up Your Screen Reader and Browser. There is something to understand, something to try, and something that proves the try worked.

      +

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

      +
      +

      Alex: Keep the teaching thread moving. Start with 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. 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 Install Git First. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Install Git First. It detects whether Git is already on your system. Put another way, if Git is missing, the Source Control panel will display a warning, and all git commands in the terminal will fail.

      +

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

      +

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

      +

      Alex: First, download the Git for Windows installer from Git for Windows download page. Then, run the installer - default options are correct for most users. After that, on the "Adjusting your PATH environment" screen, keep the default: "Git from the command line and also from 3rd-party software". Finally, complete the installer and restart any open terminals. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +
      +

      Jamie: Let's pause on Verify installation (Windows). What should a learner take away from it?

      +

      Alex: Start with Verify installation (Windows). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open PowerShell or Command Prompt. Then, type git --version and press Enter. After that, you should see a version number such as git version 2.47.0.windows.2 - any version is fine. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

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

      +

      Alex: The reason macOS matters is that Git is often already present via Xcode Command Line Tools. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, open Terminal (Cmd+Space → type "Terminal"). Then, type git --version and press Enter. After that, 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. Finally, alternatively, install directly from Git for macOS download page or via Homebrew: brew install git. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Screen reader note (Windows terminal verification). What should a learner take away from it?

      +

      Alex: Start with Screen reader note (Windows terminal verification): Once Git is installed, you will configure your Git identity in Step 7 after VS Code is set up.

      +

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

      +
      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Install Visual Studio Code. Visual Studio Code (VS Code) is the development environment used throughout this workshop. Put another way, it is free, open source, and has excellent built-in accessibility support.

      +

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

      +

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

      +

      Alex: First, navigate to code.visualstudio.com. Then, select the download link for your operating system. After that, run the installer with default options. Finally, launch VS Code when the installer finishes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Enable Screen Reader Mode in VS Code. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Enable Screen Reader Mode in VS Code. Do this before anything else in VS Code. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, listen for the dialog - it will say something like "A screen reader is detected. Would you like to enable Screen Reader Optimized mode?". Then, press Enter to accept, or Tab to the Enable button and press Space. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +
      +

      Jamie: Let's pause on Option A - Keyboard shortcut. What should a learner take away from it?

      +

      Alex: Start with Option A - Keyboard shortcut. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Shift+Alt+F1. Then, VS Code toggles Screen Reader Optimized mode immediately. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Option B - Command Palette. What should a learner take away from it?

      +

      Alex: Start with Option B - Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your screen reader will announce "Type to filter" or the palette input field.

      +

      Alex: First, press Ctrl+Shift+P to open the Command Palette. Then, arrow down to "Accessibility: Toggle Screen Reader Accessibility Mode". 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 How to confirm it is on. What should a learner take away from it?

      +

      Alex: Start with How to confirm it is on. 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 again. Then, if the status bar at the bottom of the window is accessible to you, it will read "Screen Reader Optimized". After that, alternatively: go to File → Preferences → Settings (Ctrl+,), type screenReaderOptimized in the search box, and verify the checkbox is ticked. 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 What Screen Reader Mode changes becomes real: once Screen Reader Mode is on, you navigate the editor with Up and Down Arrow to move line by line. That matters in practice: Press Enter to open a folded section. 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 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.

      +

      Jamie: Let's pause on Learning Cards: Install Git and Visual Studio Code. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Install Git and Visual Studio Code. There is something to understand, something to try, and something that proves the try worked.

      +

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

      +

      Alex: Keep the teaching thread moving. The reason Step 7 - Configure Git Identity matters is that now that Git is installed, tell it who you are. That gives the learner a simple foothold: Git embeds your name and email in every commit you make, and this affects how your contributions appear in project history.

      +
      +

      Jamie: Let's pause on Configure in VS Code. What should a learner take away from it?

      +

      Alex: Start with Configure in VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Menu: Terminal → New Terminal. Keyboard: Ctrl+ (Windows) or Cmd+ `` (Mac).

      +

      Alex: First, open Visual Studio Code. Then, open the integrated terminal. After that, type the following commands, replacing with your information. 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 config --global user.name "Your Name"; git config --global user.email "your-email@example.com". 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 to use. The terminal in VS Code is accessible with all major screen readers. Put another way, press Ctrl+ to move focus to the terminal, type your commands, and press Enter`. It 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. 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).

      +

      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: if Git isn't configured, it will either.

      +

      Alex: The practical takeaway is this. Use a default name like "Unknown" (looks unprofessional in project history). Refuse to create commits with an error message.

      +
      +

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

      +

      Alex: Keep the learner anchored in Verify Your Configuration. Run this command to see your current settings.

      +

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

      +

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

      +

      Alex: The reason Using the Correct Email matters is that use the same email you registered with GitHub. That gives the learner a simple foothold: 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.

      +

      Alex: Keep the teaching thread moving. Start with Step 8 - Install VS Code Extensions: This workshop uses two VS Code extensions. The next useful detail is this: GitHub Copilot is built into VS Code automatically. 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 GitHub Copilot (Built In). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of GitHub Copilot (Built In). GitHub Copilot is automatically included with Visual Studio Code. Put another way, there is no extension to install separately.

      +

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

      +

      Alex: This is where Activate Copilot becomes real: you do not need to use the Command Palette to sign in. That matters in practice: If you are logged into GitHub in your browser, VS Code handles authentication automatically when you first interact with the agent.

      +

      Alex: The practical takeaway is this. Your screen reader should announce the chat input field.

      +

      Alex: First, make sure Screen Reader Mode is enabled (see above). Then, make sure you are signed into GitHub in your web browser. After that, press Ctrl+Shift+I to open Agent mode. Finally, VS Code will automatically sign you into GitHub Copilot using your browser session - no manual sign-in command is needed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Activate Copilot, what is the practical point?

      +

      Alex: First, a response will appear in the chat history above the input field. Then, navigate up with Shift+Tab or Up Arrow to read the response. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Extension 2 - GitHub Pull Requests. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Extension 2 - GitHub Pull Requests. This extension lets you review and manage pull requests without leaving VS Code. This is the part to say slowly: It is used in the code review chapters.

      +
      +

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

      +

      Alex: The reason Install matters is that extension imposter warning: The VS Code Marketplace contains third-party extensions with similar names. That gives the learner a simple foothold: always verify the publisher before installing. 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. This extension was formerly named "GitHub Pull Requests and Issues" - either name is correct.

      +

      Alex: First, press Ctrl+Shift+X to open the Extensions panel. Then, press Tab to move into the results list. After that, arrow down to find "GitHub Pull Requests" with publisher "GitHub". Finally, press Enter to open the details page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Install, what is the practical point?

      +

      Alex: First, press Tab to the Install button and press Enter or Space. Then, VS Code will announce when installation is complete. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

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

      +

      Alex: Start with Verify it is working: The Pull Requests panel is a tree view. The next useful detail is this: Navigate it with Up and Down Arrow.

      +

      Alex: The practical takeaway is this. If you are already signed in from the earlier step, this command may not appear - that means you are already authenticated. The Pull Requests panel should open in the sidebar. If your repository has open pull requests, they will appear here.

      +

      Alex: First, press Ctrl+Shift+P and type: GitHub Pull Requests: Sign in. Then, to confirm the extension loaded: press Ctrl+Shift+P, type GitHub Pull Requests: Focus on Pull Requests View. 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 Copilot Free tier. Copilot Free is available to all GitHub users at no cost. Put another way, for this workshop, Free tier is sufficient.

      +

      Alex: The practical takeaway is this. Limited inline code completions per month. Limited Copilot Chat messages per month.

      +
      +

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

      +

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

      +

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

      +

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

      +

      Alex: Keep the learner anchored in 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). This is the part to say slowly: 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. 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 --version; git config user.name; git config user.email; gh auth status if GitHub CLI is installed. 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; [ ]. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: If setup starts to feel like a barrier, how should a learner think about it?

      +

      Alex: The reason What Happens at the Start of Day 1 matters is that 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. That gives the learner a simple foothold: when the workshop opens, the facilitator will paste a GitHub Classroom assignment link in the chat.

      +
      +

      Alex: Keep the teaching thread moving. Start with Other GitHub Access Methods (Reference Only): This workshop focuses entirely on GitHub.com in the browser and VS Code. The next useful detail is this: However, you should be aware that other ways to work with GitHub exist.

      +

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

      +

      Alex: Here is the plain-English version of GitHub Desktop. A graphical desktop application for managing repositories, branches, and commits without using the command line.

      +

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

      +

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

      +

      Alex: This is where GitHub CLI (gh) becomes real: a command-line tool that lets you perform nearly any GitHub action directly from your terminal. 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. 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.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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: Keep the learner anchored in GitHub Copilot CLI (gh copilot). An extension to the GitHub CLI that brings Copilot assistance to the terminal. This is the part to say slowly: You can ask it to explain or suggest shell commands in plain English.

      +

      Alex: The practical takeaway is this. Install: gh extension install github/gh-copilot. Documentation: docs.github.com/en/copilot/github-copilot-in-the-cli. Particularly useful for users who prefer a terminal workflow.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Reference examples only; gh copilot suggest "how do I undo my last commit"; gh copilot explain "git rebase -i HEAD 3". 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 Git (the version control system itself) matters is that GitHub is a platform built on top of Git, which is the underlying version control system. That gives the learner a simple foothold: Git runs locally on your computer via a terminal.

      +

      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.

      +
      +

      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 1. Next in the series is episode 2, where we keep building the same contributor muscles.

      - +

      Episode 2: Understanding GitHub on the Web

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

      -

      Based on: Chapter 1: Understanding GitHub on the Web

      - - -

      Download Episode 2 (MP3)

      +

      Based on: Chapter 2: Understanding GitHub on the Web

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 2: Understanding GitHub on the Web

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is Episode 2: Understanding GitHub on the Web. I am your host, Alex, and I am here to guide you through learning GitHub and open source collaboration, specifically designed for screen reader users and developers with low vision.

      -

      Jamie: And I am Jamie! I am so excited to be here. I learned GitHub about two years ago, and I still remember exactly how overwhelming it felt the first time I landed on a repository page. There is just so much information coming at you all at once.

      -

      Alex: It is incredibly overwhelming at first. In Episode 1, we made sure you had your GitHub account created and Git installed on your machine. Those were our prerequisites. Today, we are going entirely web-based. We are going to build a mental map of how GitHub organizes its web interface. Once you understand the underlying structure, the HTML headings, the ARIA landmarks, and the URL patterns, you will never feel lost on a GitHub page again.

      -

      Jamie: I love the idea of a mental map. When I first started, I used to just press the Tab key about fifty times to find what I wanted. I had no map. I just had hope and a lot of patience.

      -

      Alex: We are definitely going to save your Tab key today. To start, let us talk about the big picture. GitHub is not just one type of page. It is a nested structure. Think of GitHub like a massive office building.

      -

      Jamie: Okay, an office building. I can picture that.

      -

      Alex: Right. When you first log in, you land on your dashboard. That is the lobby of the building. It shows you a feed of recent activity from projects you follow. Also in this lobby level, you have your profile page, which is like your employee badge showing your recent work, and your settings page, which is like the administrative office.

      -

      Jamie: So the dashboard, profile, and settings are all Level 1. The lobby. Where does the actual coding happen?

      -

      Alex: That happens in a repository. If the dashboard is the lobby, a repository is a dedicated project room on an upper floor. A repository is simply a central place where all the files, code, and history for a specific project live. When developers say, navigate to the repo, they mean navigate to that specific project room.

      -

      Jamie: And once you are inside that repository room, you have different stations, right? Like issues and pull requests.

      -

      Alex: Exactly. Let us define those, because they are the most important page types you will interact with. An issue is basically a to-do ticket or a discussion thread. If you find a bug in the code, or you want to suggest a new feature, you open an issue. It has a title, a description, and a comment thread where people can discuss it.

      -

      Jamie: And what about a pull request?

      -

      Alex: So a pull request - and I love that name because you are literally requesting that someone pull your changes into their project - is what happens when you have actually written some code to fix that bug. You submit a pull request, often just called a PR, to propose your changes. The PR page is a bit more complex. It has the conversation thread, just like an issue, but it also has tabs to review the specific lines of code that were changed.

      -

      Jamie: Okay, so to recap our building analogy. The dashboard is the lobby. The repository is the project room. An issue is a to-do ticket sitting on a desk in that room. And a pull request is a formal proposal to change something in that room.

      -

      Alex: That is a perfect summary. And no matter which of these rooms you are in, there are certain structural elements that are always present. Let us talk about how to navigate them without spamming the Tab key.

      -

      Jamie: So, if I am not supposed to just Tab through the page, what is the first thing I should do when I land on a GitHub page?

      -

      Alex: The very first thing you will encounter on every single GitHub page, if you are navigating from the top of the document, is the jump-to-content skip link.

      -

      Jamie: Oh, the skip link! I actually know this one. It is a hidden link right at the top of the page. If you press Tab exactly once when the page loads, your screen reader will announce, Skip to content. If you press Enter on it, it skips over all the global navigation links and drops your focus directly into the main, unique content of that specific page.

      -

      Alex: Exactly. It is a massive time saver. But sometimes, you actually do want to access that global navigation. The global navigation bar is present at the top of every single page on GitHub. It contains the GitHub logo, which takes you back to your dashboard lobby. It contains a global search bar. It has links to all your pull requests and issues across all your repositories, your notifications inbox, and your profile menu.

      -

      Jamie: How do I jump straight to that global navigation if I am deep in the middle of reading an issue?

      -

      Alex: This is where ARIA landmarks come in. ARIA landmarks are invisible structural signposts in the HTML that screen readers can recognize and jump between. Every screen reader has a shortcut to cycle through landmarks. If you are using NVDA or JAWS on Windows, you press the letter D. If you are using VoiceOver on a Mac, you press Control plus Option plus U to open the rotor, then use the arrow keys to select Landmarks.

      -

      Jamie: So if I press D, what will I hear?

      -

      Alex: The global navigation bar is wrapped in a landmark called Navigation Menu. So if you press D, your screen reader will say, Navigation Menu landmark. Once you hear that, you can press the letter K to move through the individual links inside it.

      -

      Jamie: That is so much faster. And what happens when I navigate into a repository? Do the landmarks change?

      -

      Alex: The Navigation Menu landmark stays exactly the same, because it is global. But a new landmark appears just below it, called the Repository navigation landmark. This contains the tabs specific to that project room: the Code tab, the Issues tab, the Pull requests tab, and so on.

      -

      Jamie: Okay, so D for Navigation Menu gets me the global stuff. D again gets me the Repository navigation for the project tabs. What is below that?

      -

      Alex: Below that is the Main landmark. This is where the actual content of the page lives. If you are on an issue, the Main landmark holds the issue description and comments. If you are on the repository home page, the Main landmark holds the file tree and the project Read Me.

      -

      Jamie: I remember struggling so much to find the reply box when I wanted to leave a comment on an issue. I would just scroll and scroll. Is there a landmark for that?

      -

      Alex: There is! This is one of my favorite GitHub accessibility features. On any page where you can leave a comment, like an issue or a pull request, there is a specific landmark called Add a comment. You just press D until you hear Add a comment landmark, and you are right at the text box, ready to type.

      -

      Jamie: Okay, so landmarks are like the major zones of the page. Global nav, repo nav, main content, and the comment box. What about the actual content itself? If I am in the Main landmark, how do I know what I am looking at?

      -

      Alex: For that, we use the HTML heading structure. GitHub is very disciplined about how they use headings, and learning their pattern is the key to orienting yourself.

      -

      Jamie: I use the letter H to jump between headings all the time. But how do you use it for orientation?

      -

      Alex: Think of the Heading Level 1, or H1, as your You Are Here marker on a shopping mall directory map. It tells you exactly what page you are on. Every time you land on a new GitHub page, I recommend pressing the number 1 on your keyboard to jump straight to the first H1.

      -

      Jamie: What will I hear when I press 1?

      -

      Alex: It depends on the page type. If you navigate to a repository home page and press 1, you will hear the owner name slash the repository name. For example, community-access slash accessibility-agents. That confirms you are in the right project room. If you navigate to the issues list and press 1, you will just hear Issues.

      -

      Jamie: And if I open a specific issue?

      -

      Alex: If you open an issue and press 1, the H1 is the title of the issue itself. Like, Fix contrast on submit button. Same for a pull request. The H1 is always the title of the PR.

      -

      Jamie: That is so consistent. I love that. So H1 tells me where I am. What about the rest of the content?

      -

      Alex: Below the H1, GitHub uses H2s for major sections, and H3s for individual items. For example, on an issue detail page, the H1 is the issue title. Below that, there is an H2 called Description, which is the original bug report. Below that is an H2 called Activity, which contains all the comments.

      -

      Jamie: Oh, and let me guess, the individual comments are H3s?

      -

      Alex: You guessed exactly right. Every single comment on an issue or a pull request starts with an H3 heading that contains the author's username and the timestamp. So, if you open an issue with forty comments, you do not have to read them line by line. You just press the number 3 on your keyboard to jump from comment to comment, hearing who wrote it and when.

      -

      Jamie: That is brilliant. I wish I had known that when I started. I used to read the entire page from top to bottom. Okay, that sounds like a lot of steps to remember, though. Press D for landmarks, press 1 for the title, press 3 for comments.

      -

      Alex: It does sound like a lot! But here is the thing - you have already done most of this on Day 1 when you were browsing the web. It is the exact same workflow, just applied to a highly structured application. I recommend a ten-second orientation sequence every time you open a GitHub link.

      -

      Jamie: Walk me through the ten-second sequence.

      -

      Alex: Step one: press the number 1. Listen to the H1 to confirm what page you are on. Step two: press D a few times to cycle through the landmarks, so you know what regions are available on this page. Step three: pull up your screen reader's Elements List. In NVDA, that is NVDA plus F7. In JAWS, it is Insert plus F6 for the headings list.

      -

      Jamie: Ah, the Elements List! That brings up a dialog box with a clean list of every heading on the page, right? Like a table of contents.

      -

      Alex: Exactly. By doing those three things, which takes about ten seconds, you know exactly what page you are on, where the major zones are, and you have scanned the table of contents. You are completely oriented without needing to see the visual layout at all.

      -

      Jamie: One quick warning for folks - I remember getting really confused once because the landmarks disappeared. It turned out I had my browser window snapped to half the screen. GitHub is responsive, so when the window got narrow, it collapsed the sidebar and hid some of the navigation into a mobile-style menu.

      -

      Alex: That is a fantastic point, Jamie. To get the most consistent heading and landmark experience, always keep your browser window maximized when working on GitHub.

      -

      Jamie: So, navigating by headings and landmarks is great. But earlier you mentioned there are ways to jump around without even doing that. You mentioned built-in keyboard shortcuts.

      -

      Alex: Yes. GitHub has its own complex system of keyboard shortcuts built directly into the web application. They are powered by JavaScript, and they let you do things like jump straight to the pull requests tab, or filter issues by assignee, all with single keystrokes.

      -

      Jamie: But wait. If I press the letter H to use a GitHub shortcut, my screen reader is just going to intercept it and jump to the next heading, right?

      -

      Alex: Exactly. And this is the single biggest point of friction for screen reader users learning GitHub. You have to understand the difference between your screen reader's Browse Mode and Focus Mode.

      -

      Jamie: Can you break that down for us?

      -

      Alex: Absolutely. Browse Mode, which JAWS calls the Virtual Cursor, is what you use to read pages. In this mode, your screen reader intercepts your keystrokes. Pressing H goes to a heading. Pressing B goes to a button. The web page never hears you press those keys.

      -

      Jamie: Right, because if the web page heard it, you would just be typing the letter H over and over.

      -

      Alex: Exactly. Focus Mode, on the other hand, is what you use to type into text boxes. When you enter Focus Mode, the screen reader stops intercepting keys and passes them directly through to the web page. Usually, your screen reader switches to Focus Mode automatically when you land on a text box.

      -

      Jamie: But to use GitHub's custom keyboard shortcuts, we need to manually switch to Focus Mode even when we are not in a text box, right? So the page can hear the keystroke.

      -

      Alex: You nailed it. If you want to use a GitHub shortcut, you must manually enter Focus Mode first. In NVDA, you press NVDA plus Space. In JAWS, you press Insert plus Z. You will hear a little click or chime. Now, your keystrokes are going straight to GitHub.

      -

      Jamie: Okay, so once I am in Focus Mode, what are these magical GitHub shortcuts? How do I learn them?

      -

      Alex: You do not have to memorize them from a manual. GitHub has a built-in cheat sheet. If you press the Question Mark key - which is Shift plus Slash - GitHub opens a dialog box that lists every single shortcut available for the exact page you are currently on.

      -

      Jamie: Oh, that is clever! So the list changes depending on whether I am in the lobby dashboard or the project repository?

      -

      Alex: Yes, it is context-aware. Let us say you are in a repository. You press NVDA plus Space to enter Focus Mode. Then you press Shift plus Slash to open the shortcut menu. You will see shortcuts like pressing the letter G followed by the letter I to jump straight to the Issues tab. Or G followed by P to jump to the Pull Requests tab. Think of them as the secret elevator buttons in our office building.

      -

      Jamie: So G stands for Go. Go to Issues, Go to Pull Requests. That makes total sense. And once I am done using the shortcut, I need to remember to press NVDA plus Space again to turn Browse Mode back on, so I can read the new page with my normal heading keys.

      -

      Alex: Exactly. It takes a little practice to toggle between Focus Mode and Browse Mode, but it unlocks incredible speed. And there is one shortcut that is so powerful, you do not even need to toggle modes to use it, because it automatically throws your focus into a text field.

      -

      Jamie: Ooh, I know this one. The Command Palette!

      -

      Alex: Yes, the Command Palette. You can reach it from any page on GitHub by pressing the Forward Slash key, or by pressing Control plus K.

      -

      Jamie: Control plus K is my absolute favorite. What does it actually do?

      -

      Alex: When you press Control plus K, a search box pops up in the middle of your screen. But it is not just for searching text. It is a command center. You can type the name of a repository, and press Enter to jump straight to it. You can type the name of a file, or type the word settings to jump to your settings page.

      -

      Jamie: To use our building analogy, the Command Palette is like a magical concierge desk. You just walk up, press Control plus K, tell them where you want to go, and they instantly teleport you there. You do not even need to know which floor it is on.

      -

      Alex: That is a perfect analogy. The Command Palette is incredibly powerful for accessibility because it completely bypasses the need to navigate through complex menus or nested tabs. You just declare your intent, and GitHub takes you there.

      -

      Jamie: Alex, there is one more shortcut I have heard people talk about, and it sounds almost like magic. Something about pressing the period key?

      -

      Alex: Ah, yes. The period key shortcut. This is one of the most remarkable features GitHub has introduced in recent years. It is the bridge between reading code on the web and actually editing it.

      -

      Jamie: How does it work?

      -

      Alex: If you are on any repository page or viewing any file on GitHub, and you switch to Focus Mode and press the period key, the entire web page transforms. You leave github dot com, and you are redirected to a URL that says github dot dev.

      -

      Jamie: Github dot dev. What is the difference?

      -

      Alex: Github dot com is the standard web interface we have been talking about—the issues, the pull requests, the project rooms. Github dot dev is a fully functioning version of Visual Studio Code, the code editor, running entirely inside your web browser.

      -

      Jamie: Wait, so I do not have to install anything? I just press the period key, and suddenly I am in a professional code editor with the entire project loaded up?

      -

      Alex: Exactly. No installation, no cloning the repository to your local computer, no terminal commands. It just opens the project in a web-based editor. And because it is VS Code, it has excellent screen reader support built right in.

      -

      Jamie: That is wild. Why would I use that instead of just downloading the code to my laptop?

      -

      Alex: It is perfect for quick changes. Let us say you are reading the project Read Me, and you notice a typo. Instead of opening your terminal, downloading the project, opening your local editor, fixing the typo, and pushing the code back up... you just press the period key. The editor opens in your browser, you fix the typo, you commit the change from the web interface, and you are done.

      -

      Jamie: I love that. It lowers the barrier to entry so much. If someone finds an accessibility bug in documentation, they can fix it in literally two minutes right from the browser.

      -

      Alex: Exactly. Now, there is one pro-tip for screen reader users regarding the period key. If you just press period, it transforms your current browser tab into the editor. When you are done, you have to hit the back button to get back to GitHub. A better way is to press Shift plus Period, which types the greater-than symbol.

      -

      Jamie: What does Shift plus Period do?

      -

      Alex: It opens github dot dev in a brand new browser tab. That way, you keep your original GitHub page open in your first tab, and you have your code editor in the second tab. It is much easier to keep your mental map intact that way.

      -

      Jamie: Shift plus Period for a new tab. I am definitely writing that one down.

      -

      Alex: We have covered a massive amount of ground today, Jamie. Let us wrap up with some concrete takeaways for our listeners to practice.

      -

      Jamie: I will take the first one! Takeaway number one: Think of GitHub like a building. The dashboard is the lobby, the repository is the project room, issues are to-do tickets, and pull requests are formal proposals to change the code.

      -

      Alex: Perfect. Takeaway number two: Use the ten-second orientation sequence on every new page. Press the number 1 to hear the H1 heading and know where you are. Press D to scan the ARIA landmarks like Navigation Menu and Main. And use your screen reader's Elements List to read the table of contents.

      -

      Jamie: Takeaway number three: Comments are always H3 headings. If you want to read a discussion thread quickly, just press the number 3 to jump from author to author without reading every single line in between.

      -

      Alex: Takeaway number four: Learn to toggle Browse Mode and Focus Mode. Use NVDA plus Space, or Insert plus Z, to enter Focus Mode so you can use GitHub's built-in shortcuts. Press Shift plus Slash to open the cheat sheet for whatever page you are on.

      -

      Jamie: And takeaway number five: When in doubt, teleport. Press Control plus K to open the Command Palette, type where you want to go, and press Enter. Or press Shift plus Period to instantly open the code in a web-based editor.

      -

      Alex: Those are excellent takeaways. Now that you have a mental map of the building, and you know how to navigate the hallways, you are ready to start looking at the code itself. In Episode 3, we are going to dive deep into Navigating Repositories. We will cover how to read the file tree, how to switch between different branches of code, and how to read the project documentation.

      -

      Jamie: I cannot wait. I am ready to get out of the lobby and into the project rooms.

      -

      Alex: Until then, open up your browser, head to GitHub, and practice your ten-second orientation. Thank you for listening to Gitt Going with GitHub. We will see you in the next episode.

      +

      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.

      +

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

      +

      Alex: Here is the plain-English version of 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.

      +

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

      +

      Alex: The room should hear these as checkpoints. 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 Page Type 5: Your Personal Feed and Profile. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Page Type 5: Your Personal Feed and Profile. Your personal home (github.com) shows activity from repositories you follow. This is the part to say slowly: Your profile (github.com/username) shows your contribution graph, pinned repos, and bio.

      +

      Alex: Another way to ground it. Start with What to expect on your feed. 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 "For you" activity stream - recent activity from repos you watch. A sidebar of suggested repositories and topics.

      +

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

      +

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

      +

      Alex: A few details make that real. 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: This is the part worth saying out loud. 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: That shows up in the workshop in a few specific ways. 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.

      +

      Jamie: Let's pause on 5. Visual Map of a Repository Page. What should a learner take away from it?

      +

      Alex: This is where 5. Visual Map of a Repository Page becomes real: see also: Appendix A: Glossary defines every term used in this course. That matters in practice: Appendix B: Screen Reader Cheat Sheet has quick-reference keyboard shortcuts for navigating headings and landmarks.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Description. A repository home page is laid out from top to bottom as follows. This is the part to say slowly: 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 Screen reader navigation of this page. What should a learner take away from it?

      +

      Alex: The reason Screen reader navigation of this page matters is that press 1 to hear "owner/repo-name" (the H1, confirms you are on the right repo). That gives the learner a simple foothold: press D to hear "Navigation Menu," then D again for "Repository navigation," then D again for "Main" (the file tree area).

      +

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

      +

      Alex: Start with 6. Screen Reader Orientation Sequence: Do this every time you land on a new GitHub page. The next useful detail is this: It takes about 10 seconds once you are practiced. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: These are the details that keep the idea from floating away. 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). 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, main content area - file tree, issue list, PR diff, etc. Treat 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: Screen Reader Orientation Sequence. What should a learner take away from it?

      +

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

      +
      +

      Alex: Keep the teaching thread moving. This is where 7. Landmark Structure by Page Type becomes real: each GitHub page type has a consistent landmark pattern. That matters in practice: Knowing the pattern means you can skip steps 2 and 3 above for familiar pages.

      +

      Jamie: Let's pause on 8. GitHub's Heading Hierarchy in Practice. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 8. GitHub's Heading Hierarchy in Practice. GitHub uses a predictable heading structure. This is the part to say slowly: Learning this pattern means you can navigate any page by heading level alone.

      +

      Alex: Keep the teaching thread moving. The reason Pull request detail - Files Changed tab matters is that 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. 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: GitHub's Heading Hierarchy. What should a learner take away from it?

      +

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

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 9. How GitHub's Layout Changes by Viewport. GitHub is a responsive web application. Put another way, the layout shifts at different screen widths, and this affects what landmarks and headings you encounter.

      +

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

      +

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

      +

      Jamie: Let's pause on At mobile width (below 768px). What should a learner take away from it?

      +

      Alex: The reason At mobile width (below 768px) matters is that consistent experience recommendation: Use your browser maximized or at full desktop width during this workshop. That gives the learner a simple foothold: 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: What does the learner do first, second, and then after that?

      +

      Alex: Start with 10. The Mental Model - Building Your Internal Map: After your first day of using GitHub, you will have an internal map. The next useful detail is this: 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. Think of 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: Building Your Internal Map. What should a learner take away from it?

      +

      Alex: 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: Turn that into a path someone can follow.

      +

      Alex: This is where Try It: The 60-Second Orientation becomes real: time: 1 minute What you need: A browser with your screen reader running. That matters in practice: Open any GitHub repository - try github.com/community-access/accessibility-agents - and prove to yourself that the mental model works. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      +

      Alex: Keep the learner anchored in Day 2 Amplifier. Once you have this mental model solid, the Accessibility Agents make more sense. This is the part to say slowly: 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 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 2. Next in the series is episode 3, where we keep building the same contributor muscles.

      - +

      Episode 3: Navigating Repositories

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

      -

      Based on: Chapter 2: Navigating Repositories

      - - -

      Download Episode 3 (MP3)

      +

      Based on: Chapter 3: Navigating Repositories

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 3: Navigating Repositories

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is episode three, Navigating Repositories. I am Alex, and I am so glad you are joining us today.

      -

      Jamie: Hello everyone! I am Jamie, and I am incredibly ready for this one.

      -

      Alex: Today we are diving into the absolute core of GitHub. We are going to explore what a repository actually is, how to read its history, and how to navigate its structure using your screen reader. We will cover branches, cloning, forking, and all those different sections you encounter when you first open a project.

      -

      Jamie: And just a quick reminder, if you have not listened to episode two, you might want to jump back and check it out. In that episode, we covered the basic structure of a GitHub page. We talked about navigating by headings, using landmarks to find your way around, and using the built in keyboard shortcuts. We will be building directly on those skills today.

      -

      Alex: Exactly. If you are comfortable moving through landmarks and jumping to headings, everything we talk about today is going to feel very approachable.

      -

      Alex: Let us start at the very beginning. What is a repository? At its most basic level, a repository is essentially a project folder that is tracked by Git. It holds all the files, all the folders, and the complete documentation for a specific project.

      -

      Jamie: When I was learning this a couple of years ago, I realized a repository is not just a folder. It is like a magical filing cabinet with a built in time machine. It does not just hold the files as they are right now. It holds every single version of every single file, going all the way back to the very first day the project was created.

      -

      Alex: That is a perfect way to describe it. It is the entire history of the project. And when you navigate to a repository address, like github dot com slash owner slash repo name, you land on the repository home page.

      -

      Jamie: Right, and as soon as the page loads, your screen reader will announce the page title, which tells you the owner and the repository name. If you press the number one key, you will jump straight to the main heading one, which is also the repository name.

      -

      Alex: Once you are on that page, the first major landmark you want to find is the repository navigation landmark. You can reach this by pressing the D key to cycle through your landmarks. This navigation area contains the tab bar, which is how you move between the different sections of the repository.

      -

      Jamie: I like to think of these tabs as different rooms in an office building. They all belong to the same company, but different types of work happen in each room.

      -

      Alex: Let us walk through those rooms. The default tab, the one you land on first, is the Code tab. We will spend a lot of time here. Next to it, you will find the Issues tab.

      -

      Jamie: Issues are your discussion board. This is the room where people report bugs, request new features, or ask questions. If you find a problem with the software, you go to the Issues tab to tell the team about it.

      -

      Alex: Next is the Pull Requests tab. So a pull request, and I love that name because you are literally requesting that someone pull your changes into their project, is a proposal to merge your code. When you write new code and want to share it with the project, you open a pull request.

      -

      Jamie: Then we have the Actions tab. Actions are automated scripts. This is the robot room of the office. It is where automated tests run every time someone submits new code, to make sure nothing is broken.

      -

      Alex: And finally, depending on your permissions, you might find the Settings tab. This is the manager's office. It is usually only visible to the maintainers of the project, and it is where they control permissions and repository features.

      -

      Alex: Let us focus on that first tab, the Code tab. When you are on the Code tab, the main piece of content is the files table. This table shows every file and folder currently in the project.

      -

      Jamie: To get to the files table quickly, I press the T key to jump to the next table on the page. My screen reader will announce something like, table with twenty rows and three columns.

      -

      Alex: Those three columns are very important. The first column is the Name of the file or folder. The second column is the Message, which tells you the most recent change made to that specific file. And the third column is the Age, which tells you how long ago that change happened.

      -

      Jamie: Navigating this table is a great time to use your screen reader table commands. If I am using N V D A or Jaws, I hold down Control and Alt, and use my arrow keys. Pressing Control plus Alt plus Down Arrow moves me to the next row, which is the next file. Pressing Control plus Alt plus Right Arrow moves me across the columns, from the file name, to the message, and then to the age.

      -

      Alex: And if you are using VoiceOver on a Mac, you will hold down the V O keys, plus Shift, and use your arrow keys to move through the table cells.

      -

      Jamie: One thing that confused me at first was telling the difference between a file and a folder in that table. But I learned that if it is a folder, the screen reader will announce a slash at the end of the name. If you press Enter on a folder, the page reloads and shows you the contents of that specific folder.

      -

      Alex: Exactly. Now, immediately following the files table in the reading order is the read me section. The read me dot m d file is a markdown file that acts as the welcome mat for the project. GitHub automatically renders this file and displays it right below the files table.

      -

      Jamie: The read me is its own landmark region, so you can press D to jump to it. Because it is rendered markdown, it has a full heading structure. I always press the H key to read through the headings in the read me so I can quickly understand what the project does and how to install it.

      -

      Alex: Before you reach the files table, there is a very important control called the branch selector. To understand this, we need to define what a branch is, and why repositories have them.

      -

      Jamie: A branch is a separate line of development inside a repository. If we all edited the exact same files at the exact same time, it would be complete chaos. Branches give us parallel timelines to work in safely.

      -

      Alex: That is exactly right. A branch lets you isolate your work.

      -

      Jamie: My favorite analogy for a branch is baking. Imagine you are baking a cake from a cherished family recipe. You want to try adding lemon zest to the batter, but you absolutely do not want to ruin the original recipe card in case your experiment tastes terrible. So, you copy the entire recipe onto a brand new card, write Lemon Experiment at the top, and make your changes there. That new card is a branch. If the cake turns out delicious, you can permanently update the original recipe later.

      -

      Alex: And that original recipe card has a name. It is called the default branch. On modern GitHub projects, the default branch is almost always named main. The main branch holds the stable, official version of the project. Whenever you navigate to a repository, you are viewing the main branch by default.

      -

      Jamie: To switch to a different branch, you use the branch selector. You can press the B key to jump to buttons until you hear the current branch name, which usually sounds like main branch button. When you press Enter, it opens a dropdown panel.

      -

      Alex: This dropdown is a live region. As soon as it opens, your focus is placed in a search field. You can simply start typing the name of the branch you are looking for.

      -

      Jamie: Then, you press the Tab key to move into the filtered results list, and use your Up and Down arrows to find the exact branch. Once you press Enter, the entire page reloads, and the files table will now show the code exactly as it exists on that specific branch.

      -

      Alex: Let us talk about the history of those changes. When you are exploring the files table, you hear the message column. Those messages come from commits. A commit is a saved snapshot of your changes at a moment in time.

      -

      Jamie: I like to think of the commit history as the ultimate project guestbook. If the repository is a magical filing cabinet, the commit history is the unalterable ledger sitting right on top of it. Every single time someone puts a file in or takes one out, they have to sign the ledger, write the exact date and time, and write a little note explaining exactly what they did and why.

      -

      Alex: That is a great comparison. A commit is not just the code that changed. It is the who, the what, and the when. And you can read this entire ledger. On the Code tab, you can navigate to a link that says something like, one thousand commits.

      -

      Jamie: When you activate that link, you are taken to the commit history page. The commits are grouped by date, and you can use your heading navigation, pressing the H key or the number three key, to jump through the dates. Then you use the I key to move through the individual list items, which are the commits themselves. It is fascinating to read through the history and see how a project evolved day by day.

      -

      Alex: So far, we have been browsing code on the GitHub website. But eventually, you will want to work on the code yourself. This brings us to two fundamental concepts, cloning and forking. Let us define cloning first. What does cloning mean?

      -

      Jamie: Cloning means copying a remote repository from GitHub down to your local computer. You are making a full, working clone of the project on your own hard drive, including its entire history.

      -

      Alex: Right. If the repository is a massive encyclopedia in the library, cloning is like checking that encyclopedia out and bringing it to your own desk at home. You can flip through all the pages, read the history, and work with the material entirely offline.

      -

      Jamie: But what if I want to make changes and give them back to the project? I do not have permission to just change their official encyclopedia. This is where forking comes in. A fork is a personal copy of someone else's repository, but it lives in your own GitHub account in the cloud.

      -

      Alex: Exactly. You fork a project on GitHub to create your own copy where you have full control.

      -

      Jamie: My analogy for forking is business. Forking is like buying a franchise of a popular restaurant. You are given the exact blueprints, the menu, and the operations manual of the original restaurant. But this new building belongs to you. You can try out new recipes in your kitchen without affecting the original restaurant. But, if you invent a brilliant new dish, you can send a proposal back to headquarters, asking them to add it to the official menu. That proposal is your pull request.

      -

      Alex: That is brilliant. So, to recap the workflow, you fork the original project to your GitHub account, and then you clone your personal fork down to your computer.

      -

      Jamie: OK that sounds like a lot of steps. I navigate to the repository, I fork it on the website, then I open my terminal, then I find the web address, and then I clone my fork to my computer?

      -

      Alex: It does! But here is the thing, you have already done most of this on Day One. Same workflow, just with V S Code handling the heavy lifting. Once you understand the concepts, the actual execution becomes second nature.

      -

      Alex: Let us talk about the actual mechanics of cloning. When you are on the Code tab, there is a very prominent button labeled simply, Code.

      -

      Jamie: I usually navigate to the main repository heading by pressing the number one key, and then press the B key to move to the next button, which is the Code button. When you press Enter or Space to activate it, it opens a flyout panel.

      -

      Alex: This panel has a few different tabs for how you can get the code, specifically H T T P S, S S H, and GitHub C L I.

      -

      Jamie: If you are using standard Git in your terminal, you would make sure the H T T P S tab is selected, press the Tab key to find the copy url to clipboard button, and press Enter. Then you go to your terminal and type git clone, followed by a space, and paste that long web address.

      -

      Alex: But there is a faster way if you have the GitHub Command Line Interface installed. We call it the g h tool.

      -

      Jamie: Oh I love the g h tool. In that same flyout panel, you can choose the GitHub C L I tab. The command it gives you is so much simpler. Instead of a long web address, you just type g h repo clone, followed by a space, and then the owner name, a slash, and the repository name. So to clone the learning room, you just type g h repo clone community dash access slash learning dash room. It is so clean.

      -

      Alex: It really is. Now, what if someone just wants the files to read, and they do not care about the Git history or making contributions?

      -

      Jamie: If you keep pressing the Tab key inside that Code flyout panel, you will eventually reach a button called Download zip. This gives you a compressed zip folder of the code exactly as it is right this second.

      -

      Alex: Right. But remember, a downloaded zip folder is not tracked by Git. It is like printing out a physical photograph of the code instead of downloading the digital file. You can look at it, but you cannot push any changes back to GitHub from a downloaded zip file. You only use Download zip if you are just exploring.

      -

      Alex: Before we wrap up, we need to talk about one more important region on the repository page. The sidebar.

      -

      Jamie: Yes! After the read me section in the reading order, you will find the sidebar content. To get there quickly, I press the D key until I reach the Main landmark, and then I press the number two key or the H key to jump to the heading called About.

      -

      Alex: The About section is critical because it contains the project description, a link to the project website if they have one, and the repository topics.

      -

      Jamie: Topics are essentially tags. They tell you what the project is built with or what it is for. You might hear topics like python, accessibility, screen reader, or machine learning. It is a great way to quickly understand the context of the code.

      -

      Alex: And right next to the About section, you will find the license. The license is fundamentally what makes open source work. It is a legal document that tells you exactly what you are allowed to do with this code. If a repository does not have a license, you technically do not have permission to use, modify, or distribute it, even if it is completely public on GitHub. Always check the license.

      -

      Alex: We have covered a massive amount of ground today. Let us review our main takeaways.

      -

      Jamie: Takeaway number one. A repository is your main project container. You can navigate its different areas, like Code, Issues, and Pull Requests, by finding the Repository Navigation landmark.

      -

      Alex: Takeaway number two. The Code tab contains the files table. You can use your screen reader table commands to read across the rows, checking file names, commit messages, and how long ago the file was changed.

      -

      Jamie: Takeaway number three. Branches let you work on parallel versions of the code safely, just like testing a recipe on a new card. The official, stable version is almost always kept on the default branch, which is called main.

      -

      Alex: Takeaway number four. Forking creates your own personal copy of a project in the GitHub cloud, like buying a franchise. Cloning downloads a working copy to your local computer, like checking a book out of the library.

      -

      Jamie: And takeaway number five. The commit history is the unalterable guestbook of the project. It tells you exactly who changed what, and when they did it.

      -

      Alex: Perfect summary. In our next episode, we are going to put all of this theory into practice. We will be entering The Learning Room, where you will navigate these tabs yourself and make your very first open source contribution.

      -

      Jamie: I cannot wait for that one. Thank you all for listening, and we will see you in the next episode!

      +

      Alex: Welcome to episode 3 of Git Going with GitHub: Navigating Repositories. 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 Exploring a repository: tabs, files, README, branches, and commit history. 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 A Screen Reader Guide to GitHub Repositories: everything you need to explore a GitHub repository using your keyboard and screen reader. The next useful detail is this: 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: 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 Workshop Recommendation (Chapter 3). Chapter 3 is a confidence-building orientation 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 none. Automation check: none. Why: this chapter teaches navigation foundations that are practiced in later issue and PR chapters.

      +

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

      +

      Alex: This is where Safety-First Learning Pattern becomes real: 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. 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 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: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason What Is a Repository Page? matters is that 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 gives the learner a simple foothold: this page has several distinct regions.

      +

      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 Description: The repository home page is organized from top to bottom as follows. The next useful detail is this: The Navigation bar (GitHub global nav) contains the avatar menu, Notifications, and search. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +
      +

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

      +

      Alex: Here is the plain-English version of Landing on a Repository - What to Expect. 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". 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 Orientation sequence (do this on every new repo) becomes real: 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. That matters in practice: 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: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Keep the learner anchored in 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). This is the part to say slowly: Not all tabs appear on every repository - Discussions, Wiki, and Projects must be enabled by the repository owner.

      +
      +

      Jamie: What is the ordered workflow?

      +

      Alex: The reason How to reach the tabs matters is that the tab bar is visible just below the repository name. That gives the learner a simple foothold: click the tab you want - Code, Issues, Pull requests, etc. 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 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. 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 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: Hold that next to this. Here is the plain-English version of The Files Table. See also: Appendix B: Screen Reader Cheat Sheet lists the keyboard shortcuts for navigating repository file trees. Put another way, the files table is the core of the Code tab - it shows every file and folder in the repo.

      +
      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: This is where Reaching the files table becomes real: 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. That matters in practice: It's visible immediately below the branch selector.

      +

      Alex: That shows up in the workshop in a few specific ways. 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. 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 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. This is the part to say slowly: For example: "docs/ Add accessibility guide 3 days ago". 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 Folder vs file. 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. 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: Here is the practical turn. Start with Learning Cards: The Files Table. 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 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: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of The Branch Selector. The branch selector button sits just above the files table. Put another way, it lets you switch which branch you are viewing.

      +

      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: This is where How to open the branch selector becomes real: mouse users see the current branch name as a button with a dropdown arrow (e.g., main ▼) just above the file table. That matters in practice: Type to filter branches, then click a branch name to switch. 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. 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). 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 open the branch selector. What should a learner take away from it?

      +

      Alex: First, 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: Let's pause on Inside the branch dropdown. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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. This is the part to say slowly: 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: The reason Switching to a tag matters is that tags mark specific releases or versions. That gives the learner a simple foothold: 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. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Switching to a tag, what is the practical point?

      +

      Alex: First, navigate with ↑/↓ and press Enter to select a tag. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

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

      +

      Alex: Start with Cloning a Repository: Cloning copies the repository to your local machine so you can work with it in VS Code or the terminal. The next useful detail is this: 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      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. 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 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: How do you keep commands from becoming magic words?

      +

      Alex: Here is the plain-English version of Or with standard Git. Setup: Install the GitHub CLI from cli.github.com and authenticate with gh auth login. It 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 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: For a learner, the useful signals are these. 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: Keep the learner anchored in Tool Cards: Clone a Repository. github.dev (web editor): No clone needed. This is the part to say slowly: 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. It 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: 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. The rhythm is simple: orient, act, verify, then continue.

      +

      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 Fork vs. Clone vs. Branch - What Is the Difference? What should a learner take away from it?

      +

      Alex: The reason Fork vs. Clone vs. Branch - What Is the Difference? matters is that these three concepts are related but serve different purposes. That gives the learner a simple foothold: students often confuse them, so here is a side-by-side comparison.

      +

      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. 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: Here is what that changes in practice. 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: Here is the plain-English version of Watching, Starring, and Forking. These three actions let you follow, bookmark, or copy a repository.

      +
      +

      Jamie: Let's pause on Watching (subscribe to notifications). What should a learner take away from it?

      +

      Alex: This is where Watching (subscribe to notifications) becomes real: the Watch, Star, and Fork buttons are at the top-right of the repository page, just below the global navigation bar. That matters in practice: 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Forking (create your own copy). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Forking (create your own copy). Click the Fork button (top-right, next to Watch and Star). This is the part to say slowly: 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Forking (create your own copy), what is the practical point?

      +

      Alex: First, tab to "Create fork" and press Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Starring (bookmarking). What should a learner take away from it?

      +

      Alex: The reason Starring (bookmarking) matters is that the button changes to Starred with a filled star icon to confirm. That gives the learner a simple foothold: 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 interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      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. The rhythm is simple: orient, act, verify, then continue.

      +
      +

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

      +

      Alex: Start with 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: Before the learner moves on. Here is the plain-English version of Reading a Markdown file (like README.md). The README renders with full heading structure.

      +

      Alex: These are the details that keep the idea from floating away. 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: This is where Reading a code file becomes real: code files render as a table where each row is one line of code.

      +
      +

      Alex: This is where the talk moves from concept to action. Keep the learner anchored in The file action buttons. Above the file content, there are buttons. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: A few details make that real. 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: The reason How to reach these buttons matters is that 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: Start with 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      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). Treat 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: 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: Another way to ground it. This is where The Blame View becomes real: blame shows you who changed each line of a file, in what commit, and when. That matters in practice: It is useful for tracing why a particular change was made. 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 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. 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 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 Searching for a File. What should a learner take away from it?

      +

      Alex: This is where Searching for a File becomes real: 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: Keep the learner anchored in How to use Go to File. GitHub keyboard shortcut: T - opens the Go to File dialog. This is the part to say slowly: 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. It is 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: 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.

      +
      +

      Alex: Keep the teaching thread moving. Start with GitHub Shortcuts for Repository Navigation - Spotlight: These are the GitHub built-in shortcuts you will use most on repository pages. The next useful detail is this: They work by sending keystrokes directly to GitHub's JavaScript, so enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z). 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. 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: Here is the plain-English version of Navigating the sidebar. The sidebar content is inside the "Main" landmark, after the files table and README. Put another way, 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: This is where The Repository About Section becomes real: 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +
      +

      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. It is 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 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. The rhythm is simple: orient, act, verify, then continue.

      +

      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. Think of 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 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). Treat 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 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. 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: The Five-Tab Tour. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Try It: The Five-Tab Tour. Time: 3 minutes What you need: Browser with screen reader, signed in to GitHub. This is the part to say slowly: Navigate to the Accessibility Agents repository and do this. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      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. It 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: 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. 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 3. Next in the series is episode 4, where we keep building the same contributor muscles.

      - +

      Episode 4: The Learning Room

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

      -

      Based on: Chapter 3: The Learning Room

      - - -

      Download Episode 4 (MP3)

      +

      Based on: Chapter 4: The Learning Room

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 4: The Learning Room

      Transcript

      -

      Alex: Welcome back to Gitt Going with GitHub. This is episode four, titled The Learning Room. I am Alex, and I am here to guide you through the wonderful, sometimes chaotic, but always rewarding world of open source collaboration.

      -

      Jamie: And I am Jamie. I am relatively new to GitHub, having learned it just about two years ago. I am here to ask all the questions that you might be thinking, and hopefully help us all avoid the mistakes I made when I was first starting out.

      -

      Alex: We are so glad to have you here. In this episode, we are talking about the Learning Room. This is a very special part of the GitHub workshop experience. But before we dive into that, let us do a quick recap. In episode three, we talked about navigating repositories.

      -

      Jamie: Right, we talked about how a repository is essentially the master project folder. It holds all the files, the history of changes, and the branches. And we talked about how a branch is like a parallel universe where you can safely make changes without breaking the main project.

      -

      Alex: Exactly. If you are feeling a little fuzzy on how to move through a repository using your screen reader, or how to explore a file tree, you might want to pause this and go back to episode three. But if you are ready to keep going, let us talk about the Learning Room.

      -

      Alex: During your first day of learning GitHub, you are actually working on two parallel tracks. Track one is your individual skills track. This happens on your personal GitHub account. You work through modules at your own pace, and a friendly automated bot named Mona guides you step by step.

      -

      Jamie: I like Mona. Mona is very patient when I forget to commit my changes.

      -

      Alex: Mona is great. But track one is private. It is just you and the bot. Track two is the Learning Room contribution sprint. And this is completely different. The Learning Room is a single, shared GitHub repository where all the workshop participants collaborate together at the exact same time.

      -

      Jamie: Wait, all of us? In one repository? At the same time? That sounds like a recipe for overriding each other's work.

      -

      Alex: It sounds like it, but that is the magic of GitHub. Think of the Learning Room like a large community kitchen. Track one, with Mona, is like practicing chopping vegetables in your own private kitchen at home. You can take your time, and nobody is watching. But the Learning Room is the community kitchen. You are at one prep station, someone else is at the stove, someone else is baking bread. You can all hear and interact with each other, you are all contributing to the same massive meal, but because everyone has their own specific task and their own branch, you do not bump elbows.

      -

      Jamie: Okay, I love that analogy. But why do we do it this way? Why not just keep practicing in our private kitchens?

      -

      Alex: Because open source is a community kitchen. Real open source projects are shared spaces. By putting everyone in one repository, we create a realistic environment. You get to see other people's work, you learn from the person sitting next to you, and we can practice peer review.

      -

      Jamie: That makes sense. It bridges the gap between learning the buttons to press, and actually working with other human beings.

      -

      Alex: Exactly. Now, to understand how we collaborate in this space, we need to talk about the workflow. Specifically, the fork, edit, and pull request workflow.

      -

      Jamie: Oh, good. I hear the word fork all the time. I know what a branch is, but what is a fork? Is it just another utensil in our community kitchen?

      -

      Alex: Great question. Let us define it. A fork is a complete, personal copy of someone else's repository, placed into your own GitHub account. Let us say you find an amazing open source project, but you do not have permission to change their files directly. You would create a fork. That makes a copy in your account where you have full control. You make your edits there.

      -

      Jamie: Okay, so I fork the project, I make my changes in my copy. But how does the original project get those changes?

      -

      Alex: That is where the Pull Request comes in. And I love that name because you are literally requesting that the original project owners pull your changes from your fork into their project. In standard open source, this fork, edit, and pull request workflow is how almost everything gets done.

      -

      Jamie: So in the Learning Room, are we all forking the repository?

      -

      Alex: In the Learning Room, we actually simplify it just a bit to keep us all in one space. Instead of everyone making their own separate fork, we give everyone permission to create branches directly inside the shared Learning Room repository. You will still create a branch, make your edit, and open a Pull Request. It is the exact same workflow you use with a fork, just contained within one big shared house so we can all see each other's pull requests easily.

      -

      Jamie: Okay, so we are in this shared community kitchen. What are we actually cooking? What are the tasks?

      -

      Alex: We call them challenges. Inside the Learning Room repository, there is a folder called docs. Inside that folder, there is a file called CHALLENGES dot M D. M D stands for Markdown. This file is your menu. It lists twelve different challenges organized by skill level, from beginner to expert.

      -

      Jamie: How do I find my challenge and know what to do?

      -

      Alex: You will navigate to that challenges file and read through the options. Each challenge tells you exactly which file you need to edit, what skills you will practice, and what the success criteria are. And here is the fun part. The practice files you will be editing have intentional mistakes built into them.

      -

      Jamie: Intentional mistakes? Like a scavenger hunt?

      -

      Alex: Exactly like a scavenger hunt. Let me give you an example. There is a file called welcome dot M D. It is supposed to be an introduction to open source for newcomers. But it has three sections marked with the word TODO in capital letters, where the content is just missing.

      -

      Jamie: Oh, I have seen those in real projects. Someone writes a document, gets tired, types TODO, and leaves it for someone else.

      -

      Alex: Precisely. One of the beginner challenges is to find those TODO markers, delete them, and write the missing paragraphs. Another file is called keyboard dash shortcuts dot M D. This is a reference guide for screen reader shortcuts. It has tables for N V D A, JAWS, and VoiceOver. But we purposely put incorrect shortcuts in those tables.

      -

      Jamie: Oh, that is devious. I love it. So we have to find the wrong shortcut and fix it?

      -

      Alex: Yes, and you have to do it without breaking the structure of the Markdown table. It is fantastic practice. There is also a setup guide file with broken links that point to nowhere. Your job might be to track down the broken links and update them to the correct web address.

      -

      Jamie: Okay, that sounds like a lot of fun, actually. But how do I know when I am done? Do I just save the file and yell across the room that I finished?

      -

      Alex: Not quite. You know you are done when your Pull Request is merged into the main project. Merging means your changes are officially accepted and combined with the original file. When that happens, an automated bot will actually post a celebration comment on your pull request and award you a digital badge.

      -

      Jamie: Alright, let us talk about opening that Pull Request. I remember the first time I had to open a Pull Request. I was terrified. I felt like I was standing on a stage and everyone was about to judge my code.

      -

      Alex: That is a very common feeling. It can feel incredibly intimidating. You are putting your work out there for public review.

      -

      Jamie: It really is intimidating! OK, that sounds like a lot of steps. Creating branches, making edits, opening this request for everyone to see.

      -

      Alex: It does! But here is the thing. You have already done most of this on Day 1 in your private track. It is the exact same workflow. And remember, the Learning Room is a safe environment. Every single person in that repository is learning, just like you. And we have built safety nets into the process.

      -

      Jamie: Safety nets? Like what?

      -

      Alex: The first safety net is our automated bot. We call it the Learning Room PR Bot. The moment you open your Pull Request, within about thirty seconds, this bot springs into action.

      -

      Jamie: What does the bot do? Does it grade my work?

      -

      Alex: I prefer to think of it as a friendly automated building inspector who walks through the house before the open house begins. The bot checks to make sure you edited the correct file. It checks your Markdown formatting to ensure you used headings correctly. If you added an image, it checks to make sure you included alternative text for screen readers. It even checks to ensure you did not leave any broken links behind.

      -

      Jamie: Wow, that is really thorough. What happens if I messed something up? Does it reject my Pull Request?

      -

      Alex: Never. The bot never fails your Pull Request or closes it. Instead, it posts a very detailed, educational comment on your Pull Request. It tells you exactly what it found, explains why it matters for accessibility or formatting, and gives you links to documentation so you can learn how to fix it.

      -

      Jamie: Oh, I wish I had known that when I started. An automated proofreader that explains things nicely instead of just yelling error messages at me.

      -

      Alex: Exactly. It gives you instant feedback. And you can push a new commit to your branch to fix the issues, and the bot will run again and update its report. It is a completely low-stakes way to practice getting technical feedback.

      -

      Alex: But the bot is only the first step. The second step is human peer review. And this is where the real magic of the Learning Room happens.

      -

      Jamie: Peer review. So, reading and commenting on classmate work. How does that work? Do I just pick someone at random?

      -

      Alex: We have another automation called the pairing bot. When you open your Pull Request, the pairing bot looks at the roster of students and automatically assigns one of your classmates to be your reviewer. It tries to balance the workload so nobody gets overwhelmed.

      -

      Jamie: So someone else in the workshop gets a notification saying, Jamie needs you to review their work?

      -

      Alex: Yes. And the bot even posts a comment giving the reviewer instructions on what to look for. It might say, please check that Jamie completed all three TODO sections, and that the new paragraphs read well.

      -

      Jamie: Okay, so let us walk through this from the perspective of the reviewer. Let us say I get that notification. I have been assigned to review your Pull Request, Alex. How do I navigate that with my screen reader? Where do I go?

      -

      Alex: This is a great practical question. First, you will navigate to the Learning Room repository in your browser. From the main repository page, you need to navigate to the Pull Requests tab.

      -

      Jamie: How do I find that tab efficiently?

      -

      Alex: If you are using N V D A or JAWS on Windows, you can use GitHub's built-in keyboard shortcuts. Press the letter G, followed by the letter P. That stands for Go to Pull requests.

      -

      Jamie: Oh, that is clever! G then P. Does that work for VoiceOver on Mac too?

      -

      Alex: Yes, those are GitHub specific shortcuts, so they work across platforms as long as your screen reader is passing the keystrokes through. Once you are on the Pull Requests page, you will be in a list of all open pull requests. If it is a busy workshop, there might be thirty pull requests in that list.

      -

      Jamie: That sounds overwhelming. How do I find the one I am supposed to review?

      -

      Alex: You use the filter. Navigate to the filter text box. By default, it says something like, is open is PR. You can clear that and type a specific filter query. You will type, review dash requested, then a colon, then the at symbol, and the word me. So, review requested colon at me. Press Enter.

      -

      Jamie: And that filters the list to only show the ones where I am the assigned reviewer?

      -

      Alex: Exactly. Now you can use your screen reader's heading navigation. Press the letter H to jump from one pull request title to the next. When you hear the title of the one you want, press Enter to open it.

      -

      Jamie: Okay, I am on the Pull Request page. What am I looking at? Or rather, what am I listening to?

      -

      Alex: A Pull Request page has a few different tabs, but the two most important ones are the Conversation tab, and the Files Changed tab. You land on the Conversation tab by default.

      -

      Jamie: The Conversation tab. Is that where the bot leaves its report and where people leave comments?

      -

      Alex: Yes. You can use heading navigation here as well. Every comment is a heading. You will find the original description of the Pull Request, the automated bot's report, and any discussion that has happened so far. You will also find a section called Reviewers, usually marked as a heading level three, which confirms that you are assigned.

      -

      Jamie: So I read the conversation to get context. But how do I actually see the changes you made to the code or the text?

      -

      Alex: For that, you navigate to the Files Changed tab. Once you activate that tab, you are looking at the diff.

      -

      Jamie: The diff. Let us define that. A diff is short for difference. It is a special view that shows exactly what was added and what was removed from a file.

      -

      Alex: Right. Navigating a diff with a screen reader takes a little practice. GitHub presents the diff as a table or a structured list of lines. As you arrow down through the content, your screen reader will announce the state of each line.

      -

      Jamie: What does that sound like?

      -

      Alex: If a line was added, your screen reader will usually say plus, or inserted, before reading the text. If a line was removed, it will say minus, or deleted. Unchanged lines, which are just there to give you context, are read normally without a prefix.

      -

      Jamie: So if you were fixing a typo in the word GitHub, I would hear a minus line with the misspelled word, immediately followed by a plus line with the correctly spelled word?

      -

      Alex: Exactly. You can read through the entire file this way, line by line, to see exactly what the author changed.

      -

      Jamie: Okay, so I have read your changes. I think they look great, but I want to suggest one small addition. How do I leave my review?

      -

      Alex: On the Conversation tab, there is a large text area for adding a comment. If you are using N V D A, you might press N V D A plus Space to enter Focus Mode, or Forms Mode for JAWS, so you can type freely. If you are using VoiceOver on a Mac, you would navigate to the text area and press V O plus Shift plus Down Arrow to interact with it.

      -

      Jamie: I type my feedback. Do I just say, looks good?

      -

      Alex: You could, but helpful peer review is specific. You might say, I love the paragraph you added about assistive technology. One suggestion, maybe we could add a link to the official documentation here.

      -

      Jamie: That is a great way to phrase it. It is encouraging but offers a clear improvement. So I type that out. Then what?

      -

      Alex: Then you navigate to the button called Review Changes. When you activate it, you get to choose the type of review. You can choose Comment, which is just leaving feedback without passing judgment. You can choose Approve, which means you think it is perfect and ready to be merged. Or you can choose Request Changes, which means there is something specific that must be fixed before it can be merged.

      -

      Jamie: So if you missed one of the TODO markers, I would choose Request Changes and politely let you know.

      -

      Alex: Exactly. Once you select your option, you navigate to the Submit Review button and press Enter. The author gets a notification, and they can push a new commit to address your feedback.

      -

      Jamie: I really like this process. But I have to ask, what if I am assigned to review someone's work, and I do not know if their code is right? I am a beginner too. I might approve something that is actually broken.

      -

      Alex: That is the beauty of the Learning Room. It is completely low stakes. Remember the flight simulator analogy?

      -

      Jamie: A flight simulator. Where you can crash the plane without actually hurting anyone.

      -

      Alex: Exactly. We want you to make mistakes here. If you approve a Pull Request that has a formatting error, the automated bot will probably catch it anyway. And even if the bot misses it, and it gets merged into the repository, that is fine! It just becomes a new challenge for the next student to fix.

      -

      Jamie: Oh, I never thought of it that way. A mistake just creates more open source work for the community.

      -

      Alex: Right. The goal here is not perfect code. The goal is building confidence. When you practice this fork, edit, and pull request workflow in a safe environment, you are building muscle memory.

      -

      Jamie: So when I go to contribute to a huge project like N V D A or React, my hands will already know the keyboard shortcuts. I will already know how to filter for my reviews.

      -

      Alex: Precisely. Because the steps you take in the Learning Room are the exact same steps you take on the biggest open source projects in the world. And I want to emphasize this. When you merge a Pull Request in the Learning Room, it is a real contribution.

      -

      Jamie: It is not a simulation?

      -

      Alex: The environment is designed for learning, but the technology is real. You found an issue, you made a meaningful change, you received technical feedback from a bot, you received human feedback from a peer, you incorporated their suggestions, and you merged your work. That is open source contribution in its purest form. You will have a merged commit in your GitHub history to prove it.

      -

      Jamie: That is incredibly motivating. It takes the fear out of the process and replaces it with a sense of community.

      -

      Alex: Let us wrap up with a few key takeaways from our discussion today. First, the Learning Room is a shared repository where everyone collaborates together. It is designed to simulate the bustling, collaborative nature of a real open source project.

      -

      Jamie: Second, the practice challenges are real files with intentional mistakes. You find your challenge in the docs folder, make your fixes on a branch, and open a Pull Request.

      -

      Alex: Third, you are supported by two types of feedback. The automated bot gives you instant, low-stakes technical feedback on accessibility and formatting. And your peers give you human feedback on your content.

      -

      Jamie: And finally, leaving a peer review is just as important as writing the code. You use the filter review requested colon at me to find your assignments, read the diff to see what changed, and leave constructive, encouraging comments.

      -

      Alex: Beautifully summarized. In our next episode, we are going to dive deeper into how projects organize all of this work. We will be talking about Working with Issues. Issues are how we track bugs, plan features, and figure out what to work on next.

      -

      Jamie: I cannot wait. Tracking tasks is my favorite kind of organizing.

      -

      Alex: Thank you all for listening to Gitt Going with GitHub. Take a deep breath, go open that first Pull Request in the Learning Room, and we will see you in the next episode.

      +

      Alex: Welcome to Git Going with GitHub, episode 4: The Learning Room. I am Alex. Today we are going to make The Learning Room 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: Your shared practice environment: challenges, PR workflow, bot feedback, peer review. 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 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: The next layer is 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. It 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. 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: What is the one idea that makes the next few steps less mysterious?

      +

      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: What is the ordered workflow?

      +

      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: 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 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      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: How would you walk the room through that step by step?

      +

      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: What does the learner do first, second, and then after that?

      +

      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.

      +

      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: Where do you want a learner to place their attention here?

      +

      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: Before the learner moves on. The reason Workshop Recommendation (Chapter 4) matters is that chapter 4 is a system orientation 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 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: Hold that next to this. 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.

      +
      +

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

      +

      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: That shows up in the workshop in a few specific ways. 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: That connects to another useful point. 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: For a learner, the useful signals 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: 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: What would you say to someone who is already bracing for this to be too much?

      +

      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 thread going. 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. 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. 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: Give me the version that sounds like an instructor, not a manual.

      +

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

      +

      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 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 parts worth keeping in working memory are these. 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: Now bring the learner back to the room. 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.

      +
      +

      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: That matters because of the next idea. 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? 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 [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.

      +

      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 does someone need before they touch the keyboard?

      +

      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: Another way to ground it. 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +
      +

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

      +

      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.

      +

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

      +

      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 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: This is the part worth saying out loud. 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 makes this practice feel low-stakes but still real?

      +

      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.

      +

      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.

      +

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

      +

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

      +

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

      +

      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.

      +

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

      +

      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: 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. 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 "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. 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.

      +
      +

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

      +

      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.

      +
      +

      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 4. Next in the series is episode 5, where we keep building the same contributor muscles.

      - +

      Episode 5: Working with Issues

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

      -

      Based on: Chapter 4: Working with Issues

      - - -

      Download Episode 5 (MP3)

      +

      Based on: Chapter 5: Working with Issues

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 5: Working with Issues

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is episode 5, Working with Issues. I am Alex, and I am here to guide you through the accessibility and workflow concepts that will help you thrive in open source.

      -

      Jamie: And I am Jamie. I am a blind developer who started learning GitHub about two years ago, and I am here to ask all the questions that you are probably thinking right now.

      -

      Alex: It is great to have you here, Jamie. In episode 3, we covered repository navigation and how to move between the different tabs of a project. Today, we are diving deep into one of those specific tabs, the Issues tab. We will cover what issues are, how to read them, how to file them, and how to manage them.

      -

      Jamie: I remember when I first heard the word issue in the context of programming. In everyday life, having an issue sounds like a bad thing. Like a problem. I thought it meant I broke something.

      -

      Alex: That is such a common reaction! But in GitHub, an issue is not necessarily a bad thing at all. Think of an issue simply as a unit of work. It is a dedicated discussion thread attached to a repository. Yes, it can be a bug report, but it can also be a feature request, a question, a task, or an accessibility report.

      -

      Jamie: So it is basically a digital manila folder for a specific topic.

      -

      Alex: Exactly. That is a perfect analogy. If you want to add a new button to your application, you open a manila folder, write Add New Button on the tab, and put all your notes, questions, and checklists inside that folder. On GitHub, that folder is an issue. It keeps the conversation focused and gives everyone a place to collaborate before any code is actually written.

      -

      Jamie: Okay, so how do I actually find these manila folders? Say I am on a repository page right now.

      -

      Alex: If you are using a screen reader, you can navigate by landmarks to the Repository navigation region, then press your Tab key until you reach the Issues tab. Your screen reader will usually announce the word Issues followed by the number of open issues, like, Issues, 14 open. Then you just press Enter.

      -

      Jamie: Is there a faster way? You know I love keyboard shortcuts.

      -

      Alex: There is! If you are in Focus Mode, you can press the letter G, release it, and then press the letter I. G stands for Go, and I stands for Issues. That will jump you straight to the Issues tab from anywhere in the repository.

      -

      Jamie: Oh, that is clever. Go to Issues. G then I. I will definitely use that. So once I am on the Issues page, what does the structure look like?

      -

      Alex: The page is built around a search and filter bar at the top, followed by some buttons to switch between Open and Closed issues, and then the main event, which is the issues list itself.

      -

      Jamie: How should I navigate that list with my screen reader?

      -

      Alex: The best way is to use your heading navigation. Every issue title in the list is a heading level 3 link. So if you press the number 3 on your keyboard, you will jump from issue to issue. Your screen reader will announce the title, the issue number, any labels attached to it, who opened it, and how many comments it has.

      -

      Jamie: That sounds like a lot of information. Does it read it all at once?

      -

      Alex: It usually reads it as a single block of text when you land on the heading. If you want to explore a specific issue in more detail before opening it, you can use your down arrow to read the individual elements like the author and the timestamp.

      -

      Jamie: Let us talk about that search and filter bar you mentioned. If a project has hundreds of open issues, pressing the number 3 to read all of them is going to take all day.

      -

      Alex: You are absolutely right. That is where filtering comes in. It is like having an assistant who can instantly pull only the manila folders you care about from a massive filing cabinet. To reach the search bar, you can navigate to it using your form field shortcut, which is usually the letter E or F depending on your screen reader.

      -

      Jamie: And when I get there, I need to switch to Focus Mode to type, right?

      -

      Alex: Yes, exactly. Switch to Focus Mode, which is Insert plus Space for NVDA, or Insert plus Z for JAWS. Once you are in the text field, you can type qualifiers to filter the list. For example, if you want to find bugs, you type the word is, followed by a colon, followed by the word open, then a space, then the word label, a colon, and the word bug.

      -

      Jamie: So, is colon open space label colon bug.

      -

      Alex: Correct. When you press Enter, the page updates instantly to show only open issues that have the bug label.

      -

      Jamie: What if I want to find issues that are assigned to me?

      -

      Alex: You would type assignee colon at me. The at symbol followed by the word me is a special shortcut in GitHub that always refers to your own username. You can also type author colon at me to find issues you originally filed.

      -

      Jamie: That is really powerful. Are there other ways to filter besides typing these queries out? Sometimes I forget the exact syntax.

      -

      Alex: Absolutely. Right near the search bar, there is an actions toolbar with dropdown buttons for Labels, Milestones, and Assignees. You can Tab to the Label button, press Enter to open the dropdown, use your up and down arrows to find the label you want, and press Enter to select it. When you press Escape to close the dropdown, the list filters automatically.

      -

      Jamie: You mentioned milestones. What is a milestone?

      -

      Alex: A milestone is just a way to group issues together by a target date or a specific release. For example, a project might have a milestone called Version 2 point 0. Filtering by that milestone shows you all the issues that need to be finished before Version 2 point 0 can launch.

      -

      Jamie: Okay, so I have filtered the list, I found an issue that sounds interesting, and I pressed Enter on the heading to open it. What does the actual issue page look like?

      -

      Alex: The page has a very specific anatomy. At the very top, you have the issue title as a heading level 1. Right below that, your screen reader will announce a status badge, telling you if the issue is Open or Closed.

      -

      Jamie: And then comes the description?

      -

      Alex: Yes. The original post, which we call the issue body or description, comes next. But before you read it, it helps to know about the sidebar. On the right side of the screen visually, there is a sidebar containing metadata. It has sections for Labels, Assignees, and the Milestone. These are marked as heading level 3s.

      -

      Jamie: So if I want to quickly check who is assigned to an issue, I can just press the number 3 until I hear Assignees?

      -

      Alex: Exactly. It is a great way to orient yourself. But for reading the main description, you want to stay in Browse Mode. The description is usually formatted using Markdown, which means GitHub turns it into proper HTML. Headings are real headings, bullet points are real lists, and code blocks will actually announce as code.

      -

      Jamie: I love that. There is nothing worse than reading a wall of unformatted text. So I can just use my normal screen reader commands to read the description line by line.

      -

      Alex: Yes. And below the description is the timeline. This is the activity stream of the issue. Every comment left by another person is a heading level 3. So to read a conversation, you just press the number 3 to jump from comment to comment.

      -

      Jamie: Does the timeline only show comments?

      -

      Alex: Good question. No, it shows events too. If someone adds a label, or assigns someone, or references a pull request, those events appear in the timeline chronologically between the comments. They usually read as simple text paragraphs, like, Jamie added the bug label 2 days ago.

      -

      Jamie: Let us flip the script. Instead of reading an issue, I want to file a new one. I found a bug where my screen reader is not announcing a button state, and I want to report it.

      -

      Alex: That is a perfect use case. From the issues list page, you will want to navigate to the New Issue button. You can use the letter K to move through links until you find it, or use your buttons shortcut. Press Enter to activate it.

      -

      Jamie: Does it just give me a blank text box?

      -

      Alex: Sometimes. But many open source projects use Issue Templates. If they do, you will land on a page asking you to pick a template. You might hear options like Bug Report, Feature Request, or Accessibility Issue. You just find the one you want and press Enter on its Get Started button.

      -

      Jamie: Okay, I picked the Bug Report template. Now I am on a form with a title and a body. I remember when I filed my first issue, I just made the title, Screen reader bug. Was that a bad title?

      -

      Alex: It is not terrible, but it is not very helpful to the maintainers. Think of the title like a news headline. It needs to be specific. A much better title would be, Screen reader does not announce expanded state on the main navigation menu.

      -

      Jamie: That makes sense. It tells them exactly what is wrong and where. So I type that into the title field using Focus Mode. Then I Tab to the description field.

      -

      Alex: Right. And this is where you write the body of your issue. If you selected a template, the text area might already have some headings in it, like What Happened, What I Expected, and Steps to Reproduce. You just fill in the details under each heading.

      -

      Jamie: Can I use formatting here? Like making the steps an actual numbered list?

      -

      Alex: Absolutely. The text area supports Markdown. Because you are in Focus Mode while typing, you can use keyboard shortcuts. Control plus B makes text bold. Control plus E formats text as a code block. And Control plus Shift plus the number 7 creates a numbered list.

      -

      Jamie: Oh, I did not know about Control plus Shift plus 7. That is way faster than typing out the numbers manually. What about task lists? I have seen issues that have actual checkboxes in them.

      -

      Alex: Task lists are incredibly useful! You can create them by typing a hyphen, a space, a left bracket, a space, a right bracket, and another space. It looks a bit like a little text drawing of an empty box. When you submit the issue, GitHub renders that as a real, interactive checkbox.

      -

      Jamie: That sounds like a lot of steps. Hyphen, space, bracket, space, bracket.

      -

      Alex: It does! But here is the thing, you have already done most of this on Day 1 of your programming journey. It is just typing characters. And if you use VS Code to write your issue drafts, you can use extensions that handle the heavy lifting for you.

      -

      Jamie: That is a relief. So I have written my steps to reproduce. Is there anything specific I should include because it is an accessibility bug?

      -

      Alex: Yes, always include your environment details. Tell them exactly which screen reader and version you are using, like NVDA 2025 point 3. Tell them your browser and your operating system. A bug might happen on Firefox but not on Chrome, so that context is crucial for the maintainer trying to fix it.

      -

      Jamie: Okay, the issue is filed. What happens when someone replies? How do I comment back?

      -

      Alex: When you open the issue, you can jump straight to the comment box by navigating to the landmark called Add a comment. Or, if you prefer shortcuts, you can just press the letter R while reading a previous comment to reply and automatically quote their text.

      -

      Jamie: I love the R shortcut. Once I am in the text area, it is just like writing the issue body, right? Focus mode, type my reply, use markdown if I want to.

      -

      Alex: Exactly. And when you are ready to post it, you do not even need to Tab to the submit button. You can just press Control plus Enter from right inside the text area to submit your comment.

      -

      Jamie: What if someone leaves a comment that just says, I will look into this today. I want to acknowledge it, but leaving a comment that just says Thanks feels like it might clutter the timeline.

      -

      Alex: That is a brilliant observation. Open source maintainers get a lot of notifications, so adding a comment just to say thanks or I agree can sometimes be overwhelming. Instead, you should use Reactions.

      -

      Jamie: Reactions? Like emojis?

      -

      Alex: Yes. Reactions are a form of lightweight feedback. Every comment has a button to add a reaction. You can add a thumbs up, a heart, a smile, or even a rocket ship. It communicates your acknowledgement without sending an email notification or cluttering the thread.

      -

      Jamie: Analogy time! It is like nodding your head in a meeting. You are showing you understand and agree, without actually interrupting the speaker to say the word yes.

      -

      Alex: That is perfectly stated. Nodding in a meeting. Use reactions to nod.

      -

      Jamie: Let us talk about connecting things together. I have noticed people typing the number sign, or the hash symbol, followed by a number in their comments. What does that do?

      -

      Alex: That is how you cross-reference issues. Every issue and pull request has a unique number. If you are typing a comment and you type the number sign followed by 42, GitHub automatically turns that into a link pointing to issue number 42.

      -

      Jamie: Does it do anything besides make a link?

      -

      Alex: It does! It creates a two-way connection. If you mention issue 42 in your new issue, a timeline event automatically appears over on issue 42 saying that you referenced it. It is like a digital string tying the two documents together, so anyone reading either issue can find the other.

      -

      Jamie: That is so helpful for keeping track of related bugs. I also read something about magic closing keywords. What are those?

      -

      Alex: This is one of the best automations in GitHub. Let us say you open a pull request with code that fixes issue number 42. In the description of your pull request, you type the word Closes, followed by the number sign, and the number 42.

      -

      Jamie: Closes number 42.

      -

      Alex: Right. When your pull request is approved and merged into the project, GitHub sees that keyword and automatically closes issue 42 for you. You do not have to go back and do it manually. You can also use words like Fixes or Resolves.

      -

      Jamie: You mentioned closing an issue. As a beginner, closing an issue sounds scary. Like I am deleting it forever.

      -

      Alex: I completely understand that fear. But closing an issue does not delete anything. It just changes its state from Open to Closed. It is like crossing a task off your paper to-do list. You did not shred the paper, you just drew a line through the text. The history, the comments, and the decisions are all preserved permanently.

      -

      Jamie: So if I realize a bug is actually not fixed, can I un-cross it off the list?

      -

      Alex: Yes, you can. At the bottom of any closed issue, the Close Issue button changes into a Reopen Issue button. You just navigate to it, press Enter, and the issue is back in the Open state.

      -

      Jamie: Who normally closes issues? Can I close someone else's issue?

      -

      Alex: Usually, only the repository maintainers, or the person who originally opened the issue, have the permission to close it. This brings us to issue management. If you are a maintainer, or if you have write access to a repository, you can manage issues by assigning them and labeling them.

      -

      Jamie: How do I assign an issue to myself so people know I am working on it?

      -

      Alex: You go to the issue sidebar. Remember those heading level 3s? You navigate to the Assignees heading. Right next to it is a button to manage assignees. Press Enter to open it, type your username, and select yourself from the dropdown.

      -

      Jamie: And applying labels works the same way?

      -

      Alex: Exactly the same. Navigate to the Labels heading, open the menu, select the labels you want, and press Escape to close. Labels are crucial for organizing work. In fact, there is one specific label every beginner should know about. It is called good first issue.

      -

      Jamie: Oh, I have seen that one!

      -

      Alex: Maintainers use the good first issue label to mark bugs or tasks that are perfect for people who are new to the project. The scope is usually small, and the maintainer is willing to mentor whoever picks it up. If you are looking to make your first open source contribution, searching for is colon open label colon quote good first issue unquote is the best way to start.

      -

      Jamie: Everything we have talked about so far has been in the browser. But in earlier episodes, you showed me how to do things from my computer's terminal. Can I manage issues from the command line too?

      -

      Alex: You absolutely can, using the GitHub CLI. The command is g h space issue.

      -

      Jamie: What kind of things can I do with it?

      -

      Alex: Almost everything. If you open your terminal and type g h space issue space list, it prints out a list of all open issues right in your console. You can even filter it by typing g h issue list dash dash label bug.

      -

      Jamie: That is so fast. What if I want to read one?

      -

      Alex: You type g h issue view followed by the issue number. It will print the title, the description, and all the comments into your terminal. Because it is just plain text in your console, your screen reader will read it flawlessly without needing to navigate complex web page structures.

      -

      Jamie: Can I create an issue from the terminal too?

      -

      Alex: Yes, by typing g h issue create. It will launch an interactive prompt that asks you for the title, and then opens your default text editor so you can write the body. It is a fantastic alternative if you find web forms tedious.

      -

      Jamie: This has been incredibly helpful, Alex. I feel like I understand the flow of conversation on GitHub so much better now.

      -

      Alex: I am glad to hear that, Jamie. Let us recap the key takeaways for today. First, an issue is a dedicated discussion thread for a unit of work, like a bug report or a feature request.

      -

      Jamie: Second, use the search bar and filters to find what you need. Typing is colon open label colon bug will save you from reading through hundreds of irrelevant headings.

      -

      Alex: Third, when reading an issue, use your heading navigation. The title is a level 1, sidebar sections and comments are level 3s. Stay in Browse mode to read, and switch to Focus mode when typing your comments.

      -

      Jamie: Fourth, when filing an issue, be specific! Write a headline, not just a vague category. And remember to use Markdown to format your steps to reproduce clearly.

      -

      Alex: And finally, use the magic keywords like Closes number 42 in your pull requests to automatically close issues when your work is done. Connecting your work creates a clear history for everyone.

      -

      Jamie: Speaking of pull requests, I hear that is what we are covering next.

      -

      Alex: We certainly are. In our next episode, Working with Pull Requests, we will take the code you have written and learn how to propose it to a project. We will cover the review process, leaving inline comments, and finally getting that code merged. You will not want to miss it.

      -

      Jamie: I am looking forward to it. Thanks for listening, everyone!

      -

      Alex: See you next time on Gitt Going with GitHub.

      +

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

      +
      +

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

      - +

      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)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 6: Working with Pull Requests

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is episode six, Working with Pull Requests. I am Alex, and I am here to guide you through the accessibility of open source collaboration.

      -

      Jamie: And I am Jamie! I am here to ask the questions, share my own learning curve, and hopefully prevent you from making the same mistakes I did when I first started using GitHub a couple of years ago.

      -

      Alex: In our previous episodes, we covered a lot of foundational ground. In episode three, we talked about branches, which are safe parallel universes where you can experiment with code. And in episode five, we talked about issues, which are where we track bugs, feature requests, and discussions.

      -

      Jamie: Right. Issues are the conversation about the work that needs to be done, and branches are where you actually do the work. But that leaves a pretty big gap. How do we get the work from our experimental branch back into the main project?

      -

      Alex: That is exactly what a pull request is. A pull request, often just called a P R, is a formal proposal to merge the changes from your branch into another branch. I love the name because it is literal. You are requesting that the project maintainers pull your changes into their code.

      -

      Jamie: When I first started, I was constantly confusing issues and pull requests. They felt like the same thing because they both have titles, descriptions, and comment threads.

      -

      Alex: That is a very common point of confusion. Think of it like a restaurant. An issue is the order ticket. It says, we need a vegetarian pizza at table four. It describes the problem or the requirement. The pull request is the chef putting the finished pizza on the counter and saying, here is the food, can the manager verify it is vegetarian before we serve it?

      -

      Jamie: Oh, I like that. The issue is the work order. The pull request is the finished product waiting for inspection.

      -

      Alex: Exactly. An issue is just text and ideas. A pull request contains actual, modified code.

      -

      Alex: Before we talk about creating one, let us understand the anatomy of a pull request page on GitHub. When you navigate to a pull request, the page is divided into three main tabs.

      -

      Jamie: I use the landmarks for this. I press the D key to move through my ARIA landmarks until I hear Pull request navigation tabs.

      -

      Alex: Perfect. Inside that landmark, you will find three tabs. The first is the Conversation tab. This is where you will find the pull request description, the timeline of all comments, any automated status checks, and the merge button. It is the history of the proposal.

      -

      Jamie: The second tab is Commits. This is just a chronological list of the individual commits that make up your pull request. It is handy if you want to step through the author's thought process commit by commit.

      -

      Alex: And the third tab is Files changed. This is the heart of the pull request. It is where you go to read the diff. A diff is the before and after comparison of every single file that was modified. We are going to spend a lot of time talking about how to read a diff with a screen reader later in this episode.

      -

      Jamie: So, Conversation, Commits, and Files changed. That is the anatomy. How do we actually create one of these?

      -

      Alex: There are two main scenarios for creating a pull request. You are either creating it from a branch within the same repository, or you are creating it from a fork.

      -

      Jamie: Let us define those. A branch in the same repository is what we do at my company. We all have write access to the main repository, so I just create a branch called jamie dash new dash feature, do my work, and open a pull request.

      -

      Alex: Right. The analogy there is that you and your team all live in the same house. You are building a new cabinet in the garage, which is your branch. When it is done, you ask your roommates to help you move it into the living room, which is the main branch.

      -

      Jamie: But open source does not work like that, right? I cannot just go create a branch on the official Microsoft accessibility repository. They do not know me. They are not going to give me write access to their house.

      -

      Alex: Exactly. That is where forks come in. A fork is a complete, personal copy of someone else's repository that lives on your own GitHub account. You have full control over your fork. You can create branches there, commit code there, and break things there.

      -

      Jamie: So if the same repository branch is building a cabinet in the garage, a fork is building the cabinet at my own house across town.

      -

      Alex: Yes. And when the cabinet is finished, you load it into a truck, drive it over to the open source project's house, and submit a pull request asking if they want it. That is a cross-repository pull request. The beauty of GitHub is that the creation process is almost identical for both.

      -

      Jamie: When you push a new branch to GitHub, whether it is to your fork or the main repository, GitHub is pretty smart. If you navigate to the repository homepage shortly after pushing, you will usually find a banner with a button that says Compare and pull request. I just press Enter on that button.

      -

      Alex: That button is a fantastic shortcut. If you do not catch the banner in time, you can always navigate to the Pull requests tab and activate the New pull request button. When you do that, you have to select two things from a set of dropdown menus. The base branch, and the compare branch.

      -

      Jamie: I always used to mix those up. Base and compare.

      -

      Alex: It helps to read it as a sentence. You want to merge your compare branch into the base branch. The base is the foundation. It is the destination. Usually, this is the main branch of the project. The compare branch is your new work. You are asking GitHub to compare your work against the base.

      -

      Jamie: Once you select those, you land on the pull request form, which looks exactly like the form for creating a new issue. You have a title field and a description text area.

      -

      Alex: Writing a good pull request description is an art form. This is your chance to explain what changed, why it changed, and how the reviewer can test it.

      -

      Jamie: Please, please do not just name your pull request Fix bugs, and leave the description blank. I have been asked to review pull requests like that, and it is infuriating. I have no idea what I am supposed to be looking at.

      -

      Alex: A good title should be descriptive. Something like, Add keyboard navigation for the carousel component. For the description, many repositories provide a pull request template. If you tab into the description field and switch to Focus mode, you might find a checklist already waiting for you.

      -

      Jamie: If there is no template, I always try to include three things. First, a summary of what I did. Second, instructions on how to test my changes. And third, a link to the original issue.

      -

      Alex: Linking the issue is critical. If your pull request solves issue number forty two, you should type the word Closes, followed by a space, followed by the number sign, and the number forty two. Closes number forty two.

      -

      Jamie: GitHub has a magic feature where if you use that exact phrasing, the moment your pull request is merged, GitHub will automatically close issue forty two for you. It keeps the project so tidy.

      -

      Jamie: Okay, so what if I am working on that carousel keyboard navigation, and I have made some good progress, but I am stuck. The escape key is not closing the modal. I want to push my code and get your opinion, but I do not want you or the project maintainers to accidentally merge it, because it is broken.

      -

      Alex: This is the perfect time to use a draft pull request. A draft pull request is a way of putting a big, virtual Work In Progress sign on your code. It signals to the team that you are actively working on it, it allows you to ask for feedback, but the merge button is completely disabled. No one can merge it, not even the repository owner.

      -

      Jamie: How do I create a draft?

      -

      Alex: When you are on the form to create a new pull request, do not just activate the default Create pull request button. Next to it, there is a dropdown arrow button. If you activate that, you can select Create draft pull request instead.

      -

      Jamie: And when I finally figure out that escape key bug and I am ready for a real review, how do I remove the draft status? Do I have to open a new pull request?

      -

      Alex: Not at all. You just open your existing draft pull request, navigate to the Conversation tab, and scroll toward the bottom. You will find a button called Ready for review. Activating that button removes the draft status, turns on the merge button, and notifies everyone that you are ready for formal feedback.

      -

      Jamie: That is a relief. Okay, so my pull request is out of draft mode. It is open. But no one is looking at it. How do I get someone's attention?

      -

      Alex: You need to request a review. On the pull request page, there is a sidebar region. You can navigate to the Reviewers heading, which is a level three heading. Right below that, there is a button to request reviewers. Activating it opens a search field where you can type a teammate's username and select them.

      -

      Jamie: Sometimes I will open a pull request and I will notice that two people have already been requested as reviewers, and I did not even do it. It just happened automatically.

      -

      Alex: That is usually because of a file called CODEOWNERS. Many large repositories use this file to map specific folders to specific people. If you modify a file in the accessibility folder, GitHub automatically requests a review from the accessibility team. You cannot remove them; their approval is required.

      -

      Alex: So far, we have been the author. Now, let us flip the script. Jamie, I just requested your review on my pull request. You get an email notification, you follow the link, and you are on my pull request page. What is your workflow?

      -

      Jamie: The first thing I do is read your description on the Conversation tab so I know what you are trying to achieve. But then, I immediately move to the Files changed tab. That is where the truth is. The description is what you think you did. The Files changed tab is what you actually did.

      -

      Alex: And this is where we need to talk about screen reader navigation, because reading a code diff can be intimidating at first. When you activate the Files changed tab, GitHub presents a file tree on the left, and the actual diffs on the right.

      -

      Jamie: I love the file tree. I press D to navigate to the File tree region. It is a list of every file you modified. I can use my up and down arrows to hear the file names. It gives me a high level map of the damage you did to the codebase.

      -

      Alex: Once you are ready to read the code, you can use heading navigation. Every changed file is a level three heading. So you can press the number 3 to jump from file to file.

      -

      Jamie: When I land on a file heading, how do I actually read the changes?

      -

      Alex: Each file's diff is structured as an HTML table. So, from the file heading, press T to jump into the diff table. Then, switch your screen reader to Focus mode, or Forms mode. If you are using NVDA, that is Insert plus Space. For JAWS, it is Insert plus Z. For VoiceOver, you interact with the table.

      -

      Jamie: Once I am in the table in Focus mode, I just use my down arrow to read line by line.

      -

      Alex: Exactly. And the screen reader will announce the changes. Because we cannot rely on the visual layout, we listen for specific prefixes. If a line was added, your screen reader will announce a plus sign, or the word inserted, followed by the code. If a line was removed, it will announce a minus sign, or the word deleted.

      -

      Jamie: And if a line has no plus or minus, it is just context. It is unchanged code that GitHub shows you so you know where you are in the file.

      -

      Alex: So you are arrowing down through the table, and you hear a minus sign followed by an old heading level, and then a plus sign followed by a new heading level. You realize I made a mistake. How do you tell me?

      -

      Jamie: I leave an inline comment. This is so much better than just leaving a generic comment at the bottom of the page saying, hey Alex, on line forty two of that one file, you messed up. Instead, while my focus is on the specific line in the diff table, I press the Tab key.

      -

      Alex: When you press Tab from a focused line in the diff table, you will land on a button called Add a comment to this line.

      -

      Jamie: I press Enter on that button, and a text area opens right there in the middle of the code. I switch back to Focus mode, and type my comment. I will say, Alex, this heading level skips from a level two to a level four. We need a level three here for screen reader users.

      -

      Alex: Now, this next part is crucial. Once you type your comment, you will see two buttons. One says Add single comment. The other says Start a review. Always, always choose Start a review.

      -

      Jamie: I learned this the hard way! When I first started, I was using Add single comment for everything. I reviewed a massive pull request and left twenty inline comments.

      -

      Alex: And because you used Add single comment, GitHub sent the author twenty separate email notifications, one after another. Ding, ding, ding.

      -

      Jamie: They were not happy with me. When you choose Start a review, GitHub saves your comment as pending. It batches them all together. You can go through the rest of the files, leave five more comments, and the author hears nothing.

      -

      Alex: Once you have finished reading all the files and leaving your pending comments, you need to submit the review. You navigate to the Review changes button. It is usually at the top of the Files changed tab, or at the bottom of the Conversation tab.

      -

      Jamie: When you activate the Review changes button, a dialog opens. You can type an overall summary, like, Great work, just a few heading issues to fix. And then you have to choose a verdict using a set of radio buttons.

      -

      Alex: The three radio buttons are Comment, Approve, and Request changes. Comment means you are just leaving general feedback, but you are not blocking the merge. Approve means the code looks great and you are giving it a green light. Request changes means you found a blocking issue, and the pull request cannot be merged until the author fixes it.

      -

      Jamie: I select Request changes, tab to the Submit review button, and press Enter. At that exact moment, GitHub bundles all my inline comments and my summary into one single email notification and sends it to you.

      -

      Alex: It is a much kinder workflow. Now, I want to take a brief detour, because there is an alternative way to review code that is incredibly popular among screen reader users.

      -

      Jamie: Yes! VS Code!

      -

      Alex: Right. Reading diffs in a web browser table works, but it can be tedious. If you use Visual Studio Code and install the GitHub Pull Requests extension, you can check out the pull request locally.

      -

      Jamie: And the best part of doing it in VS Code is the Accessible Diff Viewer. When you have a diff open in VS Code, you just press F 7.

      -

      Alex: F 7 opens a dedicated panel designed specifically for screen readers. Instead of making you navigate a complex table, it extracts every change into a linear list. You just press F 7 to jump from change to change.

      -

      Jamie: It is so clean. It literally announces, Change one of three. Removed, heading level two. Added, heading level three. It takes all the mental gymnastics out of reading a diff. You can still leave inline comments right from VS Code, and they sync perfectly back to GitHub.

      -

      Alex: It is a phenomenal feature. Another alternative, if you are a terminal power user, is the GitHub CLI. You can type g h space p r space list to see all open pull requests. You can type g h space p r space diff to output the code changes straight to your terminal, which is very easy for a screen reader to read sequentially. You can even approve a pull request by typing g h space p r space review dash dash approve.

      -

      Jamie: I love having options. Browser, VS Code, or Terminal. You use whatever fits your brain best.

      -

      Alex: Okay, so let us look at the timeline. I opened the pull request. You reviewed it and requested changes. I fixed the heading levels and pushed a new commit. You reviewed it again, and this time, you selected Approve. Are we ready to merge?

      -

      Jamie: Almost. We have to check the bots first.

      -

      Alex: Ah yes, the Status Checks. On the Conversation tab, right below the description, there is a section for status checks. These are automated scripts that run every time you push code. They might run accessibility linters, unit tests, or security scanners.

      -

      Jamie: You can navigate to the Status checks heading to read the results. You want to hear All checks have passed. If you hear Some checks failed, the merge button might be blocked. You have to navigate to the specific failing check, open its logs, and figure out what broke.

      -

      Alex: Assuming your review is approved and all status checks have passed, it is time to merge. If you are a project maintainer, you will navigate to the bottom of the Conversation tab to the merge controls. But you have a choice to make. There are three different merge strategies.

      -

      Jamie: This used to terrify me. The dropdown gives you three options: Create a merge commit, Squash and merge, or Rebase and merge. What is the difference?

      -

      Alex: Let us use an analogy. Imagine your pull request is a business trip, and your commits are the receipts. You have a commit for your flight, a commit for your hotel, a commit for a coffee, and a commit where you bought a pen.

      -

      Jamie: Okay, I have four commits. Four receipts.

      -

      Alex: If you choose Create a merge commit, you are taking all four individual receipts, putting them in an envelope, writing Business Trip on the envelope, and handing it to accounting. The main branch keeps every single commit exactly as you wrote it, plus one extra commit, the envelope, that ties them together.

      -

      Jamie: So the history shows all the messy details. The coffee, the pen, everything.

      -

      Alex: Right. The second option is Squash and merge. If you choose squash, you take all four receipts, add up the total, throw the individual receipts in the trash, and hand accounting a single piece of paper that says Business Trip Total: eight hundred dollars.

      -

      Jamie: Oh, I see. It squashes all my messy, incremental commits into one single, polished commit on the main branch. I use this all the time because my commit history is usually terrible. I will have commits named oops, and fixed typo again. Squashing hides my shame.

      -

      Alex: Exactly. Squash and merge keeps the main project history incredibly clean. One pull request equals one commit.

      -

      Jamie: What about Rebase and merge?

      -

      Alex: Rebase is like a time machine. Imagine you started your business trip a month ago, but accounting only wants receipts from this week. Rebase takes your four individual receipts, erases the dates, and stamps today's date on all of them. It replays your commits one by one onto the tip of the main branch, as if you had just written them today.

      -

      Jamie: No envelope, no squashing. Just taking my work and sticking it perfectly at the end of the line.

      -

      Alex: Exactly. Which strategy you use depends on the repository. Many open source projects enforce Squash and merge to keep their history readable. Just check the dropdown, select the strategy the project prefers, and activate the button.

      -

      Jamie: And just like that, the pull request status changes to Merged. The code is officially part of the project.

      -

      Alex: We have covered the entire lifecycle of a pull request today. Let us recap the key takeaways. First, a pull request is a proposal to merge code, while an issue is a discussion about work to be done.

      -

      Jamie: Second, use Draft pull requests when your work is not ready for review. It tells the team you are experimenting, and prevents accidental merges.

      -

      Alex: Third, when reviewing code in the browser, use the T key to jump to the diff table, and use Focus mode to read the changes line by line. Listen for the plus and minus announcements. And remember, always use Start a review to batch your inline comments, rather than sending a notification for each one.

      -

      Jamie: And finally, do not forget about the F 7 Accessible Diff Viewer in VS Code. If navigating browser tables is giving you a headache, the VS Code extension is an absolute game changer for screen reader users.

      -

      Alex: In our next episode, we are going to tackle the one topic that strikes fear into the heart of every developer, blind or sighted. We are going to talk about Merge Conflicts. What they are, why they happen, and how to resolve them accessibly without panicking.

      -

      Jamie: I have panicked many times. I am looking forward to learning how not to.

      -

      Alex: Until then, keep exploring, keep committing, and we will see you next time on Gitt Going with GitHub.

      +

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

      +
      +

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

      +
      +

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

      +
      +

      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 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: 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: 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: 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 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 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: 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 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 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. 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: 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 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 6. Next in the series is episode 7, where we keep building the same contributor muscles.

      - +

      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)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 7: Merge Conflicts Are Not Scary

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub, the audio series for blind and low-vision developers learning the ins and outs of open source collaboration. I am Alex, and I am here with Jamie.

      -

      Jamie: Hi everyone! I am so ready for this one.

      -

      Alex: Today we are on episode seven, and the title of this episode is Merge Conflicts Are Not Scary.

      -

      Jamie: I am going to hold you to that title, Alex. Because when I was learning GitHub two years ago, the phrase merge conflict literally made my stomach drop. It sounds like an error. It sounds like I broke the project and now the developers are fighting.

      -

      Alex: That is exactly why we named the episode this way. A merge conflict is not an error, it is not a failure, and it definitely does not mean anyone is fighting. It is just a normal, everyday part of writing code with other people. Before we dive into what they are, let us quickly recap where we are in the workflow. In episode three, we talked about branches and commits, which is how you save your own independent line of work. Then in episode six, we talked about pull requests and merging, which is how you ask to bring your work into the main project.

      -

      Jamie: Right. A pull request is you saying, here are my changes, please pull them into the main branch. And usually, you hit the merge button, and GitHub just combines everything perfectly.

      -

      Alex: Exactly. Git is incredibly smart. If you edit a file at the top, and I edit the same file at the bottom, Git just quietly combines them. No problem. But a merge conflict happens when two people change the exact same lines of the exact same file in different ways. Git is smart, but it is not going to guess which version is the correct one. So it stops and asks a human to decide.

      -

      Jamie: I always think of it like two people editing the same paragraph of a shared document. Let us say we have a workshop welcome document. I go in and change the opening sentence to say, Welcome to the GitHub Workshop. But before I save and share my version, you go in and change that exact same sentence to say, Welcome Developers. If we try to combine our documents, the system throws its hands up. It cannot keep both sentences without it sounding like nonsense, and it does not want to automatically delete someone's work.

      -

      Alex: That is a perfect analogy. Git is doing the exact same thing. It is pausing the merge and saying, hey, I have two different versions of line twelve. Which one do you want? Or do you want to combine them yourself? That pause, that request for human intervention, is all a merge conflict is.

      -

      Jamie: Okay, so it is not an error. It is just Git asking a question. But how does it actually ask? When I am working on a pull request, how do I even know a conflict happened?

      -

      Alex: If you are on the GitHub website, navigating through your pull request, you will move to the Conversation tab. Usually, at the bottom of that tab, you find the button to merge your pull request. But if there is a conflict, that merge button will be disabled. Instead, your screen reader will announce a section that says, this branch has conflicts that must be resolved.

      -

      Jamie: I remember hearing that for the first time. It feels like a roadblock. But right next to that message, there is a button called Resolve conflicts.

      -

      Alex: Yes. And activating that Resolve conflicts button takes you into the GitHub web editor. This is a built in tool that lets you fix the conflict right there in your browser, without needing any terminal commands or local software.

      -

      Jamie: So what actually happens when I activate that button? I know it opens an editor, but what does the text inside look like? How does Git show me the two different versions?

      -

      Alex: This is where we need to talk about conflict markers. When Git finds a conflict, it actually edits the file for you to inject both versions of the code, separated by very specific markers. These markers are just plain text characters.

      -

      Jamie: And they can sound really weird the first time a screen reader reads them out to you.

      -

      Alex: They really can. There are three markers you need to know. The first marker indicates the start of your version of the code. It is seven less than signs, followed by a space, and the word HEAD. H E A D.

      -

      Jamie: So your screen reader might literally say, less than less than less than less than less than less than less than HEAD. Or if your punctuation level is set lower, it might just say HEAD. That is why it is good to navigate line by line and examine the characters if something seems strange.

      -

      Alex: Exactly. The word HEAD in Git just means your current location, the branch you are currently working on. So right below that less than HEAD marker, you will find your code. The code you wrote.

      -

      Jamie: Okay, so that is my version. What comes next?

      -

      Alex: Next is the dividing line. It is seven equals signs. Just a row of equals signs. This separates your version from the other person's version.

      -

      Jamie: Equals equals equals equals equals equals equals. Got it. And below the equals signs?

      -

      Alex: Below the equals signs is the incoming version. The code coming from the main branch, or from whoever else edited the file. And finally, to mark the end of the conflict area, there is a third marker. It is seven greater than signs, followed by a space, and the name of the branch that the incoming code is coming from.

      -

      Jamie: So greater than greater than greater than, and then maybe the word main, or the name of my teammate's feature branch.

      -

      Alex: Exactly. So the structure is always the same. Less than signs for the start of your code. Your code. Equals signs for the divider. Their code. Greater than signs for the end of the conflict.

      -

      Jamie: So let us make this concrete. Imagine we are editing an HTML file. I am working on a button. Originally, the button just said Submit. On my branch, I changed the button text to say Send message. But someone else on the team added an accessibility label to the original button. They added an aria label that says Submit form.

      -

      Alex: That is a very realistic scenario. Since you both changed the exact same line of HTML, you get a conflict. When you open the web editor and navigate line by line, here is what you will read. First, the less than signs and the word HEAD. Next line, your code, which is the button with the text Send message. Next line, the seven equals signs. Next line, the incoming code, which is the button with the aria label Submit form. And finally, the greater than signs and the branch name.

      -

      Jamie: So my job is to just edit this text file, right?

      -

      Alex: That is the entire job. You are just in a text editor. You need to look at both versions and decide what the final code should be. In this case, you probably want both improvements. You want the new text, and you want the aria label.

      -

      Jamie: So I would just type out a new line of code that combines them. A button with the aria label Submit form, and the text Send message.

      -

      Alex: Perfect. And then, this is the most important part, you must delete the conflict markers. You have to delete the line with the less than signs, the line with the equals signs, and the line with the greater than signs. You also delete the old versions of the code that you no longer need. When you are done, the file should just look like normal, working code.

      -

      Jamie: That is a huge aha moment for a lot of people. The markers are not special protected code. They are literally just text that Git temporarily typed into your document so you could find the conflict. You just delete them when you are done.

      -

      Alex: Exactly. Once you have deleted the markers and the code looks correct, you navigate to the top of the file in the GitHub web editor and activate the Mark as resolved button. If you have multiple files with conflicts, there is a file navigation panel you can reach with your screen reader commands, like N V D A plus F seven, or VoiceOver plus U, to move to the next file. Once all files are marked as resolved, you activate the Commit merge button. And you are done. The conflict is gone.

      -

      Jamie: Okay, that is the web editor. But what if I am working locally on my own computer, using the command line? I know a lot of developers prefer to handle things in their terminal.

      -

      Alex: The concept is exactly the same, but the steps are a bit different. Let us say you are in your terminal and you type git space merge space main, to bring the main branch into your feature branch. Git will try to merge, but then it will output a message that says, Automatic merge failed. Fix conflicts and then commit the result.

      -

      Jamie: Hearing automatic merge failed definitely sounds scary the first time.

      -

      Alex: It does! But again, it is just Git saying it needs a human. If you type git space status, it will list your files and tell you which ones are in conflict. It will say, both modified, and then the file name.

      -

      Jamie: So if I see both modified, I just open that file in my normal code editor, like VS Code or Notepad?

      -

      Alex: Exactly. You open the file, and you will find those exact same conflict markers. The less than signs, the equals signs, and the greater than signs. You edit the text, combine the changes, and delete the markers, just like we discussed.

      -

      Jamie: And since I am doing this on the command line, how do I tell Git that I finished fixing it? There is no Mark as resolved button in my terminal.

      -

      Alex: Great question. On the command line, marking a file as resolved is done by staging it. You just type git space add space, and then the file name. That tells Git, hey, I fixed this file, it is ready to go. Once you have used git add on all the conflicted files, you just type git space commit. Git will automatically create a message saying it is a merge commit, and you just save and close it.

      -

      Jamie: So the workflow is git merge, which triggers the conflict. Then git status to find the files. Open the files and delete the markers. Then git add to mark them as resolved. And finally git commit to seal the deal.

      -

      Alex: You got it. And for those of you who will be using VS Code on day two of the workshop, it gets even easier. VS Code has built in tools for this. When you open a conflicted file, it adds invisible action links right above the conflict, which you can reach by pressing Tab. These links are called CodeLens actions.

      -

      Jamie: Oh, I love CodeLens. It is so much faster.

      -

      Alex: It really is. Your screen reader will read options like Accept Current Change, which keeps your code. Accept Incoming Change, which keeps their code. Or Accept Both Changes. You just press Enter on the one you want, and VS Code automatically deletes the markers and formats the code for you. You just save with Control plus S, stage the file with Control plus Shift plus G, and commit.

      -

      Jamie: And if you are using GitHub Copilot, you can press Control plus Shift plus I to open Copilot Chat and ask it to explain the conflict to you. You can say, explain what these two changes are trying to do. But a quick warning here, you should always understand how to read the markers yourself before relying on AI. You need to verify that the final code actually makes sense.

      -

      Alex: Absolutely. Now, before we move on, I want to mention a couple of really handy commands if you are using the GitHub Command Line Interface, or the G H tool. Sometimes you want to check if a pull request has conflicts before you even try to merge it.

      -

      Jamie: Right, because maybe I am reviewing someone else's pull request from my terminal.

      -

      Alex: Exactly. You can type the command G H space P R space checks, followed by the pull request number. This will tell you the status of the pull request. You can also type G H space P R space view, which will output a summary, and it will clearly state if the branch has conflicts that must be resolved. If you want to see the actual changes, G H space P R space diff will show you line by line what was added and removed.

      -

      Jamie: That is super helpful for staying in the terminal and not having to bounce back and forth to the browser just to check the status.

      -

      Alex: So we have talked about how to resolve conflicts. But there is a famous saying in software development. Prevention is easier than resolution.

      -

      Jamie: Yes! Let us talk about how to avoid these in the first place. Because while they are not scary, they do take time to fix. What is the best way to prevent merge conflicts?

      -

      Alex: The number one rule is to keep your branches short lived. If you create a branch and work on it for three weeks without merging it, the main branch is going to change dramatically in that time. When you finally try to merge, you are going to have a massive conflict.

      -

      Jamie: So target one to three days. Keep your changes small and focused. If you are building a huge feature, break it down into smaller pull requests. A pull request that changes five files merges easily. A pull request that changes fifty files is almost guaranteed to conflict with something.

      -

      Alex: Rule number two is to sync with the main branch frequently. If you are working on a branch for a few days, start your morning by pulling the latest changes from main into your branch. You can do this with git space pull space origin space main. This brings in everyone else's approved work. If there is a small conflict, you catch it early and fix it locally, rather than waiting until the very end.

      -

      Jamie: I also want to add communication to this list. Especially in our workshop environment. If you know you are going to be editing the workshop welcome document, leave a comment on your issue saying, heads up, I am working on the welcome document today. That way, if another student is also assigned a challenge that touches that file, they can coordinate with you.

      -

      Alex: Communication is huge. Another common trap is mass reformatting. Let us say you open a file and notice the indentation is a bit messy, so you run a tool that reformats all five hundred lines of the file.

      -

      Jamie: Oh no. I have done this.

      -

      Alex: We all have! The problem is, Git sees that as you changing all five hundred lines. If anyone else on your team changed even one line of logic in that file, you will create a conflict. If you need to reformat a file, do it in a separate, dedicated pull request, announce it to your team, and get it merged immediately before anyone else does work in that file.

      -

      Jamie: That makes so much sense. What about fast forward merges? I have heard that term thrown around.

      -

      Alex: A fast forward merge is the ideal scenario. It happens when your branch is perfectly up to date with main, and you just added new commits on top. Because there are absolutely no diverging changes, Git does not even need to create a merge commit. It just fast forwards the main branch to point to your latest commit. Zero chance of conflicts. You can achieve this by rebasing your branch on main right before you merge, but rebasing is an advanced topic that rewrites history, so we will save the deep dive on that for another time.

      -

      Jamie: Okay, Alex. I have tried to keep my branches small. I tried to communicate. But I still got a massive conflict, and I am sitting here looking at a file with ten different conflict markers, and I honestly do not understand what the incoming code is trying to do. I am stuck. What do I do?

      -

      Alex: The first thing you do is take a breath. The second thing you do is ask for help. It is completely normal and expected to ask for help with a merge conflict. You can go to your pull request on GitHub, leave a comment, and tag the author of the incoming changes. You can say, hey, I have a merge conflict in the index file, and I am not sure which version to keep. Could you help me understand the intent of your changes?

      -

      Jamie: People love when you ask that, by the way. It shows you care about not breaking their code.

      -

      Alex: Exactly. And if the conflict is just completely overwhelming, maybe your branch is weeks old and everything has changed, there is always the nuclear option.

      -

      Jamie: The nuclear option?

      -

      Alex: Abandon the branch and start fresh.

      -

      Jamie: Oh, wow. Is that allowed?

      -

      Alex: It is absolutely allowed, and sometimes it is the smartest move. You just close your pull request without merging it. You switch back to the main branch, make sure it is up to date, and create a brand new branch. Then, you just manually apply your specific changes to the new branch. Sometimes copying your logic over to a fresh, up to date branch takes ten minutes, whereas untangling a massive merge conflict could take hours. Starting over is not a failure. It is a legitimate strategy.

      -

      Jamie: I love that. It takes so much pressure off. If I mess up resolving a conflict, or if it is too confusing, I can just close it and start over. I have not ruined the project.

      -

      Alex: You definitely have not. Your first conflict resolution is always the hardest. It feels abstract and dangerous. But once you resolve one, once you delete those less than and greater than signs and see your code merge successfully, you will realize it is just a text editing puzzle.

      -

      Jamie: This has been incredibly helpful. Let us wrap up with some concrete takeaways for everyone listening.

      -

      Alex: Takeaway number one. A merge conflict simply means two people changed the same lines of the same file, and Git needs a human to pick the correct version. It is normal, healthy collaboration.

      -

      Jamie: Takeaway number two. Conflict markers are just text injected into your file. Less than signs for your code, equals signs for the divider, and greater than signs for the incoming code. Your only job is to edit the text to look how you want, and delete the marker lines.

      -

      Alex: Takeaway number three. You can resolve conflicts right in the browser using the GitHub web editor, or locally using git status, git add, and git commit. If you use VS Code, take advantage of the CodeLens features to accept changes with a single keystroke.

      -

      Jamie: And takeaway number four. Prevention is the best medicine. Keep your pull requests small, sync with the main branch frequently, and communicate with your team about what files you are touching. And if you get stuck, it is always okay to ask for help or just start a fresh branch.

      -

      Alex: Perfectly summarized. That is all for episode seven. In our next episode, we are shifting gears to talk about Culture and Etiquette. We will cover how to write a great issue, how to review someone else's code kindly, and the unwritten rules of open source communication.

      -

      Jamie: I cannot wait for that one. See you all next time!

      -

      Alex: Thanks for listening to Gitt Going with GitHub. Happy coding.

      +

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

      +
      +

      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 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 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: 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: 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: 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).

      +
      +

      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 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 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. 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 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 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 7. Next in the series is episode 8, where we keep building the same contributor muscles.

      - +

      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)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 8: Open Source Culture and Etiquette

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is Episode 8: Open Source Culture and Etiquette. I am Alex, and today we are shifting gears. Over the past few episodes, we have covered the mechanical side of GitHub. We talked about branches, commits, pull requests, and resolving merge conflicts. But today, we are focusing on the human side of open source software.

      -

      Jamie: Hi everyone, Jamie here. And I have to admit, this is the topic that intimidated me the most when I was learning GitHub two years ago. The terminal commands were tricky, sure, but the idea of talking to strangers on the internet, asking them to accept my code, and worrying I might say the wrong thing or break some unwritten rule? That was terrifying.

      -

      Alex: That is such a common feeling, Jamie. And it makes perfect sense. Technical skills get your code into a project, but communication skills are what keep you welcomed in the community. When you are contributing to open source, you are stepping into a pre-existing community. It is like walking into a crowded room where everyone already knows each other. You want to be polite, clear, and respectful. So today, we are going to demystify the unwritten rules of open source communication.

      -

      Jamie: I love that. Where do we start?

      -

      Alex: Let us start with the nature of the communication itself. Open source collaboration happens primarily in writing, asynchronously, and in public. Understanding those three characteristics shapes everything we do. Because we communicate entirely in writing, we have to think very carefully about how tone comes across in text without vocal cues.

      -

      Jamie: Right. There is no tone of voice, no body language, no immediate way to see if someone is confused or offended. It is like when you get a text message from a friend that just says, "Fine." with a period at the end. In person, they might say it with a smile, meaning "sounds good." But in text, that period makes it feel incredibly aggressive.

      -

      Alex: Exactly. A message that sounds perfectly neutral or just a bit brief in your head can read as hostile to the person on the other end. Sarcasm and irony are nearly impossible to convey safely, so it is best to avoid them entirely. The unwritten rule here is to be relentlessly explicit and assume good intent. Instead of saying, "This is problematic," you might write, "I think this approach might cause an issue with keyboard navigation because of the following reasons."

      -

      Jamie: And because it is asynchronous, you are not having a real-time chat. When I first started, I would leave a comment and just sit there waiting for a reply, getting anxious. But the maintainer might live on the other side of the world and be asleep.

      -

      Alex: Precisely. Comments are not instant messages. You might be in a rush, but the reader is not receiving that urgency from your message. This means you need to provide all necessary context in every single message. Do not assume continuity. If you solved a problem, do not just write "Fixed it." Explain what you fixed and how, because the person reading it tomorrow will not have the context of what you were doing today. And finally, remember that everything is in public. Write as if your most supportive mentor and your most critical reviewer are both reading your comments, because anyone on the internet can find them.

      -

      Alex: Now that we understand the environment, let us talk about the two main ways you will communicate: issues and pull requests. Let us start with writing a good issue description. Jamie, how would you define an issue?

      -

      Jamie: An issue is basically a ticket. It is how you report a bug, request a new feature, or ask a question about the project.

      -

      Alex: Perfect. And writing a good issue description comes down to three things: context, steps to reproduce, and expected versus actual behavior. Think of it like taking your car to a mechanic. If you just drop the car off and say, "It makes a noise," the mechanic has no idea where to start. But if you say, "When I am driving over forty miles per hour and I press the brake pedal, the front left tire makes a grinding noise," the mechanic can replicate the exact conditions to find the problem.

      -

      Jamie: That makes so much sense. So for a software bug, context means explaining your environment. Like, "I am using Windows Eleven, with the NVDA screen reader, on the latest version of Firefox."

      -

      Alex: Exactly. Then you list the exact steps to reproduce the problem. For example, "Step one: Navigate to the login page. Step two: Enter a valid username but leave the password field blank. Step three: Press the Submit button."

      -

      Jamie: And then the expected versus actual behavior. So I would say, "Expected behavior: The screen reader announces 'Password is required'. Actual behavior: The screen reader announces nothing, and focus is lost."

      -

      Alex: You nailed it. That level of detail saves the project maintainer hours of debugging time. Even if you do not know how to fix the bug yourself, writing an issue description that clear is a massive contribution to the project.

      -

      Jamie: Okay, so that is issues. What about writing a good PR description? Remind me, PR stands for pull request, right?

      -

      Alex: Yes. A pull request, and I love that name because you are literally requesting that someone pull your changes into their project. When you open a PR, you need to provide a description. A good PR description needs to answer three questions: what did you change, why did you change it, and how can the reviewer test it.

      -

      Jamie: I remember my very first PR. I fixed a typo in a documentation file. My description just said, "Fixed typo." I thought I was being efficient!

      -

      Alex: It is a common mistake! But remember, the maintainer might be reviewing twenty pull requests that day. A better description would be: "What: Fixed a spelling error in the installation guide. Why: The command to install the package was missing a letter, which caused an error when users copied and pasted it. How to test: Read the installation section and verify the command is now correct."

      -

      Jamie: That is so much better. It is like handing over your shift at a job. You do not just hand the next person the keys and walk away. You tell them what happened during your shift, why you made certain decisions, and what they need to check on next.

      -

      Alex: That is a brilliant analogy. And here is a quick tip for our listeners using screen readers. When you are writing these descriptions on GitHub, you are often typing the same phrases over and over. GitHub has a feature called Saved Replies. You can save text snippets and insert them into any comment box. You just navigate to the comment text area, activate the Saved Replies button in the toolbar, or press Control plus period, and you can filter through your saved templates. It is a huge accessibility win to avoid retyping standard issue formats.

      -

      Jamie: Okay, so we know how to write issues and pull requests. Let us talk about the rules of the community itself. When I look at an open source project, I almost always see a file called Code of Conduct. What exactly is that, and why does it exist?

      -

      Alex: The Code of Conduct is essentially the social contract of the project. It is the house rules for a community center. It outlines what behavior is expected and what behavior is unacceptable. It exists to protect contributors, especially those from marginalized groups, from harassment, discrimination, or abuse. When you see that file, it signals that the maintainers take community health seriously and that there is a formal process for reporting violations.

      -

      Jamie: It is reassuring to know it is there. And I imagine a big part of following the Code of Conduct is using inclusive language. Why does inclusive language matter so much in open source?

      -

      Alex: Open source is global. You are collaborating with people from different cultures, people who speak different languages, and people with different life experiences. Inclusive language ensures we do not accidentally alienate or demean anyone. For example, using words like "crazy" or "insane" to describe a piece of code can be stigmatizing. Instead, we can use precise words like "complex", "unpredictable", or "difficult to maintain."

      -

      Jamie: Oh, I have another example! When I was starting out, I hated reading documentation that said, "Obviously, you just run this command," or "Simply do this." When it did not work for me, or I did not understand it, the word "obviously" made me feel like I was stupid.

      -

      Alex: Yes! Words like "obviously", "simply", or "just" are alienating. What is obvious to a senior developer is not obvious to a beginner. The easiest fix is to just omit those words entirely. Instead of "Obviously, this function returns a string," you write, "This function returns a string." It is cleaner and kinder.

      -

      Jamie: Another thing I learned is to focus on the code, not the person. Instead of saying, "You made a mistake here," you say, "There is an error on line forty." It takes the ego out of it.

      -

      Alex: Exactly. Preferring the word "we" is also a great strategy. "We need to update this logic," rather than "You need to update this logic." It frames the project as a collaborative effort. And when it comes to inclusive commenting specifically for accessibility issues, precision is key. Do not generalize and say, "This website is completely unusable for blind people." That might not be accurate, and it can sound dismissive. Instead, represent the specific gap. Frame it as, "Because the submit button lacks an accessible name, users relying on screen readers cannot determine its purpose." Quote your exact screen reader output, and specify whether you are using JAWS, NVDA, or VoiceOver, because the experiences can differ.

      -

      Jamie: Let us move on to the part of open source that used to make me sweat: Code Review. This is when you submit your pull request, and other developers examine your code before it gets merged. How do we handle giving and receiving code review feedback gracefully?

      -

      Alex: Let us start with giving code review feedback. The golden rule is to be specific, be kind, and focus on the code. Think of yourself as a peer editor in a writing class, not a teacher grading a test. We teach a five-step anatomy for helpful feedback.

      -

      Jamie: I have my notes ready. What are the five steps?

      -

      Alex: Step one: Acknowledge what is working. Before identifying problems, name what is good. This is not empty flattery; most contributions have real strengths. Step two: Identify the specific concern. Vague feedback like "This is inaccessible" is useless. Be precise. Step three: Explain why it matters. Context turns a complaint into a lesson.

      -

      Jamie: Okay, so if I say, "This button has no accessible name," that is step two. Step three would be adding, "Without an accessible name, a screen reader will just announce 'button,' which gives the user no context."

      -

      Alex: Exactly. Step four is: Suggest a path forward. Offer an idea, like, "Something like an aria-label would work well here." And finally, step five: Signal the weight of the concern. Help the contributor understand if this is a hard blocker that must be fixed before merging, or just a minor preference.

      -

      Jamie: I see the word "nit" used a lot in reviews. Like N I T. What does that mean?

      -

      Alex: "Nit" is short for nitpick. It is a way of saying, "This is a very minor, optional suggestion. Feel free to ignore it." Like pointing out a trailing space or a slight formatting preference.

      -

      Jamie: Let us try an exercise. I am going to give you a harsh comment, and you rewrite it using those steps. Here is the comment: "This alt text is bad. Fix it."

      -

      Alex: Oh, that is a rough one. Okay, here is how I would rewrite it. First, acknowledge something good. "Nice catch adding this image, it really helps illustrate the step." Then, the concern and the why. "I noticed the alt text just says 'image one dot PNG'. Screen reader users will hear the filename instead of what is actually in the picture." Finally, the suggestion. "Could you describe what the screenshot shows, like 'Settings page with the Accessibility section expanded'? That way everyone gets the same information."

      -

      Jamie: Wow. If I received the first comment, I would want to quit the project. If I received your rewritten comment, I would feel encouraged and immediately know how to fix it.

      -

      Alex: That is the power of good communication. Now, let us talk about receiving code review feedback. The most important rule: do not take it personally.

      -

      Jamie: This was so hard for me! When I got my first PR reviewed, the maintainer left six comments requesting changes. I felt like I had failed. I thought, "Well, they hate my code, I am a terrible developer."

      -

      Alex: That is imposter syndrome talking. Code review is a normal, healthy part of the software development lifecycle. Even the most senior developers in the world get change requests on their pull requests. It is about making the code robust, not about judging your worth as a developer. When you receive feedback, take a breath. Look for the valid concern underneath the words. And always say thank you. When someone takes the time to review your work, acknowledge it.

      -

      Jamie: What if I disagree with the feedback? What if they tell me to change something, but I know my way is actually better for accessibility?

      -

      Alex: That is a great question. You need to know how to disagree respectfully. First, make your case once, clearly, and provide evidence. You might say, "I considered using an 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." You explain your choice.

      -

      Jamie: And if they still say no?

      -

      Alex: Then you have to accept that the maintainer has the final say in their project. It is their house. If you strongly disagree, the beauty of open source is that you can always fork the project and take it in a different direction. But fighting endlessly in a comment thread is not productive.

      -

      Jamie: Speaking of maintainers, I think it is important to talk about who these people actually are. When I started, I pictured a team of paid professionals sitting in a corporate office, waiting to review my code.

      -

      Alex: That is a very common misconception. The reality is that the vast majority of open source maintainers are volunteers. They have day jobs, families, and lives outside of GitHub. They are maintaining these projects in their spare time, out of passion or a sense of community. Understanding that maintainers are volunteers with limited time completely changes how you should interact with them.

      -

      Jamie: Right. It means practicing patience with response times. If you open a pull request on a Friday night, do not leave a comment on Saturday morning asking why no one has reviewed it yet.

      -

      Alex: Exactly. Think of it like a community garden. The people managing it are doing it because they love gardening, not because it is their full-time job. If you plant some seeds and ask the manager a question, you might have to wait until they come by on the weekend. If you have been waiting a week or two for a review on your PR, it is perfectly fine to leave a polite follow-up. You can simply say, "Hi, just checking in on this PR when you have a moment."

      -

      Jamie: What about asking questions? If I am trying to fix a bug and I get stuck, when is the right time to ask for help, and how should I frame it clearly?

      -

      Alex: You should always feel empowered to ask questions. The key is to show what you have already tried. Do not just say, "How do I fix this?" Instead, frame it clearly: "I am trying to fix the broken link on line twenty-four. I searched the repository for the correct URL, but I could not find a file at that path. Can you point me in the right direction?" This shows respect for the maintainer's time because you proved you tried to solve it yourself first.

      -

      Jamie: I like that. And I want to mention something called the "Good first issue" social contract. Many projects label certain issues as "good first issue" to welcome new contributors.

      -

      Alex: Yes, and those labels are fantastic. When a maintainer uses that label, they are signaling that they are willing to invest time in mentoring a beginner. But there is a contract there. If you want to work on it, you need to leave a comment claiming it, like, "Hi, I would like to work on this. Can I be assigned?"

      -

      Jamie: And then you wait for assignment! Do not just start coding. If two people work on it in parallel, someone's time gets wasted. And if you get stuck, or life gets busy and you cannot finish it, just tell them. Say, "Life got busy, you should reassign this." Do not just disappear.

      -

      Alex: That is professional etiquette at its finest. One final note before we wrap up today. Many of you might be using AI assistive tools, like GitHub Copilot or other agentic workflows, to help draft code or even draft review comments. Remember this: Accessibility Agents' outputs are your responsibility. If an AI drafts a triage reply or a code review for you, your name appears on it in the repository's public history. The agent writes it, but you publish it. Always review an agent-generated comment against the anatomy of helpful feedback we discussed today. Ensure the tone is kind, the language is inclusive, and it does not sound like a cold, automated robot. You are responsible for the culture you help shape.

      -

      Jamie: This has been such a great conversation, Alex. I feel like we have covered a lot of ground. What are the main takeaways our listeners should walk away with today?

      -

      Alex: I would boil it down to four concrete takeaways. First, open source communication is public, text-based, and asynchronous. Provide full context in your issue and PR descriptions, and do not rely on tone to convey your meaning. Be explicit. Second, when reviewing code, be kind and focus on the code, not the person. Use the five-step feedback anatomy: acknowledge, identify, explain, suggest, and signal.

      -

      Jamie: Third, do not take feedback personally. Everyone gets change requests on their pull requests. It is a collaborative process to make the software better. And fourth, remember that maintainers are usually volunteers. Be patient with response times, assume good intent, and respect the project's Code of Conduct.

      -

      Alex: Beautifully summarized, Jamie. Taking the time to master these communication skills will make you a highly valued contributor in any open source community. That is all for Episode 8. In our next episode, we will dive into project management on GitHub, specifically focusing on Labels, Milestones, and Projects. We will learn how repositories organize thousands of issues so nothing gets lost.

      -

      Jamie: I am looking forward to it. Until next time, happy collaborating!

      -

      Alex: Keep building, and we will catch you in the next episode of Gitt Going with GitHub.

      +

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

      +
      +

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

      +
      +

      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 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: 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: 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: 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 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). 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: 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 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. 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 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: 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 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. 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 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: 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 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. 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 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 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: 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 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: 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.

      - +

      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)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 9: Labels, Milestones, and Projects

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is episode nine, Labels, Milestones, and Projects. I am Alex, and I am here with Jamie.

      -

      Jamie: Hello everyone. If you have been following along, you know we have covered a lot of ground. Back in episode five, we talked about how to create and participate in issues. But today, we are tackling the big question. What happens when a repository has hundreds, or even thousands, of open issues? How do you keep track of it all?

      -

      Alex: That is exactly what we are focusing on today. Labels, milestones, and projects are the organizational layer of GitHub. They take a chaotic list of issues and pull requests and turn them into a structured, prioritized body of work. By the end of this episode, you will understand how to categorize work, group it into goals, and track it across your entire team.

      -

      Jamie: I remember the first time I landed on a popular open source repository. I opened the issues tab, and there were literally two thousand open issues. It was completely overwhelming. I had no idea what was being worked on, what was abandoned, or where I could even begin to help.

      -

      Alex: It is a very common experience. And that is why the first tool we are going to discuss is so important. Let us talk about labels. If we need a real world analogy, think of labels like the metadata tags on a blog, or the category tags you might use in your email inbox. They communicate at a glance what category, priority, or status an item belongs to.

      -

      Jamie: And just to be clear, GitHub provides a standard set of labels by default when you create a repository, right?

      -

      Alex: Yes, they do. When you start a new project, GitHub gives you a handful of universal labels. You will almost always see a label called bug, which means something is not working as expected. You will see enhancement, which means a new feature request. There is documentation, for changes that only affect the read me or help files.

      -

      Jamie: My personal favorite when I was starting out was the good first issue label. If you are learning a new codebase, filtering by good first issue is the best way to find a bug that the maintainers have specifically flagged as being suitable for a beginner.

      -

      Alex: Absolutely. There is also help wanted, which means the maintainers are actively seeking community help to solve a problem. And you will see labels for things that are not going to be fixed, like duplicate, invalid, or wont fix.

      -

      Jamie: So how does a screen reader actually handle these? Because if you ask a sighted developer, they will tell you that labels are color coded tags. The bug label is usually red, enhancement is blue, and so on. As a screen reader user, do I need to care about the colors?

      -

      Alex: Not at all. The color is strictly supplementary visual information. When you scan the issue list with your screen reader, the labels are announced right alongside the issue title. You will hear something like, Issue forty two, Add keyboard navigation to carousel, Labels: accessibility, good first issue. The text name of the label is what matters.

      -

      Jamie: That is a relief. So, if I want to see every label that exists in a repository, where do I go?

      -

      Alex: You will want to navigate to the Labels page. From the main page of a repository, you first navigate to the Issues tab. Once you are there, the Labels link is located in the filter toolbar, right above the main list of issues. For screen reader users, the quickest way is to press the letter K to navigate through the links on the page until you hear Labels. It is usually right next to the Milestones link. When you activate that link, you land on a page that lists every single label in the project, along with a text description of what it means.

      -

      Jamie: And if you prefer the command line, you can do this without ever opening your browser. You can open your terminal and type g h space label space list. It will print out every label and its description right there in your console. I use that all the time to quickly check if a repository has an accessibility label before I file a bug.

      -

      Alex: That is a great tip. Now, let us talk about how you actually apply a label to an issue or a pull request. Let us say you just created an issue about a broken button, and you want to label it as a bug.

      -

      Jamie: This was tricky for me at first because the label controls are not in the main content area with the issue text. They are tucked away in the right sidebar.

      -

      Alex: Exactly. When you have an issue open, you need to navigate to the sidebar. The easiest way to do this with a screen reader is to press the letter H, or the number 3, to jump by heading until you hear the heading called Labels. Right after that heading, there is a gear button, which might be announced as an edit button.

      -

      Jamie: And when you activate that gear button, a dropdown menu opens with a list of all the available labels. You can use your up and down arrow keys to move through them, and press Enter to select or deselect a label.

      -

      Alex: You can also just start typing when that dropdown opens. If you type the word bug, it filters the list instantly. You press Enter to apply it, and then press Escape to close the dropdown. The label is applied immediately. There is no separate save button you have to hunt for.

      -

      Jamie: And again, for my fellow terminal fans, the GitHub C L I makes this incredibly fast. If you want to label issue number forty two, you just type g h space issue space edit space forty two space dash dash add dash label, followed by the name of the label in quotes. You can even add multiple labels at once by separating them with a comma.

      -

      Alex: So now that we have labels on our issues, the real power comes from filtering. Let us go back to Jamie's earlier example of looking at a repository with two thousand open issues. You do not want to read all of them. You only want to read the ones labeled good first issue.

      -

      Jamie: Right. To do that, you navigate to the filter bar on the Issues page. You can usually jump straight to it by pressing the letter F. The filter bar is just a text input field. By default, it will probably say is colon open, which means it is only showing open issues. All you have to do is add a space, and then type label colon, followed by the label name. So, label colon quote good first issue quote. Press Enter, and suddenly those two thousand issues become a list of maybe ten highly relevant issues.

      -

      Alex: You can combine these too. You could type label colon accessibility, space, label colon bug. That will show you only the issues that have both of those exact labels applied.

      -

      Jamie: What if the default labels are not enough? In the hackathon we are running, we want to track issues that are blocked by external dependencies. There is no default label for that. Can we create our own?

      -

      Alex: Yes, as long as you have write access to the repository, you can create custom labels. You navigate back to that Labels page we discussed earlier. You tab to the New Label button and activate it. This opens a form with three fields. First is the label name, where you would type blocked. Second is the description, where you might type, waiting on external dependency.

      -

      Jamie: And the third field is the color, right? How does that work for us?

      -

      Alex: The color field will usually auto populate with a random hex code. You can completely ignore it if you want to, or you can type in a specific hex code if your team has a visual design system. But again, the color is purely visual. The name and the description are what make the label accessible and useful to everyone. Once you fill those out, you tab to the Create label button, press Enter, and your new label is ready to be used by anyone on the project.

      -

      Jamie: Okay, so labels help us categorize what an issue is. It is a bug, it is documentation, it is blocked. But what if we need to organize things by when they need to be finished? That brings us to our second topic, milestones.

      -

      Alex: Exactly. If labels answer the question of what, milestones answer the question of when. Milestones group issues and pull requests toward a shared goal or a deadline.

      -

      Jamie: I like to think of a milestone as a shipping container. You have a bunch of separate boxes, which are your issues. You load them all into the shipping container, which is the milestone. The ship cannot leave the dock until every box inside that container is packed and sealed. In software development, this usually represents a version release, like Version 2 point 0, or a time boxed sprint.

      -

      Alex: That is a perfect analogy. A milestone has a title, an optional description, an optional due date, and a progress bar. The progress bar tracks the percentage of closed issues versus the total number of issues assigned to that milestone.

      -

      Jamie: When you are on the issues page, you can press the letter K to find the Milestones link, right next to the Labels link we used earlier. If you activate it, you get a list of all the active milestones. And I love how screen readers announce this. You will hear something like, Hackathon Day 1 Deliverables, 3 of 8 issues closed, due April 20. It gives you the entire context in one sentence.

      -

      Alex: It is very efficient. If you press Enter on a milestone title, you open its detail page, which simply lists all the issues and pull requests assigned to it. You navigate that list just like any other issue list, pressing the number 3 to jump from issue title to issue title.

      -

      Jamie: So how do we actually put an issue into that shipping container? How do we assign it to a milestone?

      -

      Alex: The workflow is almost identical to applying a label. When you are looking at an issue, you navigate to the right sidebar. You press the number 3 or the letter H to jump to the Milestone heading. Right after that heading is the Milestone gear button. You activate it, use your arrow keys to select the correct milestone from the dropdown, and press Escape.

      -

      Jamie: I am guessing there is a command line equivalent for this too?

      -

      Alex: There is. You can use g h space issue space edit space forty two space dash dash milestone, followed by the milestone name in quotes. But there is a small catch with milestones and the C L I. While you can easily assign issues to a milestone using the C L I, there is no native command to create a brand new milestone from scratch. For that, you either need to use the web interface, or use the g h api command to make a direct web request, which is a bit more advanced.

      -

      Jamie: Good to know. So let us talk about creating a new milestone through the web interface. I know this has a specific accessibility quirk we need to discuss.

      -

      Alex: Yes, it does. To create a milestone, you navigate to the Milestones page, tab to the New Milestone button, and activate it. You fill in the title and the description just like a label. But then you reach the Due Date field.

      -

      Jamie: And date pickers on the web are notoriously frustrating with screen readers. Half the time, the calendar pop up traps your keyboard focus, or it does not announce the days of the week correctly.

      -

      Alex: Exactly. GitHub provides a calendar widget, but my strong recommendation is to ignore it completely. The due date field is a standard text input field. The most reliable, accessible way to set the date is to simply type it out in the standard format. Type the four digit year, a dash, the two digit month, a dash, and the two digit day. So, 2024 dash 10 dash 31. It works perfectly every time, and you never have to fight with the calendar widget. Tab to the Create milestone button, press Enter, and you are done.

      -

      Jamie: Alright, we have covered labels for categorization, and milestones for grouping things by a deadline. But both of those tools still just leave you with lists of issues. What if I want a bird's eye view of everything happening in my organization? What if I want to see who is working on what, what is in progress, and what is finished, all on one screen?

      -

      Alex: For that, you need GitHub Projects. GitHub Projects is a fully featured, built in project management tool. If you have ever used tools like Jira, or Trello, or Asana, GitHub Projects is built to do exactly that, but it lives right next to your code.

      -

      Jamie: And it is important to note that we are talking about Projects version 2 here. If you are reading older documentation, you might see references to classic projects. But the current version of Projects is incredibly powerful because a single project board can pull in issues and pull requests from multiple different repositories at the same time.

      -

      Alex: That cross repository tracking is huge. Imagine you maintain five different open source repositories. Instead of checking five different issue tabs every morning, you can create one organization level Project. You can set it up so that any issue created in any of those five repositories, if it has the bug label, automatically gets added to your central Project. It acts like a giant control tower for your whole ecosystem.

      -

      Jamie: That sounds amazing. But how do we actually read a project board with a screen reader? Because when I hear the word board, I think of a highly visual layout with cards scattered everywhere.

      -

      Alex: That is a very valid concern. GitHub Projects supports three different layouts, and you can switch between them depending on what works best for you. The layouts are Table, Board, and Roadmap. Let us break them down one by one, starting with the Table view.

      -

      Jamie: Table view is my absolute favorite. It basically turns your project into a giant spreadsheet. Each row is an issue or a pull request. And the columns are the data fields, like Title, Status, Assignee, Priority, and so on.

      -

      Alex: The Table view is highly optimized for keyboard navigation. When you load a project in Table view, you can press the letter T to jump your focus straight into the data grid. From there, you just use your arrow keys. You can press Control plus Alt plus Down Arrow to move down through the rows, hearing each issue. And you press Control plus Alt plus Right Arrow to move across the columns for that issue.

      -

      Jamie: So as I arrow across a row, my screen reader will say something like, Title: Fix keyboard trap. Column two, Status: In Progress. Column three, Assignee: Jamie. It is completely linear and incredibly fast to read. And if I want to change the status, I just press Space on the status cell, and a dropdown opens right there.

      -

      Alex: Exactly. It is essentially a fully accessible spreadsheet. Now, the second layout is the Board view. This is what people typically call a Kanban board. It organizes work into columns based on status. Usually, you have a To Do column, an In Progress column, and a Done column.

      -

      Jamie: This is where sighted users usually drag and drop cards from one column to another using their mouse. Obviously, drag and drop is not a great experience with a screen reader. So how do we move a card from To Do to In Progress?

      -

      Alex: GitHub has made this very straightforward. You do not need to drag and drop anything. Each column is marked as a region, so you can press the letter D, or use your screen reader's region navigation, to jump between To Do, In Progress, and Done. Once you are in a column, you press the number 3 to read the cards.

      -

      Jamie: And when I find the card I want to move?

      -

      Alex: You just press Enter on the card. This opens a detail panel on the right side of your screen. Inside that panel, there is a field called Status. You activate the status field, change it from To Do to In Progress, and press Escape. The card instantly moves to the correct column on the board. You are updating the underlying data, and the visual board simply updates to reflect your change.

      -

      Jamie: That is so much easier than trying to simulate a mouse drag. Just open the card, change the word, and close it. Okay, what about the third layout, the Roadmap view?

      -

      Alex: The Roadmap view is a timeline, often called a Gantt chart. It draws horizontal bars across a calendar to show when work starts and ends. It is heavily visual and is mostly used by project managers to plan capacity over months or quarters.

      -

      Jamie: To be honest, I rarely use the Roadmap view. Because all three views are just different ways of looking at the exact same data, I find it much easier to just switch back to the Table view. If I want to know the start and end dates of an issue, I just read the date columns in the table.

      -

      Alex: That is exactly the right approach. Treat the Roadmap as a visual summary for stakeholders, but use the Table view to actually read and edit your project data.

      -

      Jamie: So, how do I actually get my issues into this project? We talked about automation earlier, but what if I just want to add one specific issue manually?

      -

      Alex: You have two ways to do this. The first is from the issue itself. Just like labels and milestones, there is a Projects heading in the right sidebar of every issue. You press H to find it, activate the gear button, and select your project from the list.

      -

      Jamie: And the second way?

      -

      Alex: The second way is from inside the project board itself. At the bottom of the table or column, there is an Add Item button. If you activate it, a text field appears. You just type the pound sign, also known as the hash symbol, followed by a keyword from your issue title, or the issue number. A search dropdown appears, you select your issue, and it drops right into the project.

      -

      Jamie: I want to pause here and talk about how all three of these things, labels, milestones, and projects, fit together. Because when I first learned this, it felt like redundant work. Why do I need a milestone if I have a project board?

      -

      Alex: That is a great question, and it is the key to mastering GitHub organization. They are not redundant; they are complementary. Think of it like a sentence. Labels are the adjectives. They describe what the work is. It is an accessibility bug. Milestones are the deadlines. They describe when the work must be finished. It is due by the end of the hackathon. Projects are the map. They describe where the work currently is in the process. It is in progress, and assigned to Jamie.

      -

      Jamie: Oh, that is a great way to put it. And when you combine them, you can create incredibly powerful views. In my project board, I can create a filter that says, only show me issues where the label is accessibility, and the milestone is Hackathon Day 1. Suddenly, a chaotic repository becomes a highly focused to do list.

      -

      Alex: Exactly. And this is going to become critically important when we start talking about AI and Accessibility Agents later in the workshop. These labels and milestones are the exact language that automated workflows use to route work. If you do not apply labels properly, the automated agents will not know how to prioritize your issues. Labeling is not just overhead; it is how you program the project management system.

      -

      Jamie: This has been incredibly helpful. I feel like I finally have a mental model for how large open source projects actually function without collapsing into chaos.

      -

      Alex: It really is the secret to scaling collaboration. Let us recap the main takeaways from today's episode. First, labels are text based tags that categorize your issues. You apply them from the right sidebar of an issue, and you can use them in the filter bar to instantly narrow down your view.

      -

      Jamie: Second, milestones group issues together toward a shared deadline. The safest way to set a milestone due date with a screen reader is to ignore the calendar pop up and simply type the date in year, month, day format.

      -

      Alex: Third, GitHub Projects act as a central hub, pulling issues from multiple repositories into one view. You can navigate them seamlessly using the Table view, jumping to the grid with the letter T and moving through the data with Control plus Alt plus your arrow keys.

      -

      Jamie: And finally, do not try to drag and drop cards in a board view. Just press Enter to open the issue, change the status field in the sidebar, and let the board update itself.

      -

      Alex: Perfectly summarized. Now that you know how to organize work, you are going to want to know when people interact with that work. In our next episode, we are tackling one of the most requested topics: GitHub Notifications. We will show you how to tame your inbox, filter the noise, and ensure you never miss a mention.

      -

      Jamie: I cannot wait for that one. My inbox is currently a disaster zone. Thank you all for listening, and we will catch you in the next episode of Gitt Going with GitHub.

      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +

      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 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: 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: 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

      - - -

      Download Episode 10 (MP3)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 10: Notifications and Mentions

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is episode ten, Notifications and Mentions. I am Alex, and I am here to help you navigate the social and collaborative side of open source without getting completely overwhelmed by the noise.

      -

      Jamie: And I am Jamie. I am a blind developer who is still figuring out how to keep my digital life organized. I have to admit, Alex, the title of this episode gives me a little bit of anxiety. Notifications. Just the word makes me think of my phone buzzing non stop and an inbox with ten thousand unread messages.

      -

      Alex: That is a completely normal reaction, Jamie. In episode five, we talked about working with issues and commenting. Then in episode six, we covered pull requests and reviews. You have been putting your work out there, asking questions, and proposing changes. Now, the community is talking back. And when people talk back, GitHub generates notifications.

      -

      Jamie: It feels like a big transition. Going from being the person initiating the action, to being the person receiving all these updates. When I first started using GitHub about two years ago, I had this moment where I suddenly started receiving hundreds of emails a day from a repository I had visited only once. I thought I broke something.

      -

      Alex: You definitely did not break anything, but you did encounter one of the most common right of passage moments for new GitHub users. You probably accidentally subscribed to a very busy project. Today, we are going to make sure that never happens again. We are going to cover how GitHub generates notifications, the difference between participating and watching, how to manage your notification inbox, and how to use mentions to get someone else's attention.

      -

      Alex: Let us start with the core concept. How does GitHub decide to send you a notification in the first place? It all comes down to two concepts, participating and watching.

      -

      Jamie: Participating makes sense to me. If I am part of a conversation, I should probably know when someone replies.

      -

      Alex: Exactly. You are participating in a thread if you opened the issue or pull request, if you commented on it, or if someone explicitly assigned it to you. You are also participating if someone mentions your username directly. When you are participating, GitHub assumes you want to know how the story ends, so it subscribes you to that specific thread.

      -

      Jamie: So what is an analogy for that? Is participating like being on a group text message?

      -

      Alex: That is a perfect analogy. If you are on the group text, your phone is going to buzz when someone replies. But watching is completely different. Watching a repository is like installing a baby monitor in every room of a giant office building and piping the audio directly into your headphones.

      -

      Jamie: Oh wow. That sounds exhausting.

      -

      Alex: It really is, if you do it to the wrong repository. When you watch a repository, you are telling GitHub that you want to receive a notification for every single thing that happens in that project. Every new issue, every comment, every pull request, every automated test failure. For your own personal projects, watching is great. But for a massive open source project like Microsoft VS Code or the NVDA screen reader, watching means you will get thousands of notifications a week.

      -

      Jamie: That is exactly what happened to me! I thought I was bookmarking a repository so I could find it later. I navigated to the top of the repository page, found a button, and activated it. The next morning, my email inbox was completely destroyed.

      -

      Alex: I am so glad you brought that up, because new contributors constantly confuse watching with starring. They are two buttons located right next to each other at the top of every repository page. Let us clear up the difference right now. Starring a repository is what you actually wanted to do. Starring is like a public bookmark or a high five to the maintainers. It adds the project to a list on your profile, and it tells the creators that you like their work. Starring generates zero notifications.

      -

      Jamie: Zero notifications. That is beautiful. I wish I had known that.

      -

      Alex: Right. Starring is for bookmarking. Watching is for subscribing. By default, when you interact with a repository, your watch settings are set to participating and mentions. That is the sweet spot. It means you only hear about the things that actually involve you.

      -

      Jamie: But what if I do want to change my watch settings? Say I join a small team and I actually do need to know everything that happens in our team repository.

      -

      Alex: You can easily change your watch level. Navigate to the main page of the repository. If you are using NVDA or JAWS on Windows, you can press B to navigate through the buttons until you find the Watch button. Press Enter to open it. It is actually a drop down menu. Then use your up and down arrow keys to navigate the subscription options.

      -

      Jamie: And if I am using VoiceOver on a Mac?

      -

      Alex: With VoiceOver, you can use quick nav B to find the Watch button, then press VO plus Space to open the menu, use your arrow keys to find your preferred level, and press VO plus Space again to select it. The options you will hear are Participating and mentions, All Activity, Ignore, and Custom.

      -

      Jamie: Ignore sounds pretty intense.

      -

      Alex: Ignore is very useful if you are part of a massive organization and you are automatically subscribed to repositories you have nothing to do with. It completely mutes that repository. Custom is also great because it lets you get granular. You can say, only notify me when a new release is published, but ignore all the day to day issue comments.

      -

      Jamie: Okay, so we have covered how to control the fire hose of information. Let us talk about how we actually get someone else's attention. You mentioned that being mentioned makes you a participant. How does that work?

      -

      Alex: Mentions are how you tap someone on the shoulder in a crowded room. Anytime you are typing a comment in an issue, a pull request, or a discussion, you can type the at symbol followed by a person's GitHub username. For example, at Jamie blind dev. When you submit that comment, GitHub immediately sends a notification to that user, and it automatically subscribes them to that thread so they will see future replies.

      -

      Jamie: I love the shoulder tap analogy. It is literally requesting someone's specific attention. I use this a lot when I am stuck on a problem and I know exactly which developer wrote the code I am struggling with. I will drop a comment and mention them to ask for their input.

      -

      Alex: That is exactly what it is for. But there is a point of etiquette here. You should only tap someone on the shoulder if you actually need them. Tapping the lead maintainer of a huge project just to say hello or to ask them to look at your unrelated bug is generally frowned upon. Use mentions intentionally.

      -

      Jamie: That makes sense. What about when I need help from a group, but I do not know exactly who to ask? Like, I know the accessibility team needs to review my pull request, but I do not know the individual names of the people on that team.

      -

      Alex: That is where team mentions come in. It is a fantastic feature. Instead of mentioning a person, you can mention a whole team. The syntax is the at symbol, followed by the organization name, a forward slash, and the team name. So, at community dash access forward slash accessibility dash agents.

      -

      Jamie: Oh, that is clever. It is like using the public address system to page a specific department instead of paging one specific doctor.

      -

      Alex: Exactly. When you mention a team, GitHub sends a notification to everyone who is a member of that team. It is the best way to request a review from a specialized group without having to memorize everyone's individual usernames.

      -

      Jamie: Alright, so people are mentioning me, they are requesting my review, my automated continuous integration tests are failing and sending me alerts. Where does all this information go? Earlier I mentioned my email inbox getting destroyed. Is email the only way to manage this?

      -

      Alex: Email is one way, but it is rarely the best way. The problem with email is that GitHub notifications get mixed in with your bank statements, your newsletters, and messages from your family. It is too easy to lose context. The best way to handle this is the dedicated GitHub notification inbox.

      -

      Jamie: A dedicated inbox just for GitHub? Where do I find that?

      -

      Alex: You can navigate to github dot com forward slash notifications. But there is a much faster way. GitHub has a global keyboard shortcut for this. From almost anywhere on the GitHub website, you can press G then N.

      -

      Jamie: Let me clarify that for our screen reader users. When you say G then N, do you mean pressing them at the same time, like a chord?

      -

      Alex: Great question. No, it is a sequential shortcut. You press the letter G, release it, and then press the letter N. It stands for Go to Notifications. Just make sure you are in browse mode or reading mode, not focus mode, so your screen reader passes the keystrokes through to the browser.

      -

      Jamie: Okay, so I press G then N, and I arrive at the notification inbox. What is the layout of this page? I always find it helpful to understand the structure before I start arrowing around.

      -

      Alex: Structurally, the page has three main areas. On the far left, there is a sidebar with filters. In the center, taking up most of the page, is the notification list itself. And on the far right, there is a detail pane that shows a preview of whatever notification you have selected. Though, a quick tip, many screen reader users prefer to disable that right preview pane in their settings because it can make navigation a bit cluttered.

      -

      Jamie: I definitely turned that preview pane off. I prefer just a clean list. How do you recommend navigating the list itself?

      -

      Alex: The center list is grouped by date. So you will have a heading for Today, a heading for Yesterday, a heading for This Week, and so on. If you are using NVDA or JAWS, you can press the letter H to jump between these date headings. If you are using VoiceOver, make sure quick nav is on and press H.

      -

      Jamie: And once I am under a heading, like Today, how do I read the actual notifications?

      -

      Alex: This is a really important detail. Do not use your standard up and down arrow keys to read the list. The list is actually a complex interactive widget. The most reliable way to navigate it is to press the Tab key to move from one notification row to the next.

      -

      Jamie: What exactly does the screen reader announce when I tab to a notification row?

      -

      Alex: GitHub has done a lot of work to make this announcement comprehensive. When your focus lands on a row, you will hear four distinct pieces of information. First, the repository name. Second, the title of the issue or pull request. Third, the event type, which tells you why you received the notification, like review requested or mention. And fourth, the timestamp.

      -

      Jamie: So it might say something like, microsoft forward slash vscode, Add keyboard shortcut for accessible view, Jamie blind dev mentioned you, two hours ago.

      -

      Alex: Spot on. That single announcement gives you all the context you need to decide what to do next. And if you want to open that notification to read the full thread, you just press Enter. It will take you directly to the issue or pull request page, and it will automatically scroll your focus down to the exact comment that triggered the notification.

      -

      Jamie: Okay, so I tab to a notification, I hear what it is. Now I have to make a decision. This is where I struggle. I read it, but then it just sits in my inbox forever. How do I actually clear things out?

      -

      Alex: This brings us to inbox actions and keyboard shortcuts. The GitHub inbox is designed for rapid triage. You want to process these notifications like you process physical mail at your front door. You either throw it in the recycling, you file it away, or you open it immediately because it is urgent.

      -

      Jamie: I love that analogy. I am definitely a pile it on the kitchen counter kind of person, which explains my inbox. What are the shortcuts for processing the mail?

      -

      Alex: Once your focus is on a notification row, you have several single key shortcuts available. The most important one is the letter E. Pressing E marks the notification as done. It archives it and removes it from your inbox view.

      -

      Jamie: E for done. That is easy to remember. What if I want to keep it in my inbox, but I want to remember that I have already looked at it?

      -

      Alex: You can mark it as read without opening it by pressing Shift plus I. If you want to mark something as unread so it stays bold and catches your attention later, press Shift plus U.

      -

      Jamie: What if it is something really important that I need to work on tomorrow? Is there a way to pin it or save it?

      -

      Alex: Yes. Press the letter S to save it for later. This moves it to a special Saved filter in your sidebar, so it does not clutter your main inbox but it is securely filed away for when you have time.

      -

      Jamie: Okay, those are great. E for done, Shift plus I for read, S for save. But what about the opposite scenario? What if I am participating in a thread, maybe I left a tiny comment a month ago, and now two other developers are arguing back and forth with fifty comments a day. My inbox is filling up with their argument. How do I escape?

      -

      Alex: You need to mute the thread. This is a crucial survival skill. If you are focused on a notification row and you realize the conversation is no longer relevant to you, press the letter M. M stands for mute. It is the equivalent of silently leaving the group chat. You will not receive any more notifications for that specific issue or pull request, unless someone mentions your username directly.

      -

      Jamie: That is a lifesaver. M for mute. I am going to use that constantly. But what if I have already opened the issue? Do I have to go back to the inbox to mute it?

      -

      Alex: No, you can unsubscribe right from the issue page. Navigate to the right sidebar, find the section called Notifications, and activate the Unsubscribe button. It does the exact same thing as pressing M in the inbox.

      -

      Jamie: Let us talk about strategy. You mentioned earlier that some people have thousands of notifications. How do you personally manage your inbox without spending your entire day organizing it?

      -

      Alex: I am a big believer in the mark all as done workflow. When I come back from a long weekend, or if I just let things pile up, I do not process them one by one. I navigate to the top of the inbox, I find the filter field, and I type in the names of the repositories I care about the most.

      -

      Jamie: Wait, there is a search filter for the inbox?

      -

      Alex: Yes. At the top of the notification list, there is a text input field. You can navigate to it quickly by pressing the letter F for find, or E for edit, depending on your screen reader. You switch to focus mode, and you just type a repository name or an organization name. The list filters in real time to show only those notifications.

      -

      Jamie: Oh, that is incredibly powerful. So you filter for the important stuff first.

      -

      Alex: Exactly. I filter for my primary project. I read those, I reply to those, I press E to mark them done. Once I have handled the high priority items, I clear the filter by pressing Escape. Then, I tab to the button that says Mark all as done, and I press Enter.

      -

      Jamie: You just wipe out the rest of the inbox? Just like that?

      -

      Alex: Just like that. It clears everything. If I missed something truly critical, someone will mention me again. But realistically, most notifications are just conversational noise. If you try to read every single one, you will never get any actual coding done.

      -

      Jamie: That is incredibly liberating to hear from an experienced maintainer. It is okay to just let things go.

      -

      Alex: It is mandatory to let things go. You have to protect your focus. And speaking of protecting your focus, let us talk about the left sidebar filters. You can press the letter K to navigate through links, or just Tab to the sidebar. You will find filters like Unread, Saved, and Done. But the most powerful filters are Mentioned, Assigned, and Review requested.

      -

      Jamie: I can see why those are powerful. Those are the items that represent actual work waiting for me.

      -

      Alex: Exactly. If your inbox is overflowing, just activate the Review requested filter. That instantly narrows your view to only the pull requests where a teammate is literally blocked waiting for your approval. It cuts through all the noise.

      -

      Jamie: We talked earlier about email notifications. I still get emails along with my web notifications. It feels redundant. Should I turn one of them off?

      -

      Alex: I strongly recommend turning off email notifications for everything except maybe direct mentions or administrative alerts. Having both is a recipe for anxiety. To fix this, you need to configure your account settings. Navigate to github dot com forward slash settings forward slash notifications.

      -

      Jamie: What am I looking for on that settings page?

      -

      Alex: It is a long page, but it is well structured with headings. You can press H to jump from section to section. Look for the section called Email delivery. There, you can uncheck the boxes that send notifications to your email. I prefer to do all my triage in the web inbox because the keyboard shortcuts we just talked about make it so much faster than managing email.

      -

      Jamie: I am going to make that change as soon as we finish recording. What about the GitHub command line interface? In the last few episodes, we talked about how great the G H CLI is for creating issues and pull requests. Can I manage my notifications from the terminal?

      -

      Alex: You can, but it serves a slightly different purpose. The web interface is best for rapid triage and achieving inbox zero. The command line is best for targeted queries. For example, you can open your terminal and type g h search p r s dash dash review dash requested at me dash dash state open.

      -

      Jamie: That is a long command. Let me break that down. G h search p r s, means search pull requests. Dash dash review dash requested at me, filters for ones waiting on me. And dash dash state open, means only show me ones that are not closed yet.

      -

      Alex: Exactly. That command will output a clean text list in your terminal of exactly what you need to review. You can also run g h issue list dash dash assignee at me, to see all issues assigned to you. So, while the CLI does not have a fully featured inbox management tool for muting and archiving, it is fantastic for quickly finding out what your action items are without ever opening a web browser.

      -

      Jamie: That is really good to know. I like the idea of starting my morning in the terminal, running those two commands, and knowing exactly what my priorities are for the day, without getting distracted by a hundred other notifications in the web inbox.

      -

      Alex: That is a very professional workflow. It puts you in control of the information, rather than letting the information control you.

      -

      Jamie: Alright, we have covered a massive amount of ground today. This feels like the missing manual I needed two years ago. Let us recap the biggest takeaways for everyone listening.

      -

      Alex: First, understand the difference between watching and starring. Starring is a bookmark. Watching is a subscription. If you are overwhelmed with noise, check to make sure you have not accidentally watched a busy repository. You generally want your watch setting to be participating and mentions.

      -

      Jamie: Second, use the dedicated web inbox at github dot com forward slash notifications. The sequential keyboard shortcut is G then N. Do not rely on email. The web inbox gives you powerful filtering and triage tools.

      -

      Alex: Third, navigate the inbox list using the Tab key, not your reading arrows. Listen to the comprehensive announcement for each row, which includes the repository, title, event type, and timestamp.

      -

      Jamie: Fourth, learn the single key shortcuts. E marks a notification as done and gets it out of your way. M mutes a noisy thread so you stop hearing about it. And S saves it for later.

      -

      Alex: And finally, do not be afraid to use the mark all as done button. Your attention is your most valuable resource. Protect it ruthlessly. Filter for the things that matter, like review requests and direct mentions, and let the rest go.

      -

      Jamie: This has been incredibly helpful. I feel like I finally have a strategy to tame the beast. What is next on our journey?

      -

      Alex: This episode concludes the first major phase of our workshop. You now know how to navigate repositories, work with issues, review pull requests, and manage your communications. Next time, we are moving into the day two agenda, where things get really exciting. We are going to introduce GitHub Copilot, and we will talk about agentic workflows, where artificial intelligence can actually help you summarize those notifications and manage your project.

      -

      Jamie: Oh, I cannot wait for that. Having an AI assistant read my notifications sounds like a dream come true.

      -

      Alex: It is a game changer, but it relies entirely on the manual discipline we learned today. An agent can only summarize effectively if you have your watch settings configured correctly. So, practice taming your inbox today, and we will see you in the next episode. Thanks for listening to Gitt Going with GitHub.

      +

      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.

      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

      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 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: 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: 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: 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 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 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 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: 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 10. Next in the series is episode 11, where we keep building the same contributor muscles.

      - +

      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 5: VS Code Setup and Accessibility

      - - -

      Download Episode 11 (MP3)

      +

      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 eleven of Gitt Going with GitHub. I am Alex, your lead host for this series, and today we are tackling a massive and exciting topic. We are talking about setting up Visual Studio Code for accessibility.

      -

      Jamie: And I am Jamie. I have to admit, I am really looking forward to this one, but I also remember how overwhelming this exact topic was for me about two years ago. We spent episode one of this series making sure you all had Visual Studio Code and Git installed, which was a great first step. But actually opening the editor and figuring out how to make it talk nicely with a screen reader felt like a whole new mountain to climb.

      -

      Alex: That is a completely normal feeling. Moving from reading code on a website to actually writing and managing code in a professional editor is a big transition. When something might feel intimidating today, I want you to remember that you have already done most of this on day one of your learning journey. You already understand the workflow. Today, we are just learning how to let Visual Studio Code handle the heavy lifting.

      -

      Jamie: OK, that sounds like a good mindset to have. So, let us start at the very beginning. What exactly is Visual Studio Code? I hear developers just call it VS Code all the time.

      -

      Alex: Yes, we will refer to it as VS Code from here on out. VS Code is a free, extensible code editor built by Microsoft.

      -

      Jamie: Let us break that down. What do you mean by an extensible code editor? How is a code editor different from something like Microsoft Word?

      -

      Alex: That is a great question. A word processor like Microsoft Word is designed for rich text. It cares about fonts, bold text, page margins, and printing. A code editor is designed purely for plain text, but it is highly optimized for programming. It understands the structure of code, it can catch errors as you type, and it integrates directly with tools like Git.

      -

      Jamie: And what about that word, extensible?

      -

      Alex: Extensible means you can add new features to it. I like to think of VS Code as a heavy duty workshop bench. Out of the box, it is just a really solid table. But because it is extensible, you can bring your own tools and bolt them onto the bench. You can install tools for Python, tools for spell checking, or tools for GitHub Copilot. You customize the bench to fit exactly what you need to build.

      -

      Jamie: I love that analogy. You build your own perfect workspace. But before we talk about the desktop app that everyone installed in episode one, I want to talk about a really cool trick I learned. The browser version.

      -

      Alex: Ah, yes. The github dot dev experience. This is one of the most powerful features GitHub offers, and it requires zero installation.

      -

      Jamie: I remember the first time someone told me how to use this. They told me to open any repository on GitHub and just press the period key. I thought they were joking.

      -

      Alex: It sounds like a magic trick, but it is real. If you are navigating any GitHub repository in your browser, and you press the period key, just the dot on your keyboard, the webpage will instantly transform. The URL changes from github dot com to github dot dev, and suddenly, you are sitting inside a fully functional version of VS Code, running entirely in your browser.

      -

      Jamie: It is so fast. To use your workshop analogy, if the desktop app is your main heavy duty workbench in your garage, the github dot dev browser experience is like a pop up shop version of your workbench. You can access it from anywhere, on any computer, without installing a single thing.

      -

      Alex: Exactly. It uses the exact same keyboard shortcuts as the desktop version, and it has the exact same screen reader mode. It is the perfect bridge between browsing GitHub on the web and doing deep development work on your machine.

      -

      Jamie: Are there things the browser version cannot do? Why even bother with the desktop app if the browser version is so good?

      -

      Alex: The browser version does have limitations. Because it runs in your web browser, it does not have an integrated terminal. You cannot run command line scripts. It also does not support GitHub Copilot or running local accessibility agents. For those heavy duty tasks, you need the desktop application. But for quick edits, fixing a typo in documentation, or reviewing a pull request, pressing the period key is the fastest way to get to work.

      -

      Alex: Now, whether you are using the browser version or the desktop app, the very first thing you need to do is turn on screen reader mode. VS Code is built using web technologies, which means it behaves a lot like a complex web application. By default, it presents a lot of visual information that can be incredibly noisy or confusing for a screen reader.

      -

      Jamie: How do we fix that? How do we make it accessible?

      -

      Alex: You activate screen reader mode by pressing Shift plus Alt plus F1. If you are on a Mac, you will press Shift plus Option plus F1.

      -

      Jamie: What actually happens when I press Shift plus Alt plus F1?

      -

      Alex: It is like turning the lights on for your screen reader. When you enable this mode, VS Code changes how focus moves around the application. It suppresses a lot of the visual decorations that cause extra noise. Most importantly, it enables live regions for code suggestions and errors.

      -

      Jamie: Can you define live region for anyone who might be new to that term?

      -

      Alex: Certainly. A live region is an invisible area of the application that can send spoken announcements to your screen reader, even if your keyboard focus is somewhere else. So, if you are typing code, and VS Code finds an error, the live region will announce the error to you immediately, without you having to navigate away from the line you are typing on.

      -

      Jamie: That is incredibly helpful. OK, that sounds like a lot of steps to remember every time I open the app.

      -

      Alex: It does! But here is the thing, you really only have to configure this once. To make sure it stays on permanently, you should update a specific setting. You will want to navigate to your settings and search for the phrase editor dot accessibility support. You want to set this to the word on, rather than leaving it on auto.

      -

      Jamie: Why force it to on? Does the auto setting not work?

      -

      Alex: Auto usually works if you are on Windows using NVDA or JAWS. VS Code will try to detect your screen reader and turn the mode on automatically. But sometimes, especially if you start your screen reader after opening the editor, it might miss the detection. Forcing editor dot accessibility support to on guarantees that all those screen reader announcements and optimizations are always active.

      -

      Jamie: OK, so our screen reader is happy and talking to us properly. How do we actually do things in VS Code? There are so many menus and buttons. It can feel like being dropped into the cockpit of an airplane.

      -

      Alex: The secret to VS Code is that you do not need to memorize the menus. You only need to memorize one keyboard shortcut. Control plus Shift plus P.

      -

      Jamie: Ah, the Command Palette. I call this the magical concierge.

      -

      Alex: That is the perfect name for it. When you press Control plus Shift plus P, a text input field opens at the top of the window. This is the Command Palette. Every single action, setting, and feature in VS Code can be triggered by typing its name into this box.

      -

      Jamie: It is like going to a restaurant where you do not need to read the menu. You just walk up to the chef and say, I would like to format this document, or I would like to open my settings, and the chef just does it for you.

      -

      Alex: Exactly. If you want to change your color theme, you press Control plus Shift plus P, type the word theme, and press enter. If you want to toggle word wrap, you press Control plus Shift plus P, type word wrap, and press enter. You never have to dig through complex dropdown menus.

      -

      Jamie: And what if I want to learn the actual keyboard shortcuts for the area of the editor I am currently working in? Is there a quick way to get help without leaving the app?

      -

      Alex: Yes, and this is an essential tool for screen reader users. It is the accessibility help dialog. You can open it by pressing Control plus Shift plus H.

      -

      Jamie: What exactly does it tell you?

      -

      Alex: The accessibility help dialog is context aware. That means if your focus is currently inside the text editor, and you press Control plus Shift plus H, a plain text document pops up. It will read out exactly how to navigate the text editor, which shortcuts move you between errors, and how to trigger suggestions.

      -

      Jamie: Oh, that is clever! So if I move my focus to the terminal and press Control plus Shift plus H, it gives me different instructions?

      -

      Alex: Precisely. It will give you the specific accessibility commands for the terminal. It is your built in manual for wherever you happen to be standing at that exact moment. Use it as your first action whenever you land somewhere new in VS Code.

      -

      Alex: Speaking of landing somewhere new, let us talk about the layout of VS Code and how to navigate between its different areas. The interface is divided into a few main regions. The Sidebar, the Editor, the Terminal, and the Panels.

      -

      Jamie: I like to think of these as the rooms of a house. You do different tasks in different rooms, and you need to know how to walk between them.

      -

      Alex: Let us start with the Sidebar. On the far edge of the window is a vertical strip called the Activity Bar. The Activity Bar contains the main views of the application. The most important ones are the Explorer, the Search view, the Source Control view, and the Extensions view.

      -

      Jamie: Can we talk about the Explorer first? Because I remember being really confused about the difference between opening a file and opening a folder.

      -

      Alex: That is a very common stumbling block. The Explorer is your file tree. It shows you all the files in your project. But how you open your project matters. If you go to the file menu and select Open File, VS Code will open just that single document. The Explorer will be empty.

      -

      Jamie: Right, and my analogy for this is a filing cabinet. Opening a file is like taking a single piece of paper out of the filing cabinet and putting it on your desk. You can read it and write on it, but you cannot see any of the other papers that were next to it.

      -

      Alex: Exactly. But if you choose Open Folder instead, it is like bringing the entire filing cabinet to your desk. The Explorer will populate with every file and subfolder inside that project. This is how you should always work in VS Code. You open the root folder of your repository, so you have access to everything at once.

      -

      Jamie: So if I want to jump over to the Explorer to find a file, what is the shortcut?

      -

      Alex: You press Control plus Shift plus E. That moves your focus to the Explorer. You can use your up and down arrows to navigate through your files, and press Enter to open one.

      -

      Jamie: And when I press Enter, the file opens in the Editor room. How do I move my focus back and forth between the Explorer and the Editor?

      -

      Alex: To jump into your active Editor, you press Control plus 1. That puts your cursor directly into the text of the file you are working on. To go back to the Explorer, you press Control plus Shift plus E again. You will be doing this dance constantly. Control plus 1 for the editor, Control plus Shift plus E for the Explorer.

      -

      Jamie: What about the other views in the Activity Bar? You mentioned Search and Source Control.

      -

      Alex: Search allows you to find text across every file in your entire folder. You can navigate to it by pressing Control plus Shift plus F. Source Control is where you stage and commit your changes to Git. You can reach that by pressing Control plus Shift plus G.

      -

      Jamie: Earlier, you mentioned the Extensions view. You said VS Code is extensible, like bringing your own tools to a workbench. How do we actually install these tools?

      -

      Alex: You will open the Extensions view by pressing Control plus Shift plus X. This moves your focus into a search box. You simply type the name of the extension you want, for example, Python, or GitHub Pull Requests. Then you press the Tab key to navigate to the search results, use your arrow keys to find the exact match, and press Enter to install it.

      -

      Jamie: I wish I had known that when I started. It is so much faster than trying to use a mouse to find the little install buttons. Now, what about the terminal? You mentioned earlier that the browser version does not have one, but the desktop version does.

      -

      Alex: Yes, the integrated terminal. If the editor is where you write your code, the terminal is the engine room. It is where you type direct text commands to your computer's operating system, completely bypassing the graphical interface. You use it to run Git commands, install software packages, or start local web servers.

      -

      Jamie: How do we open the engine room?

      -

      Alex: You press Control plus Backtick.

      -

      Jamie: OK, let us pause for a second. What is a backtick? I spent an embarrassingly long time looking for this key.

      -

      Alex: The backtick key is usually located in the top left corner of your keyboard, right above the Tab key, and just to the left of the number one. It shares a key with the tilde symbol. Pressing Control plus Backtick will instantly open the integrated terminal panel at the bottom of your window and move your focus into it. Pressing Control plus Backtick a second time will hide the terminal and return your focus to the editor.

      -

      Jamie: Let us talk about something really fun. Audio cues. I think this is one of the best accessibility features Microsoft has ever added to an application.

      -

      Alex: I completely agree. VS Code has a system called accessibility signals. These are distinct audio cues, little chimes and sounds, that communicate the state of the editor without requiring your screen reader to speak a single word.

      -

      Jamie: It is so much like the dashboard sounds in a car. You do not need to take your eyes off the road to look at the dashboard to know your turn signal is on, because you can hear the rhythmic clicking. Audio cues do the exact same thing for coding.

      -

      Alex: A perfect example is the error signal. If you have the setting called accessibility dot signals dot line has error turned on, VS Code will play a distinct, slightly lower pitched tone whenever your cursor moves onto a line of code that contains a mistake.

      -

      Jamie: It is amazing because it does not interrupt your screen reader's speech. You hear your screen reader read the text of the line, and layered right underneath it, you hear the little error tone. You immediately know something is wrong before you even finish reading the line.

      -

      Alex: There are audio cues for everything. There is a cue for when a terminal command finishes successfully, a cue for when a terminal command fails, and cues for when you are navigating through changes in your code. You can configure all of these by opening your settings and searching for accessibility signals.

      -

      Jamie: Speaking of navigating through changes, I want to ask about the Accessible Diff Viewer. This is a concept that took me a while to wrap my head around. First, what exactly is a diff?

      -

      Alex: A diff is short for difference. So a pull request, and I love that name because you are literally requesting that someone pull your changes into their project, a pull request is essentially just a big diff. It is a representation of exactly what lines of code you added, and what lines of code you removed.

      -

      Jamie: Right. And visually, a diff is usually displayed side by side. You have the old file on the left side of the screen with the removed lines highlighted in red, and the new file on the right side with the added lines highlighted in green.

      -

      Alex: Which is an absolute nightmare to navigate with a screen reader. A spatial, color coded layout does not translate well to linear speech.

      -

      Jamie: It really does not. So how do we read a diff effectively?

      -

      Alex: This is where the Accessible Diff Viewer comes in. When you have a diff open in your editor, instead of trying to read the visual side by side layout, you open the Command Palette with Control plus Shift plus P. Then, you type Open Accessible Diff Viewer and press enter.

      -

      Jamie: What does that view actually look like to the screen reader?

      -

      Alex: It completely transforms the presentation. It turns the diff into a single, vertical list. It is like having a redline document read aloud to you line by line. As you use your up and down arrows, it will announce the change type before reading the code. It will say, Line added, followed by the text. Or it will say, Line removed, followed by the text. Or it will say, Unchanged, to give you the surrounding context.

      -

      Jamie: That is a game changer. You get the complete picture of what changed, in reading order, without having to scan visually.

      -

      Alex: Before we wrap up, there is one last piece of housekeeping regarding keyboard navigation. Sometimes, a built in VS Code shortcut might conflict with a screen reader command. For instance, NVDA or JAWS might intercept a keystroke before it ever reaches the editor.

      -

      Jamie: That used to drive me crazy. What is the fix for that? Do you just have to live without that command?

      -

      Alex: Not at all. VS Code allows for total keyboard shortcut customization. If a shortcut does not work for you, you can change it. You just open the Command Palette with Control plus Shift plus P, type Open Keyboard Shortcuts, and press enter. You can search for the command you want to change, press enter on it, and then simply type your new preferred key combination.

      -

      Jamie: I love that. The editor really bends to fit your workflow, not the other way around.

      -

      Alex: Exactly. Let us summarize our key takeaways for today. First, remember the period key trick. Pressing period on any GitHub repository opens the github dot dev browser experience for fast, lightweight editing.

      -

      Jamie: Second, always turn on screen reader mode by pressing Shift plus Alt plus F1, and make sure your editor dot accessibility support setting is forced to on.

      -

      Alex: Third, the Command Palette is your best friend. Press Control plus Shift plus P to find any command without digging through menus. And remember Control plus Shift plus H to open the accessibility help dialog for context aware shortcut lists.

      -

      Jamie: Fourth, always open a folder, not a file, so you have access to your entire project in the Explorer.

      -

      Alex: And finally, when reviewing changes, use the Command Palette to open the Accessible Diff Viewer for a clean, line by line reading experience.

      -

      Jamie: This has been incredibly helpful. I feel like my workbench is finally set up and my tools are organized. What are we building next?

      -

      Alex: In our next episode, we are going to take everything we just learned about the interface and apply it to version control. We will be covering Git and Source Control directly inside VS Code. We will learn how to stage, commit, and push our code without ever leaving the editor. Thank you for listening to Gitt Going with GitHub, and we will catch you in the next episode.

      +

      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 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 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: 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).

      +
      +

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

      +
      +

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

      +
      +

      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: 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: 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: 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. 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 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. 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 11. Next in the series is episode 12, where we keep building the same contributor muscles.

      - +

      Episode 12: Git and Source Control in VS Code

      Cloning, branching, staging, committing, pushing, and pulling from VS Code.

      -

      Based on: Chapter 11: Git and Source Control in VS Code

      - - -

      Download Episode 12 (MP3)

      +

      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 Gitt Going with GitHub. This is episode 12, Git and Source Control in VS Code. I am Alex, and I am here with Jamie.

      -

      Jamie: Hello everyone! I am really excited for this one. I feel like we have been building up to this moment for the entire series.

      -

      Alex: We absolutely have. In episode 3, we talked about the big concepts of Git, like repositories, branches, and commits. Then in episode 11, we got our VS Code environment set up, learned how to use the Command Palette, and got comfortable navigating the sidebar. Today, we are bringing those two worlds together. We are going to learn how to actually do Git operations right inside VS Code.

      -

      Jamie: And I want to say right up front to anyone listening, if this feels like a lot of steps, that is completely normal. I remember learning GitHub about two years ago, and I was terrified I was going to push the wrong button and delete someone else's code. But the beauty of Git is that it is actually really hard to permanently break things. And doing it in VS Code makes the heavy lifting so much easier.

      -

      Alex: That is a great point, Jamie. We are going to normalize that feeling of intimidation today. Because honestly, the workflow we are going to cover is the exact same workflow you will use whether it is your first day on a project or your tenth year as a senior developer.

      -

      Alex: Let us start at the very beginning. To work on a project, you need a copy of it on your computer. In Git terminology, this is called cloning a repository.

      -

      Jamie: I remember when I first started coding, before I knew Git, I would just go to a website, download a ZIP file of the code, and extract it to a folder. How is cloning different from just downloading a ZIP file?

      -

      Alex: That is the perfect question. When you download a ZIP file, you are just getting the files exactly as they exist at that exact second. It is a snapshot. But when you clone a repository, you are downloading the files plus the entire hidden history of the project. You get every commit, every branch, and most importantly, a permanent connection back to the original repository on GitHub.

      -

      Jamie: So it is like the difference between taking a photo of a document, versus having a live shared document where you can see all the version history.

      -

      Alex: Exactly. Now, there are a few different ways to clone a repository. The most accessible way, and the one we recommend for screen reader users, is using the VS Code Command Palette.

      -

      Jamie: Right, we talked about the Command Palette in the last episode. That is Control plus Shift plus P on Windows, or Command plus Shift plus P on a Mac.

      -

      Alex: Correct. When you open the Command Palette, you just type the words Git Clone. You will hear your screen reader announce Git: Clone as an option. You press Enter, and VS Code will ask you for the repository URL. You paste in the web address of the GitHub repository, press Enter again, and VS Code will open a standard file dialog asking where you want to save the folder on your computer.

      -

      Jamie: That sounds pretty straightforward. Navigate to the folder you want, press Enter, and it downloads everything. But I have also heard people talk about doing this in the terminal. Like using the words git clone or gh repo clone. What is the difference there?

      -

      Alex: Those are the command line alternatives. The standard Git command line interface, or CLI, uses the command git clone followed by the URL. That does the exact same thing as VS Code, it just does it in the terminal. Then there is the GitHub CLI, which is a separate tool you can install. Its command is gh repo clone. The neat thing about the GitHub CLI is that it already knows you are talking to GitHub. So instead of pasting a massive URL, you just type gh repo clone followed by the owner name, a slash, and the repository name. Like gh repo clone community-access slash learning-room.

      -

      Jamie: Oh, that is clever! It saves you from having to copy and paste full web addresses. But for today, we will stick to the VS Code Command Palette method. So, I have cloned the repository. I have the files on my computer. Before I start typing and changing code, I feel like I need a mental model of how Git tracks these files.

      -

      Alex: You absolutely do. Understanding the mental model is the secret to never getting lost in Git. There are three main areas you need to understand: the working tree, the staging area, and the repository.

      -

      Jamie: Okay, hit me with an analogy. I need a way to picture this.

      -

      Alex: Let us use a mailroom or a shipping department. Imagine you are putting together a care package for a friend.

      -

      Jamie: I love care packages.

      -

      Alex: Right. So, the room you are standing in, with tables and shelves and items scattered everywhere, that is your working tree. The working tree is just the actual files on your computer right now. You can pick things up, change them, break them, or create new things.

      -

      Jamie: So when I open a file in VS Code and type a new paragraph, I am messing around in the working tree.

      -

      Alex: Exactly. Now, eventually, you want to send some of these items to your friend. But you do not just throw the whole room into a truck. You get a shipping box. You take specific items from your workbench and you place them into the box. That box is the staging area. You are preparing a specific set of changes to be grouped together.

      -

      Jamie: And I can add things to the box, or take things out of the box, before I tape it shut.

      -

      Alex: Precisely. The staging area is where you build your next commit. Finally, when the box is perfectly packed, you tape it shut, stick a label on it describing what is inside, and put it on the outbound truck. Taping the box shut is creating a commit, and the truck takes it to the warehouse. That warehouse is the repository. The repository is the permanent, safe archive of all your sealed boxes.

      -

      Jamie: That makes so much sense. Working tree is the messy room. Staging area is the open box. Repository is the warehouse of sealed boxes. And I assume files can have different states depending on where they are in this process?

      -

      Alex: Yes. Git tracks files in three distinct states. First is untracked. This is a brand new file you just created. Git says, I have never seen this before, I am not tracking it. It is like a brand new item you just bought that is not on your inventory list yet.

      -

      Jamie: Okay. Untracked means brand new.

      -

      Alex: Second is modified. This means Git knows about the file, but you have changed it in your working tree, and you have not put it in the shipping box yet.

      -

      Jamie: Modified means changed, but still on the workbench.

      -

      Alex: And third is staged. This means you have moved that modified or untracked file into the staging area. It is in the box, ready to be committed.

      -

      Jamie: Untracked, modified, staged. I wish I had known that when I started. It makes the error messages make so much more sense when Git complains about modified files. So, how do we actually see these states in VS Code?

      -

      Alex: This brings us to the most important interface for Git in VS Code, which is the Source Control view. It lives in the Activity Bar on the far left of the screen, but you do not need to hunt for it. You just use the keyboard shortcut Control plus Shift plus G. That is G for Git. If you are on a Mac, it is Command plus Shift plus G.

      -

      Jamie: Control plus Shift plus G. I am pressing it now. What happens?

      -

      Alex: A side panel opens up, and your screen reader focus usually lands right in the middle of it. Let us break down the structure of this panel from top to bottom. At the very top is the Source Control title bar. This is actually super helpful because it announces the name of the branch you are currently on, like main or feature slash add-documentation.

      -

      Jamie: That is a nice quick way to check where you are without having to use the terminal. What is below the title bar?

      -

      Alex: Below that is a multi-line text input field. Your screen reader will call it Source Control Input. This is where you will eventually type your commit message, which is the label for your shipping box.

      -

      Jamie: Okay, so the text box is waiting for me. And below the text box?

      -

      Alex: Below the text box is the really magical part. It is a specialized tree view that lists your files. But it does not list all the files in your project. It only lists the files that have changed. It is divided into two collapsible sections. The bottom section is called Changes. This is your working tree. It shows all your modified and untracked files.

      -

      Jamie: So if I fix a typo in the readme file, the readme file will show up under Changes.

      -

      Alex: Exactly. And the section right above Changes is called Staged Changes. This is your shipping box. When you first open the panel, Staged Changes might be completely empty or even hidden, because you have not put anything in the box yet.

      -

      Jamie: How do I navigate this tree view with a screen reader? Is it just like a normal file explorer?

      -

      Alex: It is similar, but it has some special behaviors. For NVDA and JAWS users, you use your Up and Down arrow keys to move through the lists. When you land on a section header like Changes, your screen reader will say Changes, expanded, or Changes, collapsed. You can use your Right arrow to expand a section, and your Left arrow to collapse it.

      -

      Jamie: And when I arrow down onto an actual file, what does it say?

      -

      Alex: It will read the file name, the folder path, and the state. So it might say, index dot HTML, Modified. Or, styles dot CSS, Untracked.

      -

      Jamie: Okay, that sounds very efficient. I do not have to guess what I changed today, VS Code just gives me a tidy list of my messy workbench. Before we start moving things into the staging box, though, we should probably talk about branches. Because I know I am not supposed to do my messy work on the main branch.

      -

      Alex: That is a fantastic point. Whenever you want to make a change, whether it is fixing a bug or writing a new feature, you should create a new branch. A branch is basically an isolated copy of the code where you can experiment safely.

      -

      Jamie: Creating branches from the terminal always made me nervous. How do we do it in VS Code?

      -

      Alex: It is incredibly easy. We go back to our trusty Command Palette. Control plus Shift plus P. You type the words Create Branch. You will hear Git: Create Branch. Press Enter.

      -

      Jamie: And then it asks for a name?

      -

      Alex: Yes, a text input appears. You type your branch name. A quick tip on naming conventions: use lowercase letters and hyphens instead of spaces. So you might type, feature hyphen update hyphen readme. Then you press Enter.

      -

      Jamie: And that is it? Does it switch me to that branch automatically?

      -

      Alex: It does. VS Code creates the branch and immediately checks it out, which is Git terminology for switching to it. Your working files stay exactly as they were, but now Git knows that any new commits you make will be saved to this new branch, leaving the main branch perfectly safe and untouched.

      -

      Jamie: That takes so much anxiety out of the process. What if I need to switch back to the main branch to check something?

      -

      Alex: Command Palette again. Control plus Shift plus P. This time, type Checkout. You will select Git: Checkout to. A list of all your branches will appear. You just use your Up and Down arrows to find main, and press Enter.

      -

      Jamie: So I can bounce back and forth between branches just by searching for them. I love that. Okay, so I am on my new branch. I have made some changes to my files. I press Control plus Shift plus G to open the Source Control panel. I arrow down to the Changes section, and I hear that three of my files are modified. It is time to pack the shipping box. How do I stage a file?

      -

      Alex: Staging is very satisfying in VS Code. When you are navigating the Source Control panel and your screen reader focus is on a specific file under the Changes list, you have a couple of options. The fastest way is to just press the Spacebar, or press Control plus Enter. For Mac users, that is Command plus Enter.

      -

      Jamie: Wait, just pressing Spacebar moves it into the box?

      -

      Alex: Yes. The file immediately disappears from the Changes list and reappears up in the Staged Changes list. Your screen reader might not announce the move automatically, depending on your verbosity settings, but if you arrow up, you will find it sitting safely in the Staged Changes section.

      -

      Jamie: What if I change my mind? What if I put it in the box and realize I am not ready to ship it?

      -

      Alex: You do the exact reverse. You arrow up into the Staged Changes list, focus on the file, and press Spacebar or Control plus Enter again. It unstages the file. It takes it out of the box and puts it back on the workbench. The file itself does not lose any of your typed changes, it just changes its Git status.

      -

      Jamie: That is so forgiving. Now, you mentioned earlier that I had three modified files. What if I want to stage all of them at once? Do I have to press Spacebar on every single one?

      -

      Alex: You can, but there is a faster way. If you move your focus to the actual section heading that says Changes, expanded, you can open the context menu. For Windows users, you can press Shift plus F10, or the Application key if your keyboard has one. For Mac users, you can use VoiceOver keys plus Shift plus M.

      -

      Jamie: The context menu is like right-clicking with the mouse, right?

      -

      Alex: Exactly. When the context menu opens, you just arrow down to the option that says Stage All Changes, and press Enter. Boom. Everything on your workbench is swept into the shipping box.

      -

      Jamie: Okay, so why wouldn't I just do that every time? Why does Git even have a staging step? Why not just say, hey Git, save everything I just did?

      -

      Alex: That is the million dollar question. The reason Git has a staging step is to help you create atomic commits. Let us say you are working on a new feature, writing a bunch of new code. While you are doing that, you notice a really embarrassing spelling mistake in a completely unrelated documentation file. So you fix the typo, and you keep writing your feature.

      -

      Jamie: I do that all the time. I get distracted by typos.

      -

      Alex: Right! Now, at the end of the day, you have a bunch of changed files. If you just saved everything at once, your project history would have one giant commit that says, Added new feature and also fixed a typo. That makes it really hard for other developers to review your work.

      -

      Jamie: Oh, I see. With the staging area, I can put just the documentation file into the box, seal it up, and call it Typo fix. And then I can put all the feature files into a second box, and call that New feature.

      -

      Alex: Exactly. You stage individual files to group related changes together. In fact, VS Code even lets you stage individual lines of code within a single file. If you press Enter on a file in the Source Control panel, it opens a diff view showing exactly what lines changed. You can navigate to a specific line, open the context menu with Shift plus F10, and choose Stage Selected Ranges. It is incredibly powerful.

      -

      Jamie: Okay, that is a total power user move. Staging just a few lines of a file while leaving the rest unstaged. That is amazing. But let us stick to the basics for now. I have staged my files. They are in the Staged Changes list. The box is packed. How do I tape it shut and write the label?

      -

      Alex: It is time to commit. In the Source Control panel, you will press Tab or Shift plus Tab until your focus lands in the multi-line text field called Source Control Input. This is where you write your commit message.

      -

      Jamie: And writing a good commit message is an art form, isn't it? I know when I first started, my commit messages were literally just the word updates, or fixed stuff, over and over again.

      -

      Alex: We have all been there. But in open source, your commit messages are how you communicate with the maintainers. We use a convention called Conventional Commits. The subject line should be short, fifty characters or less, and it follows a specific format.

      -

      Jamie: What is the format?

      -

      Alex: You start with a type, then a colon, then a space, and then a short summary of what you did in lowercase letters. So for example, if you fixed a bug, you type the word fix, f i x, colon, space, and then something like correct heading hierarchy.

      -

      Jamie: Fix colon correct heading hierarchy. What if I am adding a new feature?

      -

      Alex: Then you use the word feat, f e a t. Feat colon add search button. If you are just updating documentation, you use docs, d o c s. Docs colon update screen reader instructions.

      -

      Jamie: That makes reading the project history so much easier. You can just scan down the list and see exactly what kind of work was done. So, I have typed my message into the input box. How do I actually execute the commit? Do I press Enter?

      -

      Alex: If you just press Enter, you will actually just create a new line in the text box, because it is a multi-line input. To actually execute the commit, you press Control plus Enter. Or Command plus Enter on a Mac.

      -

      Jamie: Control plus Enter. And what happens when I press it?

      -

      Alex: The text box clears out. The files disappear from the Staged Changes list. And your screen reader might announce that the commit was successful. You have officially sealed the shipping box.

      -

      Jamie: Success! My code is safe. But wait, where is it safe? Is it on GitHub yet?

      -

      Alex: Ah. This is the most common point of confusion for Git beginners. When you commit, you are only saving that snapshot to your local repository. The warehouse on your computer. GitHub has no idea that you just made a commit.

      -

      Jamie: So if I drop my laptop in a lake right now, that commit is gone forever.

      -

      Alex: Unfortunately, yes. To send your commits to GitHub, you have to perform an operation called a push. You are literally pushing your commits up to the remote server.

      -

      Jamie: Okay, how do I push?

      -

      Alex: The easiest way is back in the Command Palette. Control plus Shift plus P. Type Git Push, and select Git: Push. VS Code will contact GitHub and upload your commits.

      -

      Jamie: What if I get an error? I remember getting an error about no upstream branch when I tried to push my first branch.

      -

      Alex: Yes, the dreaded no upstream branch error. This happens because of the relationship between your local branch and the remote tracking branch. Think of your local branch like your personal private journal. You created it on your computer. GitHub does not have a journal with that name yet.

      -

      Jamie: So when I try to push, Git says, I do not know where to put this on GitHub?

      -

      Alex: Exactly. When you create a new branch locally and try to push it for the very first time, you have to publish the branch. In the VS Code Command Palette, instead of Git Push, you can select Git: Publish Branch. This tells Git to create a matching branch up on GitHub, and then push your commits to it. From then on, a normal Git Push will work perfectly.

      -

      Jamie: Git Publish Branch for the first time. Got it. Okay, so pushing is sending my stuff up. What about pulling? I hear people say they need to pull changes.

      -

      Alex: Pulling is the exact opposite. It is downloading new commits from GitHub into your local repository. Let us say you are collaborating with another developer. They push a new commit to the branch you are both working on. You need to download their work so your local files are up to date. You open the Command Palette, type Git Pull, and select Git: Pull. VS Code downloads their commits and merges them into your working tree.

      -

      Jamie: That sounds great, until we both edit the exact same line of code. What happens then? Does my computer explode?

      -

      Alex: No explosions, but you will get what is called a merge conflict. Git is very smart, but it refuses to guess which person's code is the correct one. If you both changed line 42 of the readme file, and you try to pull their changes, Git will stop and say, hey, I have a conflict here. You need to resolve this manually.

      -

      Jamie: We actually talked about the theory of merge conflicts in episode 6, but in VS Code, how does it handle it?

      -

      Alex: When a conflict happens during a pull, VS Code will show the conflicted files in your Source Control panel under a new section called Merge Changes. If you open one of those files, Git has literally injected both versions of the code into the file, separated by some markers like less-than and greater-than signs.

      -

      Jamie: That sounds a bit messy for a screen reader to read through.

      -

      Alex: It can be. The most accessible way to handle it is to open the file and press F7. F7 jumps you directly to the next conflict in the editor. Then you can press Alt plus F2 to open the Accessible Diff Viewer, which presents both versions very cleanly. You decide which version you want to keep, delete the other version and the markers, save the file, and then stage it just like a normal change.

      -

      Jamie: So a conflict is just a file that Git forces you to manually edit and stage again. That is not too scary. I also saw something in our notes about git pull dash dash rebase. What is a rebase?

      -

      Alex: Rebase is a slightly more advanced way to pull changes, but it is incredibly useful. Normally, when you pull someone else's changes while you have your own local commits, Git creates an extra merge commit to tie the two histories together. It can make the project history look like a messy subway map with lines crossing everywhere.

      -

      Jamie: And rebase prevents that?

      -

      Alex: Yes. Think of a rebase like stepping out of line at the grocery store. When you run git pull --rebase in the terminal, Git temporarily un-applies your local commits. It sets them aside. Then it downloads the other person's commits and applies them in a straight line. Finally, it takes your commits and replays them on top of the new history.

      -

      Jamie: Oh, wow. So it is like saying, let me pause my work, let you go first, and then I will do my work after you. It keeps the history as one perfectly straight timeline.

      -

      Alex: Exactly. It is a very elegant way to keep history clean, and many open source projects prefer you to use rebase when pulling updates from the main branch.

      -

      Jamie: So we have covered cloning, branching, staging, committing, pushing, and pulling, all using the VS Code interface. Are there other ways to do this? What if I am on a computer that does not have VS Code installed?

      -

      Alex: There is a fantastic web alternative. You can do almost all of this directly on GitHub dot com. If you navigate to a repository on the GitHub website, you can find any file, open it, and activate the Edit button, which visually looks like a pencil icon.

      -

      Jamie: And I can just type right there in the browser?

      -

      Alex: Yes, it opens a web editor. And here is the interesting difference. On the web, there is no staging step. When you finish editing, you just activate the Commit changes button. GitHub creates the commit directly, either on your current branch or it will automatically create a new branch for you.

      -

      Jamie: That is super fast for small changes, like fixing a single typo. But I imagine if you are changing five different files, navigating through the web interface for each one gets tedious.

      -

      Alex: Exactly. The web interface is brilliant for quick single-file edits. But when you are building a complex feature across multiple files, you want the control of VS Code, where you can stage specific files and review everything locally.

      -

      Jamie: And for the folks who love the terminal, they can do all of this using the Git CLI, right?

      -

      Alex: Absolutely. In VS Code, you can open the integrated terminal by pressing Control plus Backtick. From there, you can type git status to see your modified files, git add dot to stage all changes, git commit dash m to write your message, and git push. Many blind developers actually prefer the terminal because the output is pure plain text, which is very predictable for screen readers.

      -

      Jamie: That makes sense. It is all about finding the tool that fits your brain. But I have to say, the VS Code Source Control panel with Control plus Shift plus G feels like the perfect middle ground. It organizes the information visually and structurally, but gives you complete keyboard control.

      -

      Alex: Let us wrap up with some key takeaways from today's episode. Jamie, what is the first one?

      -

      Jamie: Takeaway number one: Understand the three environments. The working tree is your messy workbench. The staging area is the shipping box where you pack specific changes. And the repository is the permanent warehouse of sealed boxes.

      -

      Alex: Perfect. Takeaway number two: Use the Source Control panel in VS Code. Press Control plus Shift plus G to open it. It is a dedicated tree view that only shows your modified files, separated into Changes and Staged Changes.

      -

      Jamie: Takeaway number three: Staging is how you create atomic commits. You do not have to save everything at once. You can focus on a file, press Spacebar to stage it, and commit just that specific fix with a clear message.

      -

      Alex: And finally, takeaway number four: Committing only saves locally. Do not forget to push! You have to use Git Push to send your sealed boxes up to GitHub so everyone else can see them.

      -

      Jamie: This has been incredibly clarifying, Alex. I feel like I am ready to actually contribute code now. But once my code is pushed to a branch on GitHub, how do I actually ask the project maintainers to merge it into the main project?

      -

      Alex: That is the final piece of the puzzle. In our next episode, we are going to dive into the GitHub Pull Requests extension. We will learn how to create, review, and merge pull requests without ever leaving VS Code.

      -

      Jamie: I cannot wait. Thank you all for listening!

      -

      Alex: Thank you for joining us. Keep exploring, keep committing, and we will see you next time on Gitt Going with GitHub.

      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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 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 12. Next in the series is episode 13, where we keep building the same contributor muscles.

      - +

      Episode 13: The GitHub Pull Requests Extension

      Viewing, creating, reviewing, and merging PRs from inside VS Code.

      -

      Based on: Chapter 12: The GitHub Pull Requests Extension

      - - -

      Download Episode 13 (MP3)

      +

      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 to Gitt Going with GitHub. This is episode thirteen: The GitHub Pull Requests Extension. I am Alex, and I am here with Jamie.

      -

      Jamie: Hi everyone! I am so ready for this episode. We are at the point in the workshop where everything starts coming together.

      -

      Alex: We really are. If you have been following along, in episode six we covered the full pull request lifecycle from the web interface, using GitHub dot com. And in episode twelve, our last episode, we talked about doing local Git operations right inside Visual Studio Code.

      -

      Jamie: Right, so committing, branching, and pushing without ever leaving the editor. Which was a huge time saver.

      -

      Alex: Exactly. But what happens when you push that branch and you are ready to open a pull request? Or what if someone asks you to review their code? Up until now, you would have to switch over to your web browser, navigate GitHub dot com, find the pull request, and review it there.

      -

      Jamie: Which works! We learned how to do that, and it is fully accessible. But switching contexts between your editor and your browser all day can be exhausting.

      -

      Alex: It can be. And that brings us to the core concept of today's episode: The GitHub Pull Requests and Issues extension for VS Code. This extension essentially brings the GitHub website directly into your editor.

      -

      Jamie: I like to think of it like this. Imagine you are writing a book. Using the web interface for pull requests is like having to drive down to the post office every time you want to mail a chapter to your editor, and then driving back to the post office to pick up their feedback.

      -

      Alex: That is a great analogy.

      -

      Jamie: Right? But installing this extension is like having a direct mail chute installed right at your desk. You write the code, you package it up, and you send it off, all from the exact same chair. You even receive their feedback right on your original manuscript.

      -

      Alex: Perfectly said. The extension lets you view, create, review, and merge pull requests without ever pressing Alt plus Tab to open a browser. So, let us talk about how to get it.

      -

      Alex: To start using this, you need to install the extension and sign in.

      -

      Jamie: Okay, walk me through it. I am in VS Code.

      -

      Alex: First, open your Extensions sidebar. The keyboard shortcut is Control plus Shift plus X on Windows, or Command plus Shift plus X on Mac.

      -

      Jamie: Control plus Shift plus X. Got it. And that puts my focus in a search box, right?

      -

      Alex: Yes. Type in the words GitHub Pull Requests. You will hear your screen reader announce the search results. You want to navigate down to the one called GitHub Pull Requests and Issues, published by GitHub. Press Enter to open its detail page, Tab to the Install button, and press Enter again.

      -

      Jamie: Nice and easy. And since it is connecting to my GitHub account, I assume I need to log in?

      -

      Alex: You do. After it installs, VS Code will prompt you with a notification asking to sign in to GitHub. You can navigate to your notifications with Alt plus N on Windows, or Option plus N on Mac. When you activate the Sign In button, it briefly opens your web browser to authorize VS Code, and then sends you right back to the editor.

      -

      Jamie: And if I miss the notification, can I just use the Command Palette?

      -

      Alex: Absolutely. Just press Control plus Shift plus P, type GitHub Pull Requests Sign In, and press Enter. It does the exact same thing.

      -

      Jamie: Okay, I am installed and signed in. Where did my pull requests go? How do I find them?

      -

      Alex: The extension adds a brand new section to VS Code. If you are navigating the Activity Bar, it is a new icon that just says GitHub. But the most reliable way to jump straight to it with a screen reader is, as always, the Command Palette.

      -

      Jamie: Control plus Shift plus P.

      -

      Alex: Exactly. Press Control plus Shift plus P, and type Focus on Pull Requests View. When you press Enter, your focus moves to a new tree view in the sidebar.

      -

      Jamie: A tree view. So that means I am using my Up and Down Arrow keys to move through items, and Right Arrow to expand them.

      -

      Alex: Spot on. And this tree is organized brilliantly. It is like an email inbox that has already been sorted into folders for you. At the top, you have a section called My Pull Requests. If you expand that, you will find categories like Assigned to Me, Created by Me, and Waiting for my Review.

      -

      Jamie: Oh, that is incredibly helpful. So if I just want to see the things I am personally responsible for, I can just expand Assigned to Me.

      -

      Alex: Right. And as you arrow down through the list, your screen reader will announce the PR number, the title, the author, and the status. Something like: Pull Request number 42, Add Timeline Guide, opened by Jeff, 2 days ago.

      -

      Jamie: That is so much cleaner than tabbing through all the extra links and badges on the web interface. Though I should mention, if you prefer the web, or if you do not have VS Code open, you can still just navigate to the Pull Requests tab on your repository page on GitHub dot com.

      -

      Alex: Or use the GitHub Command Line Interface. If you have the gh CLI installed, you can open your terminal and type gh space pr space list. That prints out a beautifully clean text list of all open pull requests right in your console.

      -

      Jamie: So let us say I find Pull Request number 42 in that tree view, and I want to read it. What happens when I press Enter on it?

      -

      Alex: When you press Enter on a pull request in the tree, VS Code opens a Pull Request Detail View in your main editor area. This is a fully rendered, highly accessible document.

      -

      Jamie: What kind of information is in there?

      -

      Alex: Everything you would find on the Conversation tab on the web. It has the title, the description, the CI status checks telling you if the automated tests passed, a list of reviewers, and a section called Files Changed.

      -

      Jamie: Files Changed. That is the big one. That is where we see the diff, right? The actual code that was added or removed.

      -

      Alex: Exactly. A diff, short for difference, is the before-and-after comparison of the code. Now, you can review the diff simply by navigating to the Files Changed list in that detail view and pressing Enter on any file. It opens a split view or an inline view showing the changes.

      -

      Jamie: Okay, wait. Reading visual diffs with a screen reader used to be a nightmare for me. Hearing the screen reader try to parse out table columns, jumping between the old file and the new file. It was a lot of cognitive load.

      -

      Alex: It was. But VS Code has completely solved this with a feature called the Accessible Diff Viewer. This is perhaps the most important keyboard shortcut we will share today.

      -

      Jamie: I have my notepad ready.

      -

      Alex: When you have a diff open in the editor, press F7. This jumps your cursor directly to the first chunk of changed code, which is called a hunk.

      -

      Jamie: A hunk. I love programmer terminology.

      -

      Alex: It gets better. Once your cursor is on that change, press Alt plus F2 on Windows, or Option plus F2 on Mac. This opens the Accessible Diff Viewer.

      -

      Jamie: And what does that do?

      -

      Alex: It presents the change in a clean, sequential text format that is perfectly optimized for a screen reader. It announces exactly where you are, like Hunk 1 of 3. Then it reads the unchanged context lines, followed by the removed lines prefixed with the word Removed, and then the added lines prefixed with the word Added.

      -

      Jamie: Oh, that is brilliant. It is like comparing two drafts of a recipe. Instead of making you scan two pieces of paper side-by-side to figure out what changed, the Accessible Diff Viewer just reads it to you clearly: Removed: one cup of sugar. Added: two cups of sugar.

      -

      Alex: Exactly. And when you are done reading that hunk, you press Escape to close the viewer, and press F7 again to jump to the next change. It turns a frustrating visual layout into a logical, readable stream.

      -

      Jamie: And if I want to actually run their code to test it out? Can I do that?

      -

      Alex: Yes! That is called checking out a pull request. In the PR detail view, there is a Checkout button. When you activate it, VS Code downloads their branch to your local machine and switches your files over to their version. You can run the code, test it with your screen reader, and verify it actually works before you approve it.

      -

      Jamie: That is a massive advantage over the web interface. On the web, you can read the code, but you cannot easily run it.

      -

      Alex: Exactly. Though if you are using the terminal, you can achieve the same thing by typing gh space pr space checkout space 42. It pulls down the branch for pull request 42 instantly.

      -

      Jamie: Okay, so I am reading their code using the Accessible Diff Viewer, and I spot a mistake. They used a heading level two when it should have been a heading level three. How do I tell them?

      -

      Alex: You leave an inline comment. This is just like sticking a physical sticky note directly onto a specific line of a manuscript.

      -

      Jamie: How do I place the sticky note?

      -

      Alex: While you are in the diff view, navigate your cursor to the exact line with the mistake. Then, press Shift plus F10 on Windows, or Control plus Return on Mac, to open the context menu.

      -

      Jamie: Shift plus F10. Got it.

      -

      Alex: Navigate to Add Comment and press Enter. A text input box will appear right there in the editor. You type your feedback, like: This heading should be an H3 to maintain the document outline.

      -

      Jamie: And then I just hit submit?

      -

      Alex: You have two choices. You can choose Add Single Comment, which posts it to GitHub immediately. Or, you can choose Start Review.

      -

      Jamie: What is the difference?

      -

      Alex: Starting a review saves your comment as a draft. It lets you go through the rest of the files, leaving more comments as you go, without spamming the author with an email notification for every single typo you find. Once you are done looking at all the files, you submit the review all at once.

      -

      Jamie: That is polite. I appreciate that. So how do I submit the batch of comments when I am finished?

      -

      Alex: Open your Command Palette with Control plus Shift plus P, and type GitHub Pull Requests Finish Review.

      -

      Jamie: And that is where I give my final verdict, right?

      -

      Alex: Exactly. A prompt will ask you to choose a review type. You can select Comment, which just leaves your feedback without a formal decision. You can select Request Changes, which means the author must fix the issues before the code can be merged. Or, if everything looks great, you select Approve.

      -

      Jamie: And once I press Enter, all my draft comments and my final verdict are published to GitHub.

      -

      Alex: You got it.

      -

      Jamie: For folks tracking the alternatives, you can do all of this on the web by navigating to the Files Changed tab, finding a line, and activating the Add Comment button. And if you are a terminal fan, you can submit your verdict by typing gh space pr space review, followed by dash dash approve, or dash dash request dash changes.

      -

      Alex: So, we have covered reviewing other people's work. Let us flip the script. You have been writing code on a feature branch, you have committed your changes, and you have pushed them to GitHub. How do you create your own pull request from VS Code?

      -

      Jamie: I am going to guess it involves the Command Palette.

      -

      Alex: You know me so well. Press Control plus Shift plus P, and type GitHub Pull Requests Create. Select Create Pull Request, and a form opens right in your editor.

      -

      Jamie: What do I need to fill out in this form?

      -

      Alex: The most important concepts here are the Base branch and the Compare branch.

      -

      Jamie: Ah, yes. The terminology can be a little confusing at first. Base and Compare.

      -

      Alex: Let us use a highway analogy. The Base branch is the main highway. It is the destination. Usually, this is your main branch. The Compare branch is your car on the on-ramp. It is the source of the new changes you want to merge into traffic.

      -

      Jamie: That makes perfect sense. So my feature branch is the Compare branch, and I am requesting to merge it into the Base branch, which is main.

      -

      Alex: Exactly. VS Code usually selects these for you automatically, but it is good to verify them. After that, you just fill in the Title and the Description.

      -

      Jamie: On Day 1 of the workshop, when we opened pull requests on the web, we talked about Pull Request Templates. Those checklists that automatically populate the description box so you remember to test your code. Does VS Code support those?

      -

      Alex: It does! If your repository has a template file hidden in the dot github folder, the extension automatically loads it into your description field. You just use your arrow keys to navigate through the Markdown text, fill in the blanks, and put an X inside the brackets for the checkboxes.

      -

      Jamie: That is fantastic. It is literally the exact same workflow as the web.

      -

      Alex: It is. It maps perfectly to what you learned on Day 1. The underlying Git process is identical; you are just interacting with it through VS Code instead of a browser.

      -

      Jamie: Is there a way to open a Draft PR? Like, if I want to push my code to back it up and get early feedback, but I am not quite ready for a formal review?

      -

      Alex: Yes, there is a Draft PR checkbox right there in the creation form. If you check that, the PR is marked as a work in progress and cannot be merged until you mark it as ready. Once you have filled everything out, just Tab to the Create button and press Enter.

      -

      Jamie: And again, just to map this out for everyone: on the web, you would do this by pushing your code and then clicking the yellow Compare and Pull Request banner. In the CLI, you would just type gh space pr space create.

      -

      Alex: Alright, we have reached the final step of the lifecycle. The PR is open, the reviewers have approved it, and the CI checks are green. It is time to merge.

      -

      Jamie: The best feeling. How do we merge from VS Code?

      -

      Alex: Open the pull request in the PR detail view, scroll down to the bottom, and you will find a Merge Pull Request button. When you press Enter on it, you will be asked to choose a merge type.

      -

      Jamie: Merge types. This is where people get nervous. We have Merge Commit, Squash and Merge, and Rebase and Merge. Can we break those down?

      -

      Alex: Absolutely. Let us go back to our traffic analogy. You have a bunch of cars, which are your commits, waiting on the on-ramp, which is your feature branch. A Merge Commit is like a zipper merge. All of your individual cars merge onto the highway one by one, keeping their original identities, and a special sign is put up saying where they merged. It preserves your entire detailed history.

      -

      Jamie: Okay, what about Squash and Merge?

      -

      Alex: Squash and Merge is like taking everyone out of their individual cars and putting them all onto a single bus before they get on the highway.

      -

      Jamie: Oh, I love that.

      -

      Alex: It takes all of your tiny, messy commits, like "fix typo" and "forgot a semicolon", and squashes them into one single, clean commit on the main branch. This is incredibly common for feature branches to keep the project history tidy.

      -

      Jamie: And Rebase and Merge?

      -

      Alex: Rebase is like magically teleporting your cars so they were always on the highway to begin with. It replays your commits one by one at the very tip of the main branch, creating a perfectly straight, linear history without any merge signs.

      -

      Jamie: Which one should I use?

      -

      Alex: Always check your project's contributing guidelines. But if you are unsure, Merge Commit is the default and the safest option. Choose your strategy, confirm it, and the PR is merged.

      -

      Jamie: And then I should probably delete my feature branch, right? Keep the garage clean.

      -

      Alex: Exactly. VS Code will usually prompt you, asking if you want to delete the branch. Say yes. Then, use the Command Palette to check out your main branch and do a Git Pull, so your local machine gets the updated, merged code.

      -

      Jamie: And to round out our alternatives: on the web, this is the big green Merge button on the conversation tab. In the CLI, it is gh space pr space merge.

      -

      Alex: That covers the entire pull request lifecycle, entirely within VS Code. Let us recap our key takeaways.

      -

      Jamie: Takeaway number one: You do not have to leave your editor to collaborate. The GitHub Pull Requests extension lets you view, review, create, and merge PRs right where you write your code.

      -

      Alex: Takeaway number two: The Accessible Diff Viewer is a game changer for screen reader users. Remember to press F7 to jump to a change, and Alt plus F2, or Option plus F2 on Mac, to read the diff cleanly.

      -

      Jamie: Takeaway number three: The VS Code workflow maps exactly to the web workflow we learned on Day 1. The concepts of Base and Compare branches, PR templates, and Draft PRs are exactly the same. You are just using a different interface.

      -

      Alex: Perfectly summarized. Now that you are comfortable navigating code and collaborating in VS Code, you are ready for some artificial intelligence assistance. In our next episode, we are going to explore GitHub Copilot, and how it can help explain code, suggest changes, and write documentation.

      -

      Jamie: I cannot wait for that one. See you all then!

      -

      Alex: Thanks for listening to Gitt Going with GitHub.

      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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 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 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: 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: 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 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 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: 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 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. 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: 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. 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 "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: 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 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: 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 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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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 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. 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 13. Next in the series is episode 14, where we keep building the same contributor muscles.

      - +

      Episode 14: GitHub Copilot

      Inline suggestions, Copilot Chat, prompting strategies, and custom instructions.

      -

      Based on: Chapter 13: GitHub Copilot

      - - -

      Download Episode 14 (MP3)

      +

      Based on: Chapter 16: GitHub Copilot

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 14: GitHub Copilot

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub, the audio learning series for blind and low-vision developers who are mastering GitHub and open source collaboration. I am your host, Alex, and I am thrilled to be here with you today for episode fourteen, titled GitHub Copilot. Today, we are diving into the world of AI coding assistants.

      -

      Jamie: Hi everyone, I am Jamie. I am so excited for this one. I keep hearing developers talk about AI and Copilot, but I have been a little hesitant to jump in. I am really hoping we can break down how this actually works with a screen reader.

      -

      Alex: We absolutely will. Before we get into the new material, let us do a quick recap. In episode eleven, we covered the basics of Visual Studio Code. We talked about how to navigate the interface using your screen reader, how to open the command palette with Control plus Shift plus P, and how to manage your files. You will want to have those basic navigation skills fresh in your mind because Copilot lives right inside VS Code.

      -

      Jamie: I definitely recommend going back to episode eleven if you have not listened to it yet. Getting comfortable with the basic keyboard shortcuts in VS Code makes adding Copilot to the mix much easier. So, Alex, let us start at the very beginning. What exactly is GitHub Copilot?

      -

      Alex: At its core, GitHub Copilot is an AI pair programmer. But I like to think of it as a highly caffeinated, very well-read assistant sitting right next to you at your desk. As you type, it tries to guess what you are going to write next and offers suggestions. You can also talk to it conversationally and ask it questions about your project.

      -

      Jamie: When you say pair programmer, does that mean I only use this when I am writing code? Because as someone who is still learning, a lot of my open source contributions are actually documentation, writing issue responses, and formatting pull requests.

      -

      Alex: That is a fantastic question, and it is a huge misconception. Copilot is brilliant at non-code tasks. In fact, for this workshop, we are going to focus heavily on using Copilot to write Markdown documentation, draft commit messages, and review pull request descriptions. It understands human languages just as well as it understands Python or JavaScript.

      -

      Jamie: Oh, that is a relief. So how does it actually know what I am trying to do? Does it just read the current line I am on?

      -

      Alex: It reads much more than that. Copilot generates its suggestions based on context. Imagine you are cooking in a kitchen. A good sous-chef does not just look at the knife in your hand. They look at the ingredients you have already chopped on the cutting board, they look at the recipe book you have open on the counter, and they look at the pots on the stove. Based on all of that, they hand you the exact spice you need before you even ask for it.

      -

      Jamie: I love that analogy. So Copilot is looking at my whole kitchen.

      -

      Alex: Exactly. It looks at the file you are currently editing, where your cursor is positioned, other files you have open in your editor, and even the structure of your project. It gathers all of this context, sends it to the AI model, and returns a suggestion in milliseconds.

      -

      Alex: Let us talk about how these suggestions actually appear while you are typing. This is a feature called inline code completions. As you are typing a sentence or a line of code, Copilot will suddenly offer a completion for the rest of the line, or sometimes even an entire paragraph.

      -

      Jamie: I have heard sighted developers call this ghost text. What does that mean?

      -

      Alex: Yes, ghost text is the industry term for this. For a sighted user, the suggestion appears on their screen as light gray text just ahead of their cursor. It looks like a ghost because it is not actually part of the document yet. It is just a visual preview. But of course, visual previews are not helpful for us.

      -

      Jamie: Right. So how does my screen reader know the ghost text is there?

      -

      Alex: VS Code handles this beautifully by using an ARIA live region. When Copilot generates a suggestion, your screen reader will simply announce, suggestion available, or it will read the suggestion out loud, depending on how you have your verbosity settings configured.

      -

      Jamie: Okay, so I am typing, I hear suggestion available, and I want to accept it. What do I press?

      -

      Alex: You simply press the Tab key. Pressing Tab takes that ghost text and permanently inserts it into your document, moving your cursor to the end of the new text.

      -

      Jamie: And what if the suggestion is completely wrong? Like, it suggests I write about apples when I am writing about oranges.

      -

      Alex: You just press the Escape key to dismiss it. Or, honestly, you can just keep typing. The moment you type a letter that contradicts the suggestion, Copilot will dismiss it automatically and try to generate a new one based on your new keystrokes.

      -

      Jamie: That sounds easy enough. Tab to accept, Escape to dismiss. What if it gives me a suggestion, but I wonder if it has any other ideas? Can I ask for a different option?

      -

      Alex: You can. If you have a suggestion active and you want to see an alternative, you can press Alt plus the right bracket key. That will cycle to the next alternative suggestion. If you want to go back, you press Alt plus the left bracket key.

      -

      Jamie: Okay, that sounds like a lot of steps. I am imagining myself typing, getting interrupted by the screen reader, trying to cycle through options, and losing my train of thought.

      -

      Alex: It does sound intimidating! And it is completely normal to feel overwhelmed when your screen reader suddenly starts talking over you while you are trying to think. But here is the thing, you have already done most of this on Day one when we learned basic text editing. This is the exact same workflow, just with VS Code handling the heavy lifting of writing the text. And there are two incredible tricks to make this completely manageable.

      -

      Jamie: Please share the tricks, because I definitely need them.

      -

      Alex: The first trick is for when you only want part of the suggestion. Let us say Copilot suggests a whole sentence, but you only agree with the first few words. Instead of pressing Tab to accept the whole thing, you can press Control plus the right arrow key. This accepts the suggestion exactly one word at a time.

      -

      Jamie: Oh, that is clever! So I can just tap Control plus right arrow three times, take the first three words, and then just resume typing my own thought.

      -

      Alex: Exactly. It puts you completely in control. The second trick is even more important, and it solves the biggest current limitation with Copilot and accessibility.

      -

      Jamie: What limitation is that?

      -

      Alex: When Copilot generates a long suggestion, it streams the text in piece by piece, or token by token. For a sighted user, this looks like the text is being typed out really fast. But for a screen reader, this streaming effect can cause the live region to update repeatedly. It fragments the announcements. You might hear half a sentence, then an interruption, then the end of the sentence. It can be very noisy and hard to understand.

      -

      Jamie: Yes, I have experienced that with other AI tools. It is like someone trying to read you a letter while it is still coming out of the printer.

      -

      Alex: That is a perfect description. To solve this, VS Code has a feature called the Accessible View. Whenever you hear that a suggestion is available, do not press Tab yet. Instead, press Alt plus F2.

      -

      Jamie: Alt plus F2. What does that do?

      -

      Alex: It pauses the action and opens the complete suggestion in a separate, static text panel called the Accessible View. There is no streaming noise. There are no live region interruptions. It is just plain text. You can use your up and down arrow keys to read the suggestion line by line at your own pace.

      -

      Jamie: I wish I had known that when I started. So I press Alt plus F2, I read the suggestion in peace, and then what? How do I get it into my document?

      -

      Alex: While you are still inside the Accessible View, if you decide you like the text, you just press Control plus slash. That immediately inserts the suggestion into your document at your original cursor position and closes the Accessible View. If you do not like the suggestion, you just press Escape to close the view and go back to typing.

      -

      Jamie: That changes everything. Alt plus F2 to read it, Control plus slash to insert it. That feels so much more controlled.

      -

      Alex: Now that we have conquered inline suggestions, let us talk about the other half of GitHub Copilot. The Chat interface.

      -

      Jamie: This is where I can actually talk to it, right? Like a messaging app?

      -

      Alex: Exactly. You can open the Copilot Chat panel at any time by pressing Control plus Shift plus I. This opens a dedicated view in your sidebar. When you press Control plus Shift plus I, your screen reader will focus an input field. From there, you can ask questions in natural language.

      -

      Jamie: When you say natural language, do you mean I do not have to write code to talk to it?

      -

      Alex: Right. You just talk to it like you would talk to a human colleague. You could type, how do I create a pull request using the GitHub command line interface? Or, can you explain what this Markdown file is used for? Then you press Enter to send the message.

      -

      Jamie: And does the answer stream in and get all fragmented like the inline suggestions?

      -

      Alex: It does stream in, yes. But you can use the exact same trick. As soon as you press Enter to send your question, immediately press Alt plus F2 to open the Accessible View. The response will stream safely into that static view, and you can just use your arrow keys to read it. The Accessible View even formats code blocks and headings properly so your screen reader announces them correctly.

      -

      Jamie: That is so consistent. I love that the same shortcut works in both places. So, what if I want to ask a question about a specific file, or a specific part of VS Code? Does it just know what I am thinking about?

      -

      Alex: It is smart, but it cannot read your mind. To help Copilot understand exactly what you are asking about, we use Chat Participants. You can think of these like directing your question to a specific expert department in a massive company. You invoke them by typing the at symbol, followed by the participant name.

      -

      Jamie: Like tagging someone on social media?

      -

      Alex: Exactly like that. The three most common ones you will use are at workspace, at terminal, and at vscode.

      -

      Jamie: Let us break those down. What does at workspace do?

      -

      Alex: If you start your chat message with at workspace, Copilot will search across every single file in your current project folder to find the answer. So you could ask, at workspace, where do we document our accessibility guidelines? Copilot will scan the entire repository, find the contributing guide, and summarize the answer for you.

      -

      Jamie: That is incredible. It saves me from having to open a dozen files and use the find command. What about at terminal?

      -

      Alex: At terminal is a lifesaver when you get an error message on the command line that you do not understand. If you type at terminal, what does this error mean, Copilot will look at the recent text in your VS Code integrated terminal, read the error output, and explain it to you in plain English.

      -

      Jamie: Oh, I am definitely going to use that. Command line errors always look like a wall of gibberish to me. And the last one was at vscode?

      -

      Alex: Yes, at vscode. This participant is the expert on the VS Code editor itself. If you forget a keyboard shortcut, or you do not know how to change a setting, you just ask, at vscode, how do I turn on word wrap? It will give you the exact steps and the keyboard shortcuts.

      -

      Jamie: So participants tell Copilot where to look. Are there ways to tell Copilot what kind of action I want it to take?

      -

      Alex: Yes! For that, we use slash commands. If you type a forward slash in the chat input, you invoke a specific command. There are four major ones to memorize: slash explain, slash fix, slash tests, and slash doc.

      -

      Jamie: Those sound pretty self-explanatory, but let us go through them. Slash explain?

      -

      Alex: If you select a paragraph of complex text, or a dense block of code, and type slash explain, Copilot will break it down and explain how it works step by step. This is amazing when you are reading someone else's pull request and you cannot figure out what their code is doing.

      -

      Jamie: And slash fix?

      -

      Alex: If you select a broken piece of code, or even a Markdown table that is not formatted correctly, you type slash fix. Copilot will analyze the selection, figure out what is wrong, and propose a corrected version that you can accept.

      -

      Jamie: That is so much faster than hunting for a missing comma. What about slash tests and slash doc?

      -

      Alex: Slash tests will automatically generate unit tests for a function you have selected. And slash doc will automatically write the formal documentation block above a function or class. They are massive time savers for the repetitive parts of software development.

      -

      Jamie: Okay, so we have participants like at workspace to set the context, and commands like slash explain to set the action. I feel like I am learning a new syntax. But you said earlier I could just use natural language. Is there a trick to getting good answers when I am just typing regular sentences?

      -

      Alex: There is absolutely an art to it. We call it effective prompting. The biggest mistake beginners make is being too vague. If you type, write about accessibility, Copilot will give you a very generic, boring encyclopedia entry.

      -

      Jamie: So what makes a good prompt?

      -

      Alex: A good prompt is specific, it provides context, and it sets constraints. Think about ordering a sandwich at a deli. You do not just walk up and say, make me food. You say, I would like a turkey sandwich on rye bread, no mayo, add mustard, and please cut it in half.

      -

      Jamie: I am getting hungry. But I see your point. How does the sandwich order translate to Copilot?

      -

      Alex: Instead of saying, write about accessibility, you would say, write a three-paragraph section explaining how screen reader users can navigate the VS Code sidebar. Include keyboard shortcuts for NVDA. Assume the reader is a beginner. Use clear headings and bullet points.

      -

      Jamie: Wow, that is incredibly specific. You gave it the topic, the audience, the length, and the formatting.

      -

      Alex: Exactly. And the best part of effective prompting is iterating. Copilot remembers the conversation. So if it gives you an answer and it is a little too technical, you do not have to start over. You just reply, make that a little simpler, or, rewrite that in a friendlier tone. It will adjust the text immediately.

      -

      Jamie: Alex, I noticed in the settings there is a place to choose different AI models. What does that mean? Why are there different models?

      -

      Alex: That is a great observation. GitHub Copilot does not just rely on one single AI brain. It gives you access to multiple AI models from different companies, like OpenAI, Anthropic, and Google. You can switch between them using the model picker, which is a dropdown menu located at the bottom of the chat panel.

      -

      Jamie: Why would I want to switch? Are they really that different?

      -

      Alex: They are! Think of it like hiring different contractors for different jobs. If you select the GPT five mini model, it is incredibly fast and completely free to use. It is great for everyday questions and quick code completions. It is like riding a bicycle for a quick errand.

      -

      Jamie: But what if I have a really complex problem? Like a bug that spans across five different files?

      -

      Alex: Then you might want to open the model picker and select something like Claude Sonnet four point six, or GPT five point two. These models have much deeper reasoning capabilities. They are like renting a heavy-duty moving truck. They are slower, and if you are on a paid plan, they consume what are called premium requests, but they can handle incredibly complex logic.

      -

      Jamie: That makes sense. But honestly, having to choose which model to use every time I ask a question sounds exhausting.

      -

      Alex: I completely agree. And that is why the default setting in the model picker is simply called Auto mode.

      -

      Jamie: Auto mode. Let me guess, it chooses the vehicle for me?

      -

      Alex: Exactly. When you leave the model picker on Auto, Copilot evaluates your prompt behind the scenes. If you ask a simple question, it routes it to a fast, lightweight model. If you ask it to architect a complex new feature, it automatically upgrades to a heavy-duty model like Codex. It manages the cost and the speed for you, so you can just focus on writing.

      -

      Jamie: I will definitely be leaving that on Auto.

      -

      Jamie: So, Alex, I have a question about consistency. If I am working on an open source project, and we have very specific rules. For example, let us say our project requires all Markdown headings to use sentence case, and we never use the word click in our documentation. Do I have to type those rules into my prompt every single time I ask Copilot to write something?

      -

      Alex: That would be incredibly tedious. Thankfully, the answer is no. This brings us to one of the most powerful features for project maintainers: custom instructions files.

      -

      Jamie: Custom instructions. Is that a setting in VS Code?

      -

      Alex: It is actually a file you commit directly to your repository. You create a regular text file at the path dot github, slash copilot dash instructions dot m d.

      -

      Jamie: So it is just a Markdown file living in the dot github folder?

      -

      Alex: Exactly. And it acts like an employee handbook for Copilot. You can write your project's rules in plain English in that file. You might write, always write for screen reader users first. Never skip heading levels. Use imperative mood for commit messages.

      -

      Jamie: And Copilot just reads this file automatically?

      -

      Alex: Yes! Once that file is committed to your repository, Copilot silently reads it in the background every single time you ask a question or generate a completion. You never have to mention it. Copilot simply follows the rules of the house.

      -

      Jamie: That is brilliant. So if someone clones my repository and uses Copilot, their Copilot will automatically follow my accessibility rules?

      -

      Alex: Exactly. It is a fantastic way to enforce accessibility standards across an entire team without being a micromanager. Now, there is one more file type I want to mention, which is related to custom instructions, and that is prompt files.

      -

      Jamie: Prompt files. How are those different from the instructions file?

      -

      Alex: The instructions file is always on, in the background. Prompt files allow you to create your own custom slash commands that you invoke on demand. They are stored in the dot github, slash prompts folder, and they end with the extension dot prompt dot m d.

      -

      Jamie: Oh, I see. So earlier we talked about built-in commands like slash explain. I can make my own?

      -

      Alex: You got it. Let us say you do a lot of accessibility audits. You could create a file called dot github, slash prompts, slash audit dot prompt dot m d. Inside that file, you write a detailed prompt asking the AI to check for missing alt text, skipped headings, and improper link names.

      -

      Jamie: And then in the chat panel, I just type slash audit?

      -

      Alex: Exactly. You type slash audit, and Copilot executes that massive, detailed prompt perfectly every single time. It saves you from having to type out complex requests over and over again.

      -

      Jamie: Alex, this has been an incredibly packed episode. We went from ghost text to custom AI employees.

      -

      Alex: It is a lot to take in! But remember, you do not have to use all of this on day one. Start by just leaving Copilot turned on while you write, and get used to how it feels. Let us wrap up with our key takeaways for today.

      -

      Jamie: I will take the first one. When Copilot offers an inline suggestion, your screen reader will announce it. You can press Tab to accept the whole thing, Escape to dismiss it, or my favorite, Control plus the right arrow key to accept it one word at a time.

      +

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

      +

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

      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: 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 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 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: 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 "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 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.

      - +

      Episode 15: Accessible Code Review

      Navigating diffs with a screen reader, reviewing PRs in browser and VS Code.

      -

      Based on: Chapter 14: Accessible Code Review

      - - -

      Download Episode 15 (MP3)

      +

      Based on: Chapter 15: Accessible Code Review

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 15: Accessible Code Review

      Transcript

      -

      Alex: Welcome back to Gitt Going with GitHub. This is episode fifteen, Accessible Code Review. I am your host, Alex.

      -

      Jamie: And I am Jamie! I am so ready for this one.

      -

      Alex: Today is all about the reviewer experience. We are going to cover how to navigate file changes, read code comparisons, leave helpful comments, and submit your final review, entirely using your keyboard and screen reader.

      -

      Jamie: Before we jump in, let us quickly remind everyone of a couple of prerequisites. We will be building heavily on two previous episodes. First, episode six, where we introduced the concept of pull requests and the general review process. And second, episode eleven, which covered VS Code accessibility features. If you have not listened to those yet, you might want to open them up and give them a quick listen first.

      -

      Alex: Exactly. Now, in episode six, we talked about how a pull request, or PR, is a way to propose changes to a repository. You are literally requesting that the maintainers pull your code into their project. But before they do that, someone needs to review it.

      -

      Jamie: So, Alex, let us start with the big picture. Why is code review so important? When I first started learning GitHub about two years ago, I thought code review was just a way for senior developers to catch my typos.

      -

      Alex: That is a very common misconception. Code review does catch bugs, but it is fundamentally about quality and learning. It is a two-way street. The author gets another set of eyes on their work, and the reviewer gets to learn new techniques or familiarise themselves with a different part of the codebase.

      -

      Jamie: I love that. It reminds me of a writer's workshop. You do not just hand your manuscript to an editor to fix your grammar. You share it with peers. They might point out that a character's motivation is confusing, or they might learn a new way to write dialogue by reading your work.

      -

      Alex: That is a brilliant analogy. And just like a writer's workshop, building a habit of reviewing others' work regularly is one of the fastest ways to level up your own skills.

      -

      Jamie: I will be honest, though. Reviewing code still feels intimidating sometimes. Especially when I am looking at a pull request from someone who has been coding for ten years longer than I have.

      -

      Alex: It does feel intimidating! But here is the thing, you bring a unique perspective. Even if you do not catch a complex logic bug, you might catch an unclear variable name, or a missing documentation update. What we look for in a review really falls into four categories. Correctness, clarity, style, and accessibility.

      -

      Jamie: Correctness meaning, does the code actually do what it is supposed to do?

      -

      Alex: Right. Clarity means, is it easy to understand? Style means, does it follow the project's conventions? And accessibility means, does this change introduce any barriers for users with disabilities? You do not have to be an expert in all four to leave a valuable review.

      -

      Jamie: Okay, so I am sold on the why. Let us talk about the where. Where do we actually do these reviews?

      -

      Alex: You have two main environments for code review. The GitHub web interface in your browser, and your local code editor, which for our workshop is VS Code.

      -

      Jamie: Is one better than the other?

      -

      Alex: They just have different strengths. Both give you full keyboard and screen reader access. I like to think of the web browser as a quick chat at a coffee shop. It is great for quick reviews, leaving a few comments, and you can do it from any machine without downloading the code.

      -

      Jamie: And VS Code?

      -

      Alex: VS Code is like setting up in your home office for deep work. It is best for large reviews where you need to navigate through a lot of files, test the code locally, or use advanced screen reader features.

      -

      Jamie: I should also mention there is a third path, right? The GitHub CLI, or command line interface.

      -

      Alex: Yes, absolutely. The GitHub CLI is fantastic. You can open your terminal and type gh pr review to approve or request changes without ever leaving the command line. It is like the drive-through window of code review. Very fast, very efficient, but maybe not where you want to sit down and leave twenty detailed inline comments.

      -

      Jamie: Let us start with the coffee shop. The web browser. When I open a pull request on GitHub, how do I actually read the changes?

      -

      Alex: You need to navigate to the Files Changed tab. When you load a pull request page, you are usually on the Conversation tab, which has the description and the comments.

      -

      Jamie: Right, so how do I get to the files?

      -

      Alex: The most reliable way with a screen reader is to use your landmark navigation. Press the D key if you are using NVDA or JAWS, or use your VoiceOver landmarks rotor, to navigate to the Pull request navigation tabs landmark. From there, you can press the Right Arrow or Tab key to find the Files changed link, and press Enter.

      -

      Jamie: And when I open that, what am I actually listening to?

      -

      Alex: You are listening to a diff. Diff is short for difference. It is a format that shows exactly what changed between the old version of a file and the new version.

      -

      Jamie: I always explain a diff like a recipe where someone has crossed out a line and written a new one. Imagine a recipe card that says one cup of sugar, but the words one cup have a line through them, and next to it, someone wrote two cups.

      -

      Alex: That is exactly what a unified diff format looks like. It is called unified because it shows the old and new text combined into a single continuous flow. Every line in a diff is categorized in one of three ways. An addition line, a deletion line, or a context line.

      -

      Jamie: Let us break those down.

      -

      Alex: An addition line is new code that the author added. It starts with a plus sign prefix. A deletion line is code the author removed. It starts with a minus sign prefix.

      -

      Jamie: And context lines?

      -

      Alex: Context lines are the unchanged lines of code right above and below the changes. They do not have a plus or minus prefix. They are just there to give you context, so you know where the change is happening in the file.

      -

      Jamie: Okay, so I am on the Files Changed tab. How do I navigate through this diff?

      -

      Alex: First, orient yourself using the file tree. This is a region on the page that lists every changed file. You can navigate to the File tree region using your landmark shortcut, and just press the Down Arrow to move through the list. It will announce the file name, and how many additions and deletions it has.

      -

      Jamie: That is so helpful for getting a summary. If I see a file has five hundred additions, I know I need a coffee.

      -

      Alex: Exactly. Once you know what files you are dealing with, you can move to the actual code. Each changed file is presented under a heading level three containing the file name. So you can just press the number 3 key on your keyboard to jump from file to file.

      -

      Jamie: And what happens when I reach a file I want to read?

      -

      Alex: The diff for each file is structured as a table. Every row in the table is one line of code. To read it, you will navigate to the table using the T key. Then, and this is important, you need to turn on Focus Mode if you are using NVDA, or turn off the Virtual PC Cursor if you are using JAWS.

      -

      Jamie: Ah, right. Because in Browse Mode, pressing the Down Arrow just moves through the page structure. In Focus Mode, your arrow keys let you navigate the table cells directly.

      -

      Alex: Precisely. Once you are interacting with the table, you can press the Down Arrow to move through the lines of code one at a time. To read across the columns of a specific line, you press Control plus Alt plus the Right Arrow key. It will read the line number, then the change type, meaning whether it was added or deleted, and then the actual code content.

      -

      Jamie: Okay, so I am reading down the table, line by line. I hear a minus prefix, then a plus prefix, so I know a line was replaced. Let us say I spot a problem. The author changed a heading, but they skipped a heading level. They went from level two to level four. As an accessibility advocate, I know that breaks navigation for screen reader users. How do I tell them?

      -

      Alex: You need to write an inline review comment. This means you are attaching your comment directly to the specific line of code that has the issue, rather than just leaving a general comment at the bottom of the page.

      -

      Jamie: Like sticking a post-it note exactly on the sentence in a book that needs a rewrite.

      -

      Alex: Exactly. To do this, while your focus is on that specific line in the diff table, press the Tab key to look for a comment button. Or you can press the B key to navigate to the next button, which will say Add a comment to this line.

      -

      Jamie: Okay, that sounds like a lot of steps.

      -

      Alex: It does! But here is the thing, you have already done most of this on Day One of the workshop. It is the exact same workflow as opening an issue or replying to a discussion, just attached to a line of code. You press Enter on that button, an inline comment box opens, you switch to Focus Mode, and you type your feedback.

      -

      Jamie: What makes a good review comment? I remember early on, I would just write things like, this is wrong, or please fix. And people would get frustrated because they did not know what I wanted.

      -

      Alex: A helpful review comment is specific, educational, and graduated.

      -

      Jamie: Graduated? What does that mean?

      -

      Alex: It means signalling how important the comment is. Is it a strict requirement that blocks the pull request from merging, or is it just a stylistic preference? Using prefixes at the start of your comment is a great way to set expectations.

      -

      Jamie: Oh, I love prefixes. I use the word nit, spelled N I T, all the time. Like, nit, the link text says click here, which is not great for screen readers. Consider changing it to read the setup guide.

      -

      Alex: That is a perfect example. Nit means a non-blocking stylistic preference. Another good prefix is blocking. For your heading example, you could write, blocking, heading hierarchy violation. This skips level three. Please change to a level three heading before this merges.

      -

      Jamie: That is so clear. It names the issue, explains why it matters, and tells them exactly how to fix it.

      -

      Alex: Right. And once you type that comment, you tab to the button that says Start a review, and press Enter.

      -

      Jamie: Wait, why Start a review? Why not just click Add single comment?

      -

      Alex: If you use Add single comment, it posts immediately and sends an email notification to the author right then and there. If you leave ten comments, they get ten emails. Start a review batches all your comments together into a draft. When you are done looking at all the files, you submit the review all at once, and they get one single notification. It is much kinder to your teammates.

      -

      Jamie: Let us talk about that final submission. I have gone through all the files, I have left my post-it notes on various lines. How do I wrap this up?

      -

      Alex: You need to submit your review. You navigate to the top right of the Files Changed page, or the bottom of the Conversation tab, and find the Review changes button. Press Enter on that, and a dialog opens.

      -

      Jamie: This is where I give it my final grade, right?

      -

      Alex: Exactly. The dialog has a summary text area where you can write an overall thought, like, great work, just a few accessibility tweaks needed. Below that are three radio buttons for your verdict. Comment, Approve, or Request changes.

      -

      Jamie: Approve is pretty obvious. It means the code looks good to me, let us merge it. Request changes means I found a blocking issue, and they need to fix it before it can merge. What about Comment?

      -

      Alex: Comment means you have observations or questions, but you do not have a strong position on whether it should be blocked or approved. You are just leaving notes. Once you select your radio button, tab to Submit review, and press Enter.

      -

      Jamie: Okay, so that is the coffee shop experience. The web browser. It is incredibly powerful, but navigating those diff tables can get a little tedious if a pull request has hundreds of changes.

      -

      Alex: And that is exactly why we have the home office. VS Code. When you are dealing with a large review, VS Code offers a feature that completely changes the game for screen reader users. It is called the Accessible Diff Viewer.

      -

      Jamie: I remember the first time I used this. It was an absolute revelation.

      -

      Alex: How would you describe the difference between the browser diff and the VS Code Accessible Diff Viewer?

      -

      Jamie: In the browser, as we discussed, it is a big table. You have to navigate down rows, and across columns to figure out what line you are on, whether it is a plus or minus, and what the text says. The Accessible Diff Viewer is like a guided museum audio tour. It skips all the empty hallways and unchanged context lines, and just takes you straight to the exhibits that actually changed, and tells you exactly what happened to them.

      -

      Alex: That is a beautiful way to put it. Let us walk through how to use it. First, you open the pull request in VS Code. If you have the GitHub Pull Requests extension installed, you can open the Command Palette with Control plus Shift plus P, and search for GitHub Pull Requests View Pull Request.

      -

      Jamie: And once the pull request is open, the changed files appear in a tree on the sidebar. You navigate to a file and press Enter to open its diff editor.

      -

      Alex: Right. Now, when the standard diff editor opens, it is still a side-by-side visual comparison, which can be noisy. But here is the magic trick. Press the F7 key.

      -

      Jamie: F7. The magic button. What happens?

      -

      Alex: The Accessible Diff Viewer opens as a dedicated panel. Instead of a table, it presents each change, which programmers sometimes call a hunk, as a structured block of text designed specifically for sequential listening.

      -

      Jamie: So what does my screen reader actually say when I press F7?

      -

      Alex: It announces something like this. Changed lines fourteen to fourteen in docs slash keyboard-shortcuts dot markdown. Change one of three. Removed, heading level four, NVDA Single-Key Navigation. Added, heading level three, NVDA Single-Key Navigation.

      -

      Jamie: It is just so clean. It tells me exactly where I am, how many changes there are in total, and gives me clear Removed and Added labels. I do not have to guess what changed.

      -

      Alex: Exactly. And the navigation is purpose-built. You just press F7 again to jump to the next change. Or Shift plus F7 to jump to the previous change. You do not have to mess around with table navigation or focus modes. It just works with NVDA, JAWS, and VoiceOver right out of the box.

      -

      Jamie: And if I want to leave a comment while I am in VS Code?

      -

      Alex: You close the Accessible Diff Viewer by pressing Escape. That puts your cursor right back on the line you were just reviewing in the main editor. From there, you can open the Command Palette with Control plus Shift plus P, and select GitHub Pull Requests Add Comment. A text area opens, you type your comment, and submit it.

      -

      Jamie: And those comments sync directly back to GitHub, right? The author sees them on the web exactly as if I had used the browser.

      -

      Alex: Yes, they sync instantly. The author gets the exact same experience. They do not know or care which tool you used to write the review.

      -

      Jamie: This is so empowering. Whether I use the browser for a quick check or VS Code for a deep dive, I have complete access to the review process.

      -

      Alex: You do. And developing this manual review skill is critical. You need to know how to spot a heading hierarchy issue, or a missing alt attribute, or unclear link text yourself.

      -

      Jamie: Why is that so critical?

      -

      Alex: Because in our next episode, we are going to introduce Accessibility Agents. These are AI tools that can automatically scan a pull request and draft a review for you.

      -

      Jamie: Oh, wow. So the AI just does the review for me?

      -

      Alex: Not quite. The AI generates a draft. It will point out potential issues and suggest comments. But the AI does not have your human judgment. Your job shifts from finding every single issue manually, to reading the AI's draft, verifying if it is correct, and deciding what is actually worth saying to the author.

      -

      Jamie: I see. So if I do not know what a good review looks like, I will not know if the AI is giving me good advice.

      -

      Alex: Exactly. The manual skill is the foundation. The AI is just an amplifier.

      -

      Jamie: Let us wrap this up with a few concrete takeaways from today's episode. Number one, code review is a two-way street for quality and learning. It is not just about finding bugs, it is about improving the whole team.

      -

      Alex: Number two, you have two great environments. The browser is fantastic for quick, accessible reviews using landmark and table navigation. But for deep, line-by-line reading, press F7 in VS Code to open the Accessible Diff Viewer for a streamlined, sequential experience.

      -

      Jamie: Number three, when writing comments, be specific, educational, and graduated. Use prefixes like nit or blocking to clearly communicate your expectations to the author.

      -

      Alex: And number four, always use Start a review to batch your comments, rather than sending a dozen single comment notifications.

      -

      Jamie: This has been incredibly helpful. I feel like I am ready to go leave some blocking post-it notes on some pull requests.

      -

      Alex: I am sure your team will appreciate the thorough feedback. Thank you all for listening to Gitt Going with GitHub. In episode sixteen, we will dive into those Accessibility Agents and see how AI can speed up your workflow. Until then, keep practicing those reviews.

      -

      Jamie: See you next time!

      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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 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 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: 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: 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 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 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: 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 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. 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: 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. 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 "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: 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 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: 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 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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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 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. 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 15. Next in the series is episode 16, where we keep building the same contributor muscles.

      - +

      Episode 16: Issue Templates

      Creating YAML-based issue templates for bug reports, features, and custom forms.

      -

      Based on: Chapter 15: Issue Templates

      - - -

      Download Episode 16 (MP3)

      +

      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 Gitt Going with GitHub. This is episode 16, Issue Templates. I am Alex, and as always, I am joined by Jamie.

      -

      Jamie: Hello everyone! I am very excited for this one because, if you remember way back in episode 5, we talked about how to file an issue. And I mentioned that staring at a completely blank text box was one of the most intimidating parts of learning GitHub for me. I never knew what information I was supposed to provide.

      -

      Alex: It is a universal feeling. You find a bug, you navigate to the Issues tab, you activate the New Issue button, and GitHub just hands you a blank page. You are left wondering, what do the maintainers actually need to know? Do they want my operating system? My screen reader version? Steps to reproduce?

      -

      Jamie: Exactly. And then you write what you think is a helpful description, and a day later a maintainer replies asking for exactly the details you left out. It is frustrating for everyone. It feels like a lot of unnecessary back and forth.

      -

      Alex: That is exactly the problem issue templates solve. Today, we are going to learn what issue templates are, how to use them, and most importantly, how to create them for your own repositories. We will cover where they live in your project, how to configure them, and the two different types of templates. We have traditional Markdown templates, and we have YAML form templates. We will talk about why YAML forms are a massive upgrade for screen reader accessibility.

      -

      Jamie: I love anything that makes screen reader navigation smoother. And just to remind our listeners, if you have not listened to episode 5 on working with issues, you might want to brush up on that first. But if you know how to navigate to the Issues tab and activate the New Issue button, you are ready for today.

      -

      Alex: Perfect. Let us start by defining what an issue template actually is. Think of an issue template like going to a new doctor. When you walk in, the receptionist does not just hand you a blank piece of paper and say, write down why you are here.

      -

      Jamie: Right, they give you an intake form. It asks for your name, your symptoms, your medical history, your current medications. It guides you to provide exactly what the doctor needs to know before they even see you.

      -

      Alex: Exactly. An issue template is an intake form for your GitHub repository. It turns that intimidating blank text editor into a structured guide. When contributors use a template, they provide the exact information you need to triage their issue. This drastically improves the quality of the issues you receive and reduces the burden on you as a maintainer. You spend less time asking follow up questions and more time actually fixing bugs.

      -

      Jamie: So as a user, when I activate that New Issue button on a repository that has templates set up, what actually happens? Because I know I do not just drop straight into a text editor anymore.

      -

      Alex: Right. When a repository has multiple templates, GitHub places a new step in between. You land on what is called the template chooser page. Your screen reader will announce a list of available templates. Each template appears as a card with a title, a short description, and a button that says Get started.

      -

      Jamie: So I might hear something like, Bug Report, report a problem with the software, Get started button. And if I press Enter on that button, then I am taken to the actual form.

      -

      Alex: Exactly. And the beauty of this template chooser page is that you, as the repository owner, can completely customize it using a special file called config dot y m l. That is spelled c o n f i g dot y m l.

      -

      Jamie: I have heard of YAML files before. Y A M L. It is a text format used for configuration, right?

      -

      Alex: Yes. YAML is a data serialization language, which is just a fancy way of saying it is a way to write structured data using plain text and indentation. It is very common for configuration files. In your config dot y m l file, you can control a few really important things about the template chooser page.

      -

      Jamie: What kind of things? Like adding more templates?

      -

      Alex: Actually, the templates themselves live in their own files. The config file is like the lobby directory of a large office building. It tells people where to go. One of the best features is that you can add external links. Let us say someone wants to ask a general question, not report a bug. You can add a contact link in your config file that points them to a GitHub Discussions board, or a community Slack channel.

      -

      Jamie: Oh, that is clever! So right on the page where they are about to file an issue, you can intercept them and say, hey, if you just have a question, go over here instead. That must save so much clutter in the issue tracker.

      -

      Alex: It really does. Another common use case for external links is security vulnerabilities. You never want someone posting a security flaw in a public issue. So you can add a link to the chooser page that directs them to a private security reporting form.

      -

      Jamie: That makes perfect sense. Now, what if I just want to write a regular issue? Can I bypass the chooser page and just get a blank text box?

      -

      Alex: By default, yes. At the bottom of the template chooser page, there is a link that says Open a blank issue. However, in your config dot y m l file, you have the power to turn that off. You can set a property called blank issues enabled to false.

      -

      Jamie: Wow. So you can force people to use your templates. That sounds a little strict, but I can completely see why a maintainer would do that. If you need their screen reader version to fix a bug, and they keep skipping the template, you just disable the blank issue option.

      -

      Alex: Exactly. For accessibility projects in particular, disabling blank issues is one of the most effective ways to improve the quality of incoming reports. An accessibility bug report without reproduction steps or assistive technology versions is almost impossible to triage.

      -

      Jamie: Okay, so we have the template chooser page, which is controlled by the config dot y m l file. Where do all these files actually live in my project?

      -

      Alex: They live in a very specific hidden folder. In the root directory of your repository, you will create a folder called dot github. Inside that dot github folder, you create another folder called ISSUE underscore TEMPLATE. That is all uppercase, issue underscore template.

      -

      Jamie: Okay, so the path is dot github slash issue underscore template. And inside that folder is where I put my config dot y m l file, and also all my actual template files.

      -

      Alex: You got it. Now, let us talk about how to build those template files. As I mentioned earlier, there are two ways to do this. The older, traditional way is using Markdown templates. These are files that end in dot m d.

      -

      Jamie: Markdown is the formatting language we use all over GitHub, right? With the hash symbols for headings and things like that.

      -

      Alex: Exactly. A Markdown template is essentially a text file that pre fills the issue editor. When a user selects your Markdown template from the chooser page, they are dropped into the standard issue text box, but the box already has text in it.

      -

      Jamie: Like a Mad Libs page! The headings are already there, and maybe some placeholder text, and I just have to type my answers in between the headings.

      -

      Alex: That is a perfect analogy. It is exactly like a fill in the blank Mad Libs page. To create one, you just create a Markdown file in your issue template directory. But there is a special section at the very top of the file called YAML front matter.

      -

      Jamie: Front matter. That sounds like the title pages of a book. What does it do?

      -

      Alex: Think of YAML front matter like a routing slip attached to the front of a physical file folder. It is a block of YAML code at the very top of your Markdown file, enclosed by three dashes at the top and three dashes at the bottom. This routing slip tells GitHub metadata about your template.

      -

      Jamie: What kind of metadata?

      -

      Alex: Five key things. First, the name of the template. This is what appears as the title on the template chooser page. Second, the description, which is the short text that appears under the name. Third, you can specify a title. This is really cool because you can pre fill the title of the issue itself. For example, you could have the title automatically start with a bracketed word like BUG, so every issue filed with this template has a consistent naming convention.

      -

      Jamie: Oh, I wish I had known that when I started. I always wondered how some projects had such perfectly formatted issue titles. What are the other two things in the front matter?

      -

      Alex: Labels and assignees. You can provide a comma separated list of labels, like bug or needs triage. When the user submits the issue, GitHub automatically applies those labels. And you can do the same with assignees, automatically assigning a specific maintainer to issues created with this template.

      -

      Jamie: That routing slip analogy is perfect. The front matter handles all the administrative sorting, labeling, and titling automatically. And then below those three dashes, I just write standard Markdown for the body of my template.

      -

      Alex: Exactly. You use hash marks for your section headings, like Steps to Reproduce, or Expected Behavior. You can also use HTML comments to leave instructions that the user can read, but that will not show up when the issue is finally published.

      -

      Jamie: Markdown templates sound really easy to set up. But you mentioned there was a second type. A YAML form template. Why would we use that instead?

      -

      Alex: Markdown templates are easy, but they have a massive flaw when it comes to accessibility and data consistency. Because a Markdown template just dumps text into a giant open text box, the user can do whatever they want. They can accidentally delete your headings. They can ignore your instructions. And most importantly, for a screen reader user, navigating a pre filled text box full of HTML comments and placeholder text can be incredibly noisy and confusing.

      -

      Jamie: That is so true. When I open a Markdown template, my screen reader just announces a massive block of text, and I have to use my arrow keys to carefully find the exact spot where I am supposed to start typing, making sure I do not accidentally delete the formatting. It is tedious.

      -

      Alex: Enter YAML form templates. These are files that end in dot y m l instead of dot m d. When a user selects a YAML form template, GitHub does not give them a single giant text box. Instead, GitHub generates a proper, accessible web form.

      -

      Jamie: Like a digital tax software wizard! Instead of handing you a blank tax form and saying good luck, the software asks you one question at a time with specific input fields.

      -

      Alex: Yes! A YAML form template creates distinct form fields. Each field has an explicit, programmatic label that your screen reader will announce. You navigate the template just like any other web form, pressing the Tab key to move from the operating system field, to the browser field, to the description field.

      -

      Jamie: That sounds so much better. What kinds of fields can we build with these YAML templates?

      -

      Alex: There are five main types you can define in your YAML file. The first is called markdown. This is not an input field, it is just static text. You use this to display instructions or warnings at the top of the form. Your screen reader will just read it as normal text content.

      -

      Jamie: Okay, so that is how I give them background information before they start typing. What is the next type?

      -

      Alex: The second type is input. This is a single line text field. It is perfect for short answers like a version number, or a URL. Your screen reader will announce it as edit text. The third type is textarea. This is a multi line text box. You use this for long form answers, like steps to reproduce, or describing the expected behavior.

      -

      Jamie: So if I want them to write a paragraph, I use textarea. If I just want a quick string of text, I use input.

      -

      Alex: Exactly. Now, the fourth type is where things get really powerful. Dropdown. This creates a select menu with predefined options.

      -

      Jamie: Oh, this is huge. Because if you ask people what operating system they use in a blank text box, one person writes Windows 11, another writes Win 11, another writes W 11. It is impossible to filter or search later. With a dropdown, you force them to pick from your exact list.

      -

      Alex: Precisely. And dropdowns are highly accessible. Your screen reader will announce it as a combo box. You press Down Arrow or Alt plus Down Arrow to expand it, and you can arrow through the specific choices. The fifth and final type is checkboxes. This creates a group of checkboxes that the user can toggle with the Space bar. This is fantastic for creating a pre submission checklist, like asking them to confirm they have searched for existing issues before filing a new one.

      -

      Jamie: Okay that sounds like a lot of steps to build all these fields. Do I have to write all of this YAML by hand?

      -

      Alex: It does sound like a lot! But here is the thing, you have already interacted with these exact types of fields whenever you use the web. You are just defining them in a text file. Each field in your YAML file gets a type, an ID, a label, and optionally a description and placeholder text. But the real magic of YAML form templates is validation.

      -

      Jamie: Validation? You mean making fields required?

      -

      Alex: Yes. In a Markdown template, someone can just submit a blank issue. In a YAML form template, you can add a property called required and set it to true for any input, textarea, or dropdown. If a user tries to submit the issue without filling out that field, GitHub stops them and displays an error. And yes, those errors are properly announced to screen readers.

      -

      Jamie: That is a game changer for maintainers. You can absolutely guarantee that every single bug report includes the screen reader version, because they literally cannot click submit until they provide it.

      -

      Alex: So, let us put this together and talk about the specific templates you might want to create for your projects. Every repository should generally have at least two templates. A bug report, and a feature request.

      -

      Jamie: Let us start with the bug report. Especially an accessibility bug report, since that is what our listeners are most likely dealing with. What should go into that template?

      -

      Alex: If you are building an accessibility bug report as a YAML form, you want to use dropdowns for the bounded information. You want a dropdown for the operating system. A dropdown for the screen reader, with options like NVDA, JAWS, VoiceOver on Mac, VoiceOver on iOS, and TalkBack. You want a dropdown for the browser.

      -

      Jamie: And I am guessing we want those all set to required equals true.

      -

      Alex: Absolutely. Then, you want textareas for the narrative information. You need a textarea for Expected Behavior, a textarea for Actual Behavior, and a critical textarea for Steps to Reproduce.

      -

      Jamie: I always struggle with what to write in Steps to Reproduce. How can we help users fill that out correctly?

      -

      Alex: That is where the placeholder attribute comes in. In your YAML file, you can define placeholder text that appears inside the empty textarea. Do not just write, enter steps here. Write an actual example. Number 1, navigate to the settings page. Number 2, activate the save button. Number 3, observe that focus is lost. By modeling good behavior in the placeholder, you teach the contributor exactly what you expect.

      -

      Jamie: That is a great tip. Okay, what about a feature request template? How is that different from a bug report?

      -

      Alex: A feature request template is about understanding a problem, not a system failure. So instead of asking for operating systems and browser versions, you ask different questions. You might have a textarea labeled Problem or Gap, where they explain what they are trying to achieve but cannot. Then another textarea labeled Proposed Solution, where they describe how they want the new feature to work.

      -

      Jamie: And maybe a checkbox at the bottom asking them to confirm that this feature has not already been requested by someone else.

      -

      Alex: Exactly. And the beauty of this system is that you are not limited to just bugs and features. You can create custom templates for literally any purpose. If you run a documentation repository, you can create a template specifically for requesting new tutorials. If you run a design system, you can create a template for proposing a new color token. You just name the YAML file whatever you want, put it in the issue template folder, and it will appear on the chooser page.

      -

      Jamie: Okay, so I have written my YAML file, I have added my dropdowns and textareas, and I have saved it in the dot github slash issue underscore template folder. How do I actually test it to make sure it works and is accessible?

      -

      Alex: Testing your templates is a crucial final step. The best way to do this is to commit your new template file to a branch and push it to your repository. You do not even have to merge it to your main branch yet. Once it is pushed, you navigate to the Issues tab on your repository and activate the New Issue button.

      -

      Jamie: And because I pushed the template, the template chooser page should appear, right?

      -

      Alex: Yes. You should see your new template listed there. Activate the Get started button for your template. This is where you do your screen reader testing. Do not just look at the code, actually navigate the generated form.

      -

      Jamie: Right, I would use my Tab key to move through the form. I want to listen carefully. Does the screen reader read the label clearly? Does it announce whether the field is required? When I open a dropdown, does it read all the options correctly?

      -

      Alex: Exactly. And try to submit the form while leaving a required field blank. Verify that your screen reader announces the validation error and moves focus appropriately. If everything sounds good, and the form guides you smoothly from top to bottom, your template is ready for the world.

      -

      Jamie: This really reframes how I think about issues. It is not just about complaining that something is broken. It is a structured conversation. And as a maintainer, you get to design exactly how that conversation flows by building a good template.

      -

      Alex: That is a beautiful way to put it. You are designing the contribution experience. A well designed YAML form template is an act of hospitality. It tells the contributor, we value your time, we want your feedback, and here is exactly how you can help us understand it.

      -

      Alex: We have covered a lot of ground today. Let us recap with some concrete takeaways. First, issue templates turn a blank text box into a guided intake form, improving the quality of contributions and saving maintainers time.

      -

      Jamie: Second, templates live in a specific folder in your repository. You navigate to the dot github folder, and inside that, you create an issue underscore template folder. That is where all your template files and your config dot y m l file will live.

      -

      Alex: Third, while you can use Markdown files for simple templates, YAML form templates are vastly superior for accessibility and data quality. They generate real web forms with explicit labels, structured dropdowns, and required field validation.

      -

      Jamie: And fourth, always test your templates with your screen reader. Make sure your labels are clear, your placeholder text is helpful, and your required fields are actually catching empty submissions.

      -

      Alex: If you are following along with the curriculum, your hands on activity for this chapter is to create a comprehensive accessibility bug report template using YAML, and submit it as a pull request to your fork. It is fantastic practice for writing YAML syntax and understanding form validation.

      -

      Jamie: But wait, earlier I asked if I really have to write all this YAML by hand. And you kind of dodged the question by saying it is just defining fields. Is there an easier way?

      -

      Alex: I am so glad you remembered that. Writing YAML by hand is a great way to learn the structure, which is why we teach it here. But in our next episode, Episode 17, we are going to introduce you to Accessibility Agents. Specifically, we will look at the Template Builder agent, an AI tool that will ask you conversational questions about what you want in your template, and then automatically generate the flawless YAML code for you.

      -

      Jamie: Oh, I cannot wait for that. No more worrying about missing colons or incorrect indentation!

      -

      Alex: Exactly. But understanding the concepts we discussed today is what makes you able to direct that agent effectively. Until next time, keep exploring, keep testing your forms, and we will see you in the next episode.

      +

      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.

      +
      +

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

      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      - +

      Episode 17: Accessibility Agents

      -

      Six agents, 28 slash commands, custom agents, and agentic accessibility workflows.

      -

      Based on: Chapter 16: Accessibility Agents

      - - -

      Download Episode 17 (MP3)

      +

      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 to Gitt Going with GitHub, the audio series for blind and low-vision developers learning GitHub and open source. I am Alex, your lead host, and as always, I am joined by my co-host, Jamie.

      -

      Jamie: Hi everyone. I am Jamie. I am so ready for today. We are on Episode 17, which is called Accessibility Agents. And I have to admit, I peeked at the workshop materials for today and my mind is a little blown by what we are covering.

      -

      Alex: It is a big one. Today we are talking about specialized AI assistants that live right inside your editor and your repositories, designed specifically to help with accessibility tasks and GitHub workflows.

      -

      Jamie: Before we get too deep, we should probably remind everyone where we are coming from. If you are listening to this, you should have already completed the prerequisites we covered in a few earlier episodes. Specifically, Episode 11, where we talked about setting up VS Code extensions and settings, and Episode 14, where we covered GitHub Copilot Chat and how to interact with it.

      -

      Alex: Exactly. You need to know how to open Copilot Chat, which you can do by pressing Control plus Shift plus I on Windows, or Command plus Shift plus I on a Mac. If you are comfortable with that, you are ready for today.

      -

      Alex: Let us start with the big question. What exactly are accessibility agents?

      -

      Jamie: I know we have been using GitHub Copilot to help us write code and understand errors. Are agents just a different name for Copilot?

      -

      Alex: That is a great question. Think of GitHub Copilot as a general practitioner doctor. You can go to them with almost any problem, and they have a broad, baseline understanding of everything. They can help you with a lot of general coding tasks.

      -

      Jamie: Right, like asking it to explain a block of JavaScript or write a regular expression.

      -

      Alex: Exactly. But an accessibility agent is like a specialist. It is a cardiologist or a physical therapist. It is a custom AI assistant that extends GitHub Copilot with deep, specialized domain expertise. These agents know specific accessibility standards, they know how to audit document structures, and they know the exact workflows for managing GitHub repositories.

      -

      Jamie: Oh, I love that analogy. So instead of just asking general Copilot to check my code, I am bringing in an expert who only cares about keyboard navigation, or only cares about color contrast.

      -

      Alex: You nailed it. And this ecosystem is massive. There are currently fifty five different agents, organized into three distinct teams, and they run across five different platforms.

      -

      Jamie: Wait, fifty five? Okay, that sounds like a lot of steps. I am feeling a little intimidated just hearing that number. Am I supposed to memorize fifty five different AI assistants?

      -

      Alex: Not at all. And it is completely normal to feel overwhelmed by that number. But here is the thing, you have already done most of this on Day 1 of the workshop. Every single agent automates a sequence of steps you already know how to do manually. You do not need to use all fifty five. You just pick the ones that match the tasks you do every day.

      -

      Jamie: Okay, that makes me feel better. So what is the catch?

      -

      Alex: The catch is what we call the skill first principle. The agents are only useful if you have already done the work manually. An agent that summarizes pull requests is useless to someone who has never read a pull request. An agent that audits a web page for accessibility is useless if you do not understand the Web Content Accessibility Guidelines.

      -

      Jamie: That makes total sense. It is like power steering in a car. Power steering makes it much easier to turn the wheel, but it does not teach you how to drive. You still need to know the rules of the road and how to navigate. The agent does not teach you the skill, it multiplies a skill you already have.

      -

      Alex: That is a perfect comparison. So before you run any agent, ask yourself, could I do this task manually right now? If the answer is no, learn the manual skill first. The agents are designed to amplify your abilities, not replace your understanding.

      -

      Alex: Let us break down this ecosystem. I mentioned there are fifty five agents across three teams. Let us look at Team 1. This is the Accessibility team, and it is the largest, with twenty six agents.

      -

      Jamie: What kinds of specialists are on this team?

      -

      Alex: These agents audit, fix, and enforce accessibility across web, document, and mobile platforms. For example, there is an ARIA specialist for checking roles and states. There is a modal specialist that checks dialog focus trapping. There is a contrast master, a keyboard navigator, and agents specifically for auditing Microsoft Word, Excel, PowerPoint, and PDF documents.

      -

      Jamie: Wow. So if I am working on a complex data table, I can literally just call in the tables specialist agent to check my markup?

      -

      Alex: Exactly. Team 2 is the GitHub Workflow team, which has twelve agents. These automate GitHub operations. Things like issue triage, pull request reviews, contribution analytics, and repository management.

      -

      Jamie: Oh, I remember doing all of that manually in Episode 4 and 5. Navigating issues and reviewing pull requests takes a lot of time.

      -

      Alex: It does, and that is where these agents shine. Team 3 is the Developer Tools team, with six agents. These support accessible application development across desktop and cross platform frameworks. There is a Python specialist, a desktop accessibility specialist, and tools to help you build your own custom accessibility linters.

      -

      Jamie: You also mentioned they run on five platforms. Does that mean I have to leave VS Code to use them?

      -

      Alex: No, you can do everything right inside VS Code using GitHub Copilot. But the exact same fifty five agents are also available on Claude Code, Gemini Command Line Interface, Claude Desktop, and the Codex Command Line Interface. They are portable.

      -

      Jamie: So how do these teams actually work together? If I have a complex problem, do I have to talk to the keyboard navigator, and then separately talk to the contrast master?

      -

      Alex: You can, but you do not have to. This brings us to orchestrator agents. An orchestrator agent is like a general manager or a wedding planner. You give them the big picture goal, and they go hire the right specialists for the job.

      -

      Jamie: That sounds incredibly helpful. What are the names of these orchestrators?

      -

      Alex: There are a few key ones. In the GitHub Workflow team, there is an agent called at nexus. You literally type the at symbol, followed by the word nexus. At nexus handles cross agent orchestration for complex, multi step workflows. In the Accessibility team, there is at accessibility dash lead, which delegates audits to the various specialists. And there is at web dash accessibility dash wizard, which runs a full guided audit, invoking the contrast, keyboard, and forms specialists automatically.

      -

      Jamie: So if I am reviewing a pull request, how does that multi agent workflow happen in practice?

      -

      Alex: Let us walk through a real world example. Say you start your morning by asking the daily briefing agent what needs your attention. It flags a new pull request. Then, you ask the PR review agent to generate a structured review of that pull request. The review agent notices some changes to ARIA attributes, so it suggests you talk to the ARIA specialist. You invoke the ARIA specialist, it finds a missing expanded state on a button, and then you fix it. The teams connect naturally. The workflow agent tells you what happened, the accessibility agent evaluates if it is correct, and the developer tools agent helps you implement the fix.

      -

      Jamie: Okay, I am sold. How do I actually talk to these agents? You mentioned typing the at symbol.

      -

      Alex: Yes. To invoke an agent in Copilot Chat, you simply type the at symbol, and a list of available agents will pop up. You can use your arrow keys to navigate the list and press Enter to select one, or just type its name. For example, at daily dash briefing, followed by your request, like, morning briefing.

      -

      Jamie: That is easy enough. But what if I just want to run a quick command without having a whole conversation with an agent persona?

      -

      Alex: That is where slash commands come in. The ecosystem includes more than fifty four slash commands organized by workflow. You invoke them by typing a forward slash in the chat input.

      -

      Jamie: Oh, like how we use forward slash explain to ask Copilot to explain code.

      -

      Alex: Exactly. But these are custom slash commands built for our workflows. Let me give you some high impact starting points. These are the slash commands that save the most time.

      -

      Jamie: I have my notebook ready.

      -

      Alex: First is forward slash my dash issues. This gives you an instant dashboard of your open work across all repositories, complete with priority signals.

      -

      Jamie: That beats manually checking the notifications page and filtering by assigned issues.

      -

      Alex: It really does. Next is forward slash review dash p r, followed by the pull request number. So, forward slash review dash p r space pound fourteen. This generates a full AI generated review with inline suggestions, evaluating the risk level and summarizing the changes.

      -

      Jamie: Wait, does it actually post the review to GitHub automatically?

      -

      Alex: No, and this is a critical limitation we need to discuss. Agents suggest, humans decide and verify. The agent generates a draft review document in your chat window. It is your job to read it, edit it, make sure the tone is right, and verify that it did not miss any important context. Then, you post it under your own name.

      -

      Jamie: That goes back to the skill first principle. If I do not know how to review a pull request manually, I will not know if the agent gave me a good review or a terrible one.

      -

      Alex: Exactly right. A few other massive time savers to try first. Forward slash triage, followed by an issue number. This will suggest labels, priorities, and assignments for a new issue. Forward slash daily dash briefing gives you a morning snapshot of repository activity. And forward slash a eleven y dash update gives you the latest accessibility improvements across your repositories, complete with cross references to the Web Content Accessibility Guidelines.

      -

      Jamie: So how do I actually get all of these agents and slash commands onto my computer? Is it a complex installation?

      -

      Alex: It is surprisingly simple. There are two ways. For this workshop, the easiest way is to just fork the accessibility agents repository on GitHub, and then clone your fork to your local machine. When you open that folder in VS Code, Copilot automatically discovers the agents.

      -

      Jamie: Wait, that is it? No API keys or complex settings?

      -

      Alex: That is it. The agents live inside a folder called dot github, slash agents. Because they are just files in the repository, they travel with the code. If you clone a repository that has these files, you instantly have the agents.

      -

      Jamie: What if I want to use these agents on my own personal projects, not just the workshop repository?

      -

      Alex: Then you can use the quick install script. It is a single line you paste into your terminal. It detects what platforms you have installed and configures all fifty five agents globally on your machine. The exact commands are in the chapter text.

      -

      Jamie: I noticed you mentioned these agents are just files. How does a file tell the AI how to act like a specialist?

      -

      Alex: That is the magic of agent instruction files. Every agent is defined by a simple text file ending in dot agent dot m d. It is just a markdown file.

      -

      Jamie: So I can open these files and read them?

      -

      Alex: Absolutely, and you should. If you open the dot github slash agents folder, you will see files like issue dash tracker dot agent dot m d. If you read it, you will see it has two parts. At the top is some metadata, like the agent's name, a description of what it does, and what tools it is allowed to use.

      -

      Jamie: What do you mean by tools?

      -

      Alex: Tools give the agent permission to take actions. For example, an informational agent only needs permission to read files and search GitHub. But a task oriented agent might need permission to edit files, run shell commands, or create a pull request. Restricting tool access is a security best practice.

      -

      Jamie: That makes sense. What is the second part of the file?

      -

      Alex: The second part is the system prompt. It is plain English instructions. It is basically like writing a highly specific company employee handbook or a job description. You tell the agent its purpose, its domain knowledge, the step by step behavioral rules it must follow, and exactly how to format its output.

      -

      Jamie: If they are just markdown files, does that mean I can build my own custom agent?

      -

      Alex: You absolutely can, and that is one of the core exercises in the workshop. Building your own custom agent with agent dot m d files is how you tailor the AI to your exact workflow.

      -

      Jamie: How would I start doing that? Let us say I want an agent that specifically checks markdown files for accessibility errors, like making sure my heading levels do not skip from heading level one to heading level three.

      -

      Alex: You would create a new file in the dot github slash agents folder. Let us call it markdown dash assistant dot agent dot m d. At the top, you give it a name and tell it to use tools that let it read and edit files. Then, in plain English, you write its rules. You literally type, never skip heading levels. You tell it to verify that all images have alt text. You tell it to fix bare URLs.

      -

      Jamie: And once I save that file and reload the VS Code window, I can just type at markdown dash assistant in the chat?

      -

      Alex: Yes. And there are already real world examples of agent assisted contributions just like this. The GitHub Accessibility team actually published a complete walkthrough for building exactly the Markdown Accessibility Assistant you just described. It is a task oriented agent that not only reviews the file, but makes direct fixes.

      -

      Jamie: Oh, I love the idea of it making the fixes for me. But wait, what about things that require human judgment, like writing good alt text? I do not want the AI guessing what an image represents.

      -

      Alex: That is brilliant, Jamie, and it highlights a key pattern for custom agents called tiered decision making. When you write the agent's instructions, you tell it to fix objective issues automatically. Things like heading hierarchy or list structure. But for subjective issues, like alt text or plain language, you instruct the agent to flag the issue, suggest a fix, and wait for human approval before changing anything.

      -

      Jamie: That keeps the human in the loop for the important stuff, but automates the boring mechanical fixes.

      -

      Alex: Exactly. Let me give you another real world example from the workshop materials. There is an agent called at template dash builder. Creating GitHub issue templates manually requires writing YAML syntax, which is error prone and tedious. The template builder agent turns this into an interactive wizard.

      -

      Jamie: How does it do that?

      -

      Alex: You invoke it by typing at template dash builder, create accessibility template. Instead of just dumping code, the agent uses VS Code to ask you questions one by one. It asks, what is this template called? You type your answer. It asks, what field do you want to add? You type, screen reader dropdown. It asks what the options should be.

      -

      Jamie: So it interviews me, and then writes the YAML file perfectly based on my answers?

      -

      Alex: Yes. And if you want to change it later, you just tell the agent, add a checkbox for version compatibility, and it modifies the file for you. It takes a fifteen minute manual task and turns it into a two minute conversation.

      -

      Jamie: Everything we have talked about so far happens inside VS Code on my local machine. But what if I want an agent to do something automatically when I am not at my computer? Like, when someone opens an issue in my repository at three in the morning.

      -

      Alex: That brings us to agentic workflows. This is the bridge between the local agents we use in VS Code and cloud based automation. You can chain multiple agents together and run them on GitHub Actions infrastructure.

      -

      Jamie: So it works like an assembly line, where each station handles a specific task automatically?

      -

      Alex: Exactly. You can write a workflow file that says, whenever a new issue is opened with the word accessibility in the title, assign it to the accessibility team, add a needs triage label, and post a comment asking the user what screen reader they are using. The workflow runs serverlessly. No local machine required.

      -

      Jamie: That is incredibly powerful. But it all comes back to defining the intent in plain language, just like the local agents.

      -

      Alex: Yes. Understanding how to write local agent instructions in VS Code is the exact conceptual precursor to writing GitHub Agentic Workflows. Once you understand one, the other is immediately readable.

      -

      Jamie: We have covered so much ground today. The fifty five agents, the three teams, slash commands, building custom agents, and agentic workflows.

      -

      Alex: It is a massive topic. If you want to go deeper, and I highly recommend you do, check out Appendix V in the workshop materials. It is the complete reference for all fifty five agents, all fifty four plus slash commands, and all the customization formats.

      -

      Jamie: And there is an audio version for that too, right?

      -

      Alex: Yes, Episode 39 walks through the entire Appendix V reference step by step. It is a fantastic resource when you are ready to start building your own advanced workflows.

      -

      Jamie: So, Alex, what are the concrete takeaways for our listeners today?

      -

      Alex: I have three main takeaways. First, embrace the skill first principle. Agents do not teach you how to use GitHub; they multiply the skills you already have. Always do the task manually at least once before asking an agent to do it.

      -

      Jamie: Second, do not try to learn all fifty five agents at once. Start with high impact slash commands like forward slash my dash issues, or forward slash review dash p r. Let them save you time on tasks you already do every day.

      -

      Alex: And third, remember that agents suggest, but humans decide. Whether you are using a pre built agent or building your own custom agent dot m d file, you are responsible for the final output. Use tiered decision making to automate the objective tasks and keep yourself in the loop for the subjective ones.

      -

      Jamie: This has been such an eye opening episode. I am going to go play with the template builder agent right now. What are we covering in the next episode?

      -

      Alex: Next time, we are diving into Episode 18, which is all about GitHub Actions. We have touched on it briefly today with agentic workflows, but in the next episode, we are going to break down exactly how to automate your testing, your deployments, and your repository maintenance using continuous integration.

      -

      Jamie: I cannot wait. Thank you all for listening to Gitt Going with GitHub. We will see you in the next episode.

      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      - +

      Appendices

      Episode 18: Glossary of Terms

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

      Based on: Appendix A: Glossary of Terms

      - - -

      Download Episode 18 (MP3)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 18: Glossary of Terms

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is episode eighteen, Glossary of Terms. I am Alex, and today we are doing something a little different. Instead of a step by step tutorial, we are taking a step back to build our vocabulary. If you are attending our two day workshop, this episode is your foundational reference guide.

      -

      Jamie: And I am Jamie. I am so glad we are doing this because when I started learning GitHub about two years ago, the jargon was honestly the biggest barrier. People would say things like, just fork the repo, clone it local, branch off upstream, and push a pull request. And my brain would just shut down. It sounded like a completely different language.

      -

      Alex: It really is a different language. And that is exactly why we want to normalize this right now. If you are feeling intimidated by the terminology, that is completely normal. You have already done most of the underlying workflows in your day to day life without realizing it. Today, we are just giving you the official names for those concepts so you can communicate effectively with other developers and open source maintainers.

      -

      Jamie: That is a relief. So, what is the plan for today?

      -

      Alex: We are going to break our glossary down into five main categories. First, we will cover the core version control terms, the absolute basics of Git. Second, we will move into GitHub specific collaboration terms. Third, we will untangle the web of remotes, things like upstream and origin. Fourth, we will define the accessibility terms we use throughout this workshop when we describe navigating the interface. And finally, we will cover terms related to artificial intelligence agents and GitHub Copilot.

      -

      Jamie: And just a quick reminder for our listeners, the prerequisite for this episode is simply a basic understanding of web navigation with your screen reader. We covered how GitHub structures its web pages in episode one, so if you need a refresher on that, feel free to navigate back to that episode.

      -

      Alex: Perfect. Let us dive right into category one, version control terms. And we have to start with the container that holds everything, the repository. You will almost always hear this shortened to repo. A repository is the main folder for an entire project. It holds all the files, all the documentation, and most importantly, the complete history of every change ever made to those files.

      -

      Jamie: I always like to think of a repository as a project folder that has a time machine built into it. If you have ever worked on a document and saved it as final version, then final final version, then absolute final version use this one, you were trying to do what a repository does automatically. It remembers every past state of your project.

      -

      Alex: That is a brilliant analogy. And the way it remembers those past states is through our next term, a commit. A commit is a saved snapshot of your changes at a specific moment in time. But it is not just hitting control plus S on your keyboard. When you make a commit, you are required to attach a message explaining what you changed and why you changed it.

      -

      Jamie: Right, it is like hitting save, but you have to attach a sticky note to the file explaining your thought process. I remember learning that a good commit message should complete the sentence, if applied, this commit will... so, if applied, this commit will fix the broken login button.

      -

      Alex: Exactly. Now, as your repository grows, you might want to experiment with a new feature without breaking the working version of your project. That is where a branch comes in. A branch is a separate, parallel line of development inside your repository. The default, stable version of your project lives on a branch usually called main. When you want to build something new, you create a new branch.

      -

      Jamie: This is my favorite concept. A branch is literally a parallel universe or an alternate timeline. You branch off from the main timeline, you make your changes in your own little universe, and the main timeline is completely unaffected. You can switch back and forth between these universes whenever you want.

      -

      Alex: And when you are happy with the work in your parallel universe, you need a way to bring those changes back into the main timeline. That process is called a merge. To merge is to combine the changes from one branch into another.

      -

      Jamie: But what happens if two people changed the exact same thing in their own parallel universes, and then they both try to merge back into the main timeline?

      -

      Alex: That brings us to a term that strikes fear into the hearts of many beginners, the merge conflict. A merge conflict happens when Git cannot automatically figure out which changes to keep. For example, if you changed the background of the website to blue, and I changed it to red on the exact same line of code, Git throws its hands up and says, I need a human to decide this.

      -

      Jamie: I used to panic when my screen reader announced a merge conflict. It sounds so aggressive. But it is really just Git pausing the process to ask for your help.

      -

      Alex: Exactly. And the way Git asks for help is by inserting special text markers into your file. When you are reading the file with your screen reader, you will hear a line of less than signs, followed by the word HEAD, which represents your current branch. Then you will read your changes. Then you will hear a line of equals signs, which divides your changes from the incoming changes. Then you read the other person's changes. And finally, a line of greater than signs. To fix it, you just delete the markers, keep the text you want, and save the file.

      -

      Jamie: That takes so much of the mystery out of it. Okay, so we have our repository, we make commits on branches, and we merge them together. But how do we get our code onto the internet or onto our computer?

      -

      Alex: That is where push and pull come into play. These are action verbs. When you push, you are uploading your local commits from your computer up to a remote server, like GitHub. When you pull, you are downloading new commits from GitHub down to your computer and merging them into your current branch.

      -

      Jamie: So push is upload, pull is download. But specifically for commits, not just loose files.

      -

      Alex: Spot on. Now, to do any pushing or pulling, you need the repository on your computer in the first place. This introduces two terms that confuse almost everyone at first, clone and fork.

      -

      Jamie: Oh, absolutely. I thought these were interchangeable for the longest time.

      -

      Alex: They are related, but very different. Let us start with fork. A fork is a personal copy of someone else's repository that lives on your own GitHub account. You do this when you want to contribute to a project where you do not have permission to make changes directly. You fork their project, which gives you a playground copy on your own GitHub account where you have full control.

      -

      Jamie: So a fork happens entirely in the cloud, on GitHub's servers. My analogy for this is walking into a library, finding a reference book you are not allowed to write in, and making a photocopy of it to put in your own personal locker. You can draw all over your photocopy.

      -

      Alex: I love that. Now, clone is the next step. Cloning is the act of copying a repository from the internet down to your local computer's hard drive so you can work on it in an editor like Visual Studio Code.

      -

      Jamie: Keeping with the library analogy, cloning is taking that photocopied book out of your locker and bringing it home to your kitchen table so you can actually work on it.

      -

      Alex: That is exactly right. You fork a repository to get your own copy on GitHub, and then you clone your fork to get it onto your laptop.

      -

      Alex: Let us transition into our second category, GitHub specific collaboration terms. Once you have made your changes and you are ready to share them, you will interact with the GitHub website. The absolute core of GitHub collaboration is the pull request, often abbreviated as PR.

      -

      Jamie: So a pull request, and I love this name because it tells you exactly what it is, is you literally requesting that the maintainers of a project pull your changes into their repository. You are saying, hey, I fixed that bug on my branch, please pull my branch into your main branch.

      -

      Alex: Precisely. When you open a pull request, GitHub provides a beautiful interface for discussing the proposed changes. Which leads us to a helpful feature, the draft pull request. Sometimes you want to show people what you are working on before it is actually finished. When you open a draft PR, it clearly signals to everyone that this is a work in progress. It prevents maintainers from accidentally merging it before you are ready.

      -

      Jamie: Draft PRs take so much pressure off. I use them all the time just to get early feedback on my approach. And speaking of feedback, that brings up the term review.

      -

      Alex: Yes, a code review is the process where other developers read through the changes in your pull request. They can leave comments on specific lines of code, they can approve the changes, or they can request modifications. It is a peer review system to ensure quality.

      -

      Jamie: And it is not just humans doing the reviewing, right? When I open a pull request, my screen reader always starts announcing things like, some checks haven't completed yet. What is a status check?

      -

      Alex: A status check is an automated test that runs against your pull request. Think of it like an automated bouncer at a club. Before your code is allowed to merge, the repository might have a robot automatically check if your code compiles, if it follows formatting rules, or if it passes accessibility scans. If the status check fails, you get a red X, and you usually cannot merge until you fix the issue.

      -

      Jamie: That is actually really reassuring. The robots catch my typos before the human reviewers even have to see them. Now, before you even write code or open a pull request, you usually start with an issue, right?

      -

      Alex: Correct. An issue is a tracking item in a GitHub repository. Despite the name, an issue does not just mean a problem or a bug. Issues are used to request new features, ask questions, or discuss ideas. Think of the issues tab as a combination of a to do list and a discussion forum for the project. Every issue gets a unique number, like issue number forty two, which makes it very easy to reference later.

      -

      Alex: Now we are moving into category three. This is where we untangle collaboration network terms. We are talking about local, remote, origin, upstream, and downstream. Jamie, I know this was a sticking point for you early on.

      -

      Jamie: Oh, it was a nightmare. I would read documentation saying to fetch from upstream and push to origin, and I had no idea where my code was actually going.

      -

      Alex: Let us break it down simply. Local refers to the files sitting physically on your computer's hard drive. When you are working offline in Visual Studio Code, you are working local. Remote refers to any version of the repository that is hosted on the internet, like on GitHub.

      -

      Jamie: Okay, so local is my laptop, remote is the cloud. That is easy enough. But what are origin and upstream? Because those are both remotes, right?

      -

      Alex: Yes, they are both specific names for remote repositories. Let us use the open source contribution workflow to explain them. Imagine you want to contribute to the official Python programming language repository. You do not have permission to change their code, so you fork it. Now you have a copy on your personal GitHub account. Then you clone your personal copy down to your local computer.

      -

      Jamie: Right, so I have my local copy on my laptop, and my personal fork on GitHub.

      -

      Alex: Exactly. From the perspective of your local computer, your personal fork on GitHub is called origin. Origin is the default name Git gives to the place you cloned from. It is your home base in the cloud. When you type git push, it sends your code to origin.

      -

      Jamie: Okay, so origin is my personal fork. Then what is upstream?

      -

      Alex: Upstream refers to the original repository that you forked from, in this case, the official Python repository. It is called upstream because changes flow down from it to you. If the maintainers of Python update their code, you need to pull those changes down to keep your fork up to date. You are pulling from the upstream source.

      -

      Jamie: That analogy actually makes perfect sense. Upstream is the original source of the river. Origin is my personal reservoir that I built by piping water from the river. And local is the glass of water sitting on my desk.

      -

      Alex: That is a fantastic way to visualize it. And just to complete the metaphor, downstream refers to anyone who forks your repository. To them, you are the upstream. It is all relative to where you are standing.

      -

      Alex: Let us shift gears to category four. Throughout this audio series and the two day workshop, we use specific accessibility terms to describe how to navigate GitHub and Visual Studio Code. We want to define those clearly so everyone is on the same page.

      -

      Jamie: Yes, and the most fundamental term we use is screen reader. A screen reader is assistive technology that converts digital text and interface elements into synthesized speech or Braille. Common ones are NVDA or JAWS on Windows, and VoiceOver on Mac. When we say, listen to what your screen reader announces, we are referring to the feedback from this software.

      -

      Alex: Next is a term crucial for efficient navigation, the landmark. A landmark is an invisible, structural tag applied to sections of a web page. Common landmarks include the banner, the main content area, navigation regions, and the footer.

      -

      Jamie: Landmarks are like teleportation pads. Instead of hitting the tab key a hundred times to get past the top menu, I can use my screen reader's shortcut, usually the letter D or the region navigation key, to jump instantly to the main landmark where the actual content begins.

      -

      Alex: Exactly. Similar to landmarks are headings. A heading is a structural element that acts like the outline of a document. They range from heading level one, which is usually the page title, down to heading level six for deeply nested subsections. When we tell you to navigate to the heading called Pull Requests, we are instructing you to use your screen reader's heading shortcut, usually the letter H, to jump directly to that section.

      -

      Jamie: And then there is a term that sounds like a musical concept, but it is actually highly technical. ARIA. Could you explain what ARIA is, and also clarify how to pronounce it? I have heard people say it a few different ways.

      -

      Alex: I pronounce it are-ee-uh. It stands for Accessible Rich Internet Applications. ARIA is a set of attributes that developers add to code to communicate complex interface behaviors to screen readers. For example, if a menu is collapsed, an ARIA attribute tells the screen reader to announce collapsed. When you press enter, the attribute changes, and the screen reader announces expanded. You do not need to know how to write ARIA to take this workshop, but you will hear us mention it when we explain why GitHub announces certain things.

      -

      Jamie: That makes sense. Two more accessibility terms we use constantly are focus and tab order. Focus refers to the specific element on the screen that is currently active and ready to receive keyboard input. If you type a letter, it goes into the element that has focus.

      -

      Alex: And tab order is the sequential path that your focus takes when you press the Tab key to move forward, or Shift plus Tab to move backward. A well designed page has a logical tab order that follows the visual reading order. When we say, move your focus to the commit button, we generally mean to tab through the interface until that button is the active element.

      -

      Alex: Finally, we arrive at category five. This workshop incorporates modern development tools, specifically artificial intelligence agents. The primary tool we use is GitHub Copilot.

      -

      Jamie: GitHub Copilot is incredible. It is an AI powered coding assistant built directly into Visual Studio Code and GitHub.com. But it does not just write code, right? We use it to explain error messages, write documentation, and even help us resolve those merge conflicts we talked about earlier.

      -

      Alex: That is right. And Copilot operates using what we call an agent. An agent is a specialized AI helper designed for a specific context. For example, in Visual Studio Code, there is a workspace agent that knows about all the files in your local repository. There is also a terminal agent that specializes in command line errors.

      -

      Jamie: And how do we talk to these agents? I know we use something called a slash command.

      -

      Alex: Yes, a slash command is a shortcut to give the agent a specific task. In the Copilot chat window, you literally type the forward slash character followed by a word. If you type slash explain, the agent knows you want an explanation of the code that currently has focus. If you type slash fix, it will analyze an error and propose a solution.

      -

      Jamie: After you use a slash command, you usually provide a prompt. A prompt is simply the human language instruction or question you are asking the AI. So you might type, slash explain, and then your prompt could be, what does this regular expression do?

      -

      Alex: Exactly. And the last term in this category is the instruction file. An instruction file is a plain text file you can add to your repository to give Copilot custom rules for your specific project. You can tell it things like, always write explanations at a beginner level, or, never use certain outdated functions. It is a way to tailor the AI's behavior so it aligns with your project's standards.

      -

      Alex: We have covered a massive amount of ground today. Let us quickly recap with some concrete takeaways. First, remember the fundamental Git workflow. You make a commit to save a snapshot of your work, you do this on a separate branch to isolate your changes, and then you merge it when you are done.

      -

      Jamie: Second, keep your remotes straight. Origin is your personal fork on GitHub. Upstream is the original project you want to contribute to. And local is the computer sitting in front of you.

      -

      Alex: Third, utilize pull requests and issues. Issues are where discussions and bug reports happen. Pull requests are where you actually propose the code changes to solve those issues. And do not be afraid to use a draft pull request to get early feedback.

      -

      Jamie: And finally, lean on the accessibility structures. Use landmarks and headings to jump around GitHub's interface quickly, rather than tabbing through every single link.

      -

      Alex: Well said, Jamie. Having this shared vocabulary is going to make the rest of the workshop so much smoother. In our next episode, we are going to dive into the magic of automation with GitHub Actions and Workflows. We will learn how to make the repository do the heavy lifting for us.

      -

      Jamie: I cannot wait for that one. Thank you all for listening, and we will see you next time on Gitt Going with GitHub.

      +

      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.

      - +

      Episode 19: Screen Reader Cheat Sheet

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

      Based on: Appendix B: Screen Reader Cheat Sheet

      - - -

      Download Episode 19 (MP3)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 19: Screen Reader Cheat Sheet

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub, the audio learning series for blind and low-vision developers who are mastering GitHub and open source collaboration. This is episode nineteen, titled Screen Reader Cheat Sheet. I am your host, Alex, and as always, I am joined by my fantastic co-host, Jamie.

      -

      Jamie: Hello everyone! I am so excited for this episode. If you are following along in the two-day workshop, we are looking at Appendix B today. And I have to admit, when I first started learning GitHub about two years ago, I felt like I was drowning in keyboard shortcuts. There are screen reader shortcuts, browser shortcuts, and GitHub shortcuts. It felt like trying to learn to play a piano with three different sets of sheet music at the same time.

      -

      Alex: That is a perfect analogy, Jamie. It can feel completely overwhelming at first. But the secret is that you do not need to memorize every single command to be successful. You just need to understand the underlying patterns. Once you understand how the piano is tuned, to borrow your analogy, you can play almost any song. Today, we are going to break down the essential keyboard commands for NVDA, JAWS, and VoiceOver, plus GitHub's built-in shortcuts, and even some critical commands for Visual Studio Code.

      -

      Jamie: And if you are listening to this and thinking, okay, that sounds like a lot of steps, please know that it is completely normal to feel that way. You have actually already done most of this on Day One of the workshop. We are just giving you the official names and the fastest routes for the workflows you already know.

      -

      Alex: Exactly. Before we dive into the specific keys, we have to talk about the most fundamental concept for screen reader users on the web. We need to talk about the two different modes that your screen reader uses. If you do not understand these two modes, GitHub will feel completely broken to you. These are Browse Mode and Focus Mode.

      -

      Jamie: Oh, this is the big one. I remember the exact moment this finally clicked for me. I was trying to leave a comment on an issue, and I kept pressing the letter H to type the word Hello, and instead of typing, my screen reader just kept jumping wildly around the page to different headings. I was so frustrated.

      -

      Alex: We have all been there! Let us define what is happening. Browse Mode, which JAWS calls the Virtual Cursor, is your primary mode for reading and navigating web pages. When you are in Browse Mode, your screen reader intercepts every key you press and uses it as a navigation command. So pressing the letter H tells the screen reader to jump to the next heading, rather than sending the letter H to the website.

      -

      Jamie: Right. And I like to think of Browse Mode like walking through a museum. You are moving from exhibit to exhibit, reading the plaques, taking in the structure of the room. You are observing, but you are not touching or changing anything.

      -

      Alex: I love that museum analogy. But eventually, you need to interact. You need to type a comment, or rename a file, or fill out a search box. That is where Focus Mode comes in. Focus Mode, which is sometimes called Forms Mode, tells your screen reader to stop intercepting your keys. It passes your keystrokes directly through to the web page.

      -

      Jamie: So sticking with the museum, Focus Mode is like stepping up to the guestbook at the end of the tour and picking up a pen. Now you are writing. You are interacting directly with the canvas.

      -

      Alex: Exactly. Let us talk about how to switch between these modes, starting with NVDA, which is the primary screen reader we use in this workshop. To toggle between Browse Mode and Focus Mode in NVDA, you press NVDA plus Space. You will hear a distinct sound. A higher pitched click means you entered Focus Mode, and a lower pitched clack means you went back to Browse Mode.

      -

      Jamie: And for JAWS users, the concept is the same, but the keystroke is Insert plus Z to toggle the Virtual PC Cursor on and off. Though JAWS is generally pretty good at switching into forms mode automatically when you navigate to an edit field, it is still crucial to know how to force it manually with Insert plus Z when things get stuck.

      -

      Alex: Now, VoiceOver on macOS handles this a bit differently. VoiceOver does not have a global Browse or Focus mode in the same way. Instead, you interact with specific elements. To type in a text box, you navigate to it and press VoiceOver keys, which are Control plus Option, plus Shift plus Down Arrow. This tells VoiceOver you are stepping inside that element to interact with it. When you are done typing, you press VoiceOver keys plus Shift plus Up Arrow to stop interacting and step back out.

      -

      Jamie: VoiceOver interacting always reminds me of opening a Russian nesting doll. You step down into the container to play with the pieces inside, and then you step back up and close the doll when you are finished.

      -

      Alex: So now that we understand our modes, let us talk about how we actually move around GitHub in Browse Mode. We will start with single-key navigation for NVDA and JAWS. VoiceOver users can also use these if they have Quick Nav turned on. The absolute most important key you will use on GitHub is the letter H, for Headings.

      -

      Jamie: Headings are the skeleton of any GitHub page. Pressing H jumps you forward to the next heading, and Shift plus H moves you backwards. But you can also be more specific by pressing the numbers one through six.

      -

      Alex: Yes, and GitHub is very consistent about how they use these heading levels. If you press the number one, you will jump to the main title of the page. On a repository page, the level one heading is the name of the repository itself. Pressing the number two will jump you to major sections, like the repository file tree or the README file.

      -

      Jamie: And the number three is my favorite shortcut on GitHub. Issue titles and Pull Request titles are always level three headings. So if you are on a page with a list of fifty open issues, you do not have to read through all the dates and labels and author names. You just rapidly press the number three to jump from one issue title to the next. It is incredibly fast.

      -

      Alex: It is a massive time saver. The next crucial navigation key is the letter D for NVDA users, or the letter R for JAWS users. This jumps you between Landmarks. Landmarks are named regions of the page, like the main content area, the navigation menu, or the sidebar.

      -

      Jamie: Landmarks are fantastic when you first land on a page and want to skip over the hundreds of navigation links at the top. You just press D until you hear Main Landmark, and you are right where the actual content begins.

      -

      Alex: Exactly. Next we have the letter K for Links, and the letter B for Buttons. You will use B constantly to find things like the Clone or Download button, or the Submit Comment button. And to find form fields, like the search bar or a comment box, you use the letter F, or the letter E in NVDA.

      -

      Jamie: We also have to talk about tables. GitHub uses tables to display the list of files in a repository. When you land on a repository page, pressing the letter T will jump you straight to that file table.

      -

      Alex: And once you are inside the table, you do not want to just use your standard up and down arrows, because that will read every single piece of information out of order. Instead, you hold down Control plus Alt, and then use your arrow keys. Control plus Alt plus Down Arrow moves you down the rows, so you can read the list of file names. Control plus Alt plus Right Arrow moves you across the columns, so you can read when that file was last updated or the commit message associated with it.

      -

      Jamie: Okay, Alex, those are a lot of single keys to remember. What if I am on a complex Pull Request page, and I cannot remember if the thing I want is a button, or a link, or a heading? I just know the name of it.

      -

      Alex: That brings us to your navigation superpower. The Elements List. If you only remember one thing from this entire episode, remember the Elements List. In NVDA, you open it by pressing NVDA plus F7. In JAWS, you can press Insert plus F6 for a headings list, or Insert plus F7 for a links list.

      -

      Jamie: The Elements List is like walking into a massive shopping mall and looking at the electronic directory board. Instead of wandering around hoping you bump into the store you want, you just pull up the master list.

      -

      Alex: Exactly right. When you press NVDA plus F7, a dialog box opens. It gathers every single link, heading, button, and landmark on the entire page and puts them into clean, alphabetical lists. You can use your Tab key to switch between the types of elements. But the best part is that you can type to filter. If you want to create a new issue, you just open the Elements List, make sure you are on the links or buttons tab, and type the word new. It instantly filters the list down to the New Issue button. You press Enter, and the screen reader activates that button for you.

      -

      Jamie: It feels like magic. And for our Mac users, VoiceOver has the exact same concept, called the Rotor. You open it by pressing VoiceOver keys plus the letter U. Then you use your left and right arrows to switch between lists of headings, links, form controls, and landmarks. You can type to filter the Rotor exactly the same way.

      -

      Alex: Let us transition to something unique to GitHub. Everything we just discussed relies on your screen reader doing the heavy lifting. But GitHub actually has its own internal system of keyboard shortcuts built directly into the website. These are JavaScript shortcuts that trigger actions without you needing to navigate to a button at all.

      -

      Jamie: And this is where the clash happens, right? Because if I press the letter G on GitHub, GitHub wants to use that as a shortcut. But my screen reader intercepts it and says, no, there are no graphics on this page, because G is the screen reader shortcut for graphics.

      -

      Alex: Precisely. This is why we spent so much time talking about Browse Mode and Focus Mode earlier. To use GitHub's built-in shortcuts, you must force your screen reader into Focus Mode. You press NVDA plus Space, or Insert plus Z for JAWS. Now, your screen reader goes to sleep, and your keystrokes go straight to GitHub.

      -

      Jamie: So what are these GitHub shortcuts? How do I even know what they are?

      -

      Alex: The most important shortcut to learn is the Question Mark key, which is Shift plus Forward Slash. If you are not inside a text box, pressing the Question Mark key opens a dialog on the screen that lists every single GitHub shortcut available for the exact page you are currently on.

      -

      Jamie: And it is context aware! If you press the Question Mark on a repository page, it shows you repository shortcuts. If you press it while looking at a Pull Request, it shows you Pull Request shortcuts. It is essentially a built-in cheat sheet that updates dynamically.

      -

      Alex: Let us talk about some of the most powerful ones. GitHub uses a lot of sequence shortcuts, where you press one key, let go, and then press a second key. The letter G is used for going places. If you enter Focus Mode and press G, pause for half a second, and then press I, GitHub will instantly teleport you to the Issues tab of the repository.

      -

      Jamie: I love the teleportation analogy. You do not have to find the navigation landmark, you do not have to tab through menus. You just type G then I, and boom, you are on the Issues page. And if you type G then P, you teleport to the Pull Requests page. It is like knowing the secret knock to get into different rooms.

      -

      Alex: Another essential one is the Forward Slash key. Pressing Forward Slash from anywhere on the page instantly moves your focus into the primary search bar. And what is great about the Forward Slash is that it often works even if you are still in Browse Mode, because it immediately moves browser focus to an interactive form field, which usually wakes your screen reader up automatically.

      -

      Jamie: Okay, what about finding a specific file? Because navigating the table with Control plus Alt plus arrows is great, but what if a repository has hundreds of files nested in dozens of folders?

      -

      Alex: Great question. GitHub has a file finder shortcut, which is the letter T. But we have a major conflict here. In NVDA, the letter T jumps to the next table. So if you are in Browse Mode and press T, you just jump to the file list. You must enter Focus Mode first by pressing NVDA plus Space. Then, when you press T, GitHub opens a search box that lets you type the name of any file in the entire repository and jump straight to it.

      -

      Jamie: That is a perfect example of why understanding the difference between your screen reader shortcuts and GitHub shortcuts is so critical. If you do not know about Focus Mode, you will press T and wonder why the file finder never opens.

      -

      Alex: Let us cover two more advanced GitHub shortcuts that are incredibly useful for collaboration. The first is the letter Y. Jamie, do you want to explain what the Y key does?

      -

      Jamie: Yes! The Y key expands the current web address into its canonical URL. Let me explain what that means. Let us say you are looking at a piece of code, and you want to send a link to your coworker pointing to line forty-two. You copy the link and send it. But tomorrow, someone else adds ten lines of code at the top of that file. Now, your coworker clicks your link, and line forty-two is completely different code. The link broke because the file changed.

      -

      Alex: Exactly. It is like giving someone directions to a house based on the color of the paint. If the house gets repainted, they are lost.

      -

      Jamie: Right! So when you are looking at a file, if you press the letter Y, GitHub changes the URL in your browser to a permanent, canonical link tied to the exact commit hash of that exact moment in time. It creates a GPS coordinate that never moves. Even if the file is updated a hundred times, that link will always show the exact version you were looking at.

      -

      Alex: That is a brilliant explanation. The last GitHub shortcut we will mention here is the letter L. When you are viewing an issue or a Pull Request, pressing L will open the Labels menu. From there, you can easily use your arrow keys to check or uncheck labels to organize the work. Just remember, L is another conflict key. In NVDA, L means next list. So you must be in Focus Mode to use the GitHub shortcut.

      -

      Alex: Now, the prompt for this episode specifically mentions our Concept Coverage Checklist, and one of the items we absolutely must cover is Visual Studio Code screen reader shortcuts. Even though this cheat sheet focuses primarily on the GitHub website, your workflow heavily involves taking code from GitHub and opening it in VS Code, or opening it directly in the browser using GitHub dot dev.

      -

      Jamie: And honestly, VS Code can feel even more intimidating than GitHub because it is a full Integrated Development Environment. It has sidebars, panels, terminals, and editor groups. Where do we even start?

      -

      Alex: The best place to start is with the Accessible Help Menu. VS Code has a dedicated help system designed specifically for screen reader users. You can access it by pressing Alt plus F2. This menu will dynamically explain the accessibility features of whatever part of VS Code you are currently focused on.

      -

      Jamie: Oh, that is clever! So if I am in the terminal and I press Alt plus F2, it tells me how to navigate the terminal. But if I am in the editor, it gives me editor tips. It is like having a specialized tour guide who taps you on the shoulder and whispers exactly what you need to know in that moment.

      -

      Alex: Exactly. And the second VS Code feature we must discuss is the Accessible Diff Viewer. A diff, short for difference, is how GitHub and VS Code show you what has changed between two versions of a file. Visually, this is usually shown with red and green highlighting. For screen reader users, reading a standard diff table line by line, trying to figure out what was added and what was removed, is agonizingly slow.

      -

      Jamie: It really is. You end up listening to the screen reader read twenty lines of code that did not even change, just to find the one word that was deleted.

      -

      Alex: This is why the Accessible Diff Viewer is a game changer. When you are looking at a file with changes in VS Code, you press F7 to jump to the next change, or Shift plus F7 to jump to the previous change. This opens a special accessible view that presents the changes as a clean, simple list. It will explicitly announce, for example, line thirty-two removed, followed by the old code, and then line thirty-two added, followed by the new code.

      -

      Jamie: It isolates the signal from the noise. It is like having a highly trained assistant who reads a hundred-page contract, but only reads you the three sentences that were actually modified. You do not have to sift through the entire document yourself.

      -

      Alex: That is exactly what it does. And you can use this same F7 navigation whether you are in your local desktop VS Code, or if you press the Period key on a GitHub repository to open the web-based VS Code editor in your browser.

      -

      Alex: Before we wrap up, let us run through a few quick navigation patterns for everyday tasks. We already talked about using H to jump to headings, and D or R to jump to landmarks. But what about when you want to actually leave a comment?

      -

      Jamie: This is a pattern you will use a dozen times a day. You open an issue. You press the letter D until you hear the Add a Comment landmark. Then you press the letter E to jump into the edit field. You switch to Focus Mode with NVDA plus Space, and you type your message.

      -

      Alex: And here is the pro-tip. When you are finished typing, you do not need to switch back to Browse Mode, press Tab to find the Submit button, and press Enter. That takes too long. While you are still in Focus Mode inside the text box, just press Control plus Enter. On a Mac, that is Command plus Enter. This is the universal submit shortcut across all of GitHub. It submits your comment instantly and saves you a ton of keystrokes.

      -

      Jamie: I wish I had known that when I started. Control plus Enter is burned into my muscle memory now. Another quick pattern is dealing with dropdown menus. When you press Enter on a button like Assignees or Reviewers, a popup menu appears. Do not try to use your screen reader's Browse Mode to read it. Just start typing to filter the list, use your up and down arrows to hear the filtered options, press Enter to select one, and then press the Escape key to close the menu.

      -

      Alex: That Escape key step is vital. GitHub applies your selections as soon as you press Escape to close the menu. If you try to navigate away without pressing Escape, the menu might stay floating open and trap your screen reader focus.

      -

      Jamie: So, if things ever feel stuck, or if your screen reader starts reading things that do not make sense, what is the best troubleshooting step?

      -

      Alex: The number one rule of troubleshooting on GitHub is to check your mode. Nine times out of ten, if something is not working, it is because you are in Browse Mode when you need to be in Focus Mode, or vice versa. Press NVDA plus Space or Insert plus Z to toggle your mode and try the action again.

      -

      Jamie: And if the page layout seems completely different than what we described, make sure your browser window is maximized. GitHub's interface is responsive, meaning it collapses sidebars and moves landmarks around if your window is too small. Maximizing the window ensures you get the consistent desktop layout.

      -

      Alex: Excellent point. Let us summarize our key takeaways for this episode. First, master the difference between Browse Mode for navigating, and Focus Mode for typing and using GitHub's built-in shortcuts. Second, rely on headings, landmarks, and the Elements List to jump through complex pages quickly.

      -

      Jamie: Third, remember the Question Mark key to open the context-aware shortcut cheat sheet on any GitHub page. And fourth, when you are in VS Code, use Alt plus F2 for accessibility help, and F7 to navigate diffs clearly.

      -

      Alex: Perfectly summarized. I highly recommend keeping Appendix B open in a separate window or printing it out to keep near your keyboard as you work through the workshop exercises. It will become your best friend.

      -

      Jamie: It really will. Muscle memory takes time, so be patient with yourself. You are learning a new language, and soon you will be speaking it fluently.

      -

      Alex: Thank you all for listening. In our next episode, episode twenty, we are going to dive deep into managing notifications. We will learn how to tame the GitHub inbox so you only see the alerts that actually matter to your work. Until then, keep practicing those shortcuts, and happy collaborating.

      +

      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.

      - +

      Episode 20: Accessibility Standards Reference

      WCAG 2.2, ARIA roles, and the PR accessibility checklist.

      -

      Based on: Appendix C: Accessibility Standards Reference

      - - -

      Download Episode 20 (MP3)

      +

      Based on: Appendix M: Accessibility Standards Reference

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 20: Accessibility Standards Reference

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is Episode 20, Accessibility Standards Reference. I am Alex, and today we are going to talk about the rules of the road for making web applications and open source projects usable by everyone.

      -

      Jamie: And I am Jamie. If you are joining us at the workshop, you have probably heard these acronyms tossed around all week. Things like W C A G, or ARIA, or Level double A. To be honest, when I started learning GitHub two years ago, this alphabet soup was one of the most intimidating parts. I felt like I needed a law degree just to write a simple button.

      -

      Alex: That is such a common feeling, Jamie. It does sound like a lot of legal jargon. But here is the thing. You do not need to memorize these standards like a textbook. Today, we are going to give you a working understanding of the accessibility standards that govern the web, how they shape GitHub's interface, and most importantly, how they apply to the code you write and review.

      -

      Jamie: Okay, that sounds much more manageable. Just a reference guide, not a final exam. Where do we start?

      -

      Alex: We start with the big one. W C A G. You will often hear people pronounce this as wuh-cag. It stands for the Web Content Accessibility Guidelines. Right now, the standard most modern projects use is W C A G 2 point 2.

      -

      Jamie: Web Content Accessibility Guidelines. Okay. Who actually writes these guidelines? Is it a government?

      -

      Alex: Good question. No, it is not a government. It is maintained by the World Wide Web Consortium, or the W 3 C. They are the same international community that develops the standards for HTML and CSS. W C A G is essentially the global gold standard for what makes digital content accessible to people with disabilities, including screen reader users like many of our listeners.

      -

      Jamie: Got it. So if I want to make sure the pull request I am submitting to an open source project is accessible, W C A G is the measuring stick. But W C A G is massive. I have tried reading the official specification and it is incredibly dense. How do we break it down?

      -

      Alex: We break it down using an acronym. The four principles of W C A G are often abbreviated as POUR. P O U R. Perceivable, Operable, Understandable, and Robust. Every single rule in W C A G belongs to one of these four buckets.

      -

      Jamie: POUR. Okay, let us go through them. What does Perceivable mean in a coding context?

      -

      Alex: Perceivable means information and user interface components must be presentable to users in ways they can perceive. An analogy I like to use is going to a restaurant. If the menu is printed on paper, a sighted person can perceive it by reading it. But if you are totally blind, that paper menu is not perceivable to you. The information is there, but it is locked in a format you cannot access.

      -

      Jamie: Right. So in code, a classic failure of Perceivable would be an image that has no alternative text. If I am navigating a web page and my screen reader just says "image dot J P G", I get absolutely nothing out of it.

      -

      Alex: Exactly. To fix it, you add an alt attribute with descriptive text. Now the information is perceivable through an audio interface or a braille display. Another big part of Perceivable is contrast. W C A G has strict rules about text contrast against its background, which is crucial for low-vision developers. It also dictates that information cannot be conveyed by color alone.

      -

      Jamie: Oh, I have run into that one! A form where the instructions just say, "required fields are marked in red." My screen reader does not announce the color of the text by default, so I had no idea which fields were required. It was incredibly frustrating.

      -

      Alex: That is exactly why the Perceivable principle exists. Okay, let us move to the O in POUR. Operable. This means the user interface components and navigation must be operable by the user. Think of that same restaurant. Even if you can read the menu, can you physically open the door to get inside?

      -

      Jamie: So in web development, Operable is all about how we interact with the page. Keyboard accessibility has to be the biggest part of this, right?

      -

      Alex: It is the cornerstone. W C A G requires that all functionality must be available using only a keyboard. No mouse required. That means you should be able to navigate to every button, every link, and every form field using the Tab key, and activate them using the Enter key or the Spacebar.

      -

      Jamie: And avoid keyboard traps! I have to mention keyboard traps. A few months ago, I was reviewing a pull request for a custom modal dialog. I pressed the Tab key to move inside the modal, but then I could not Tab out of it, and pressing the Escape key did nothing. I was locked inside this pop-up window. I literally had to refresh the whole page to escape.

      -

      Alex: That is a perfect, and painful, example of a W C A G failure under the Operable principle. A user must always be able to move keyboard focus away from a component. Other Operable criteria include giving users enough time to read content before it times out, and providing ways to skip repeated blocks of content, like those "Skip to main content" links you hear at the top of accessible websites.

      -

      Jamie: Alright, we have P for Perceivable, O for Operable. Next is U for Understandable.

      -

      Alex: Understandable means information and the operation of the user interface must be, well, understandable. Going back to the restaurant, you got inside, you can read the menu, but what if the menu is in a language you do not speak, and there are no descriptions of the dishes? You cannot make an informed choice.

      -

      Jamie: How does that translate to code? Are we talking about plain language guidelines?

      -

      Alex: Partly, yes. But programmatically, it means things like identifying the default language of the HTML document using the lang attribute, so the screen reader knows which pronunciation engine to load. If the page is in French, but you do not tell the screen reader it is in French, it will try to read French words using English phonetics, which is entirely incomprehensible.

      -

      Jamie: Oh, I have heard that happen. It sounds like absolute nonsense. What else falls under Understandable?

      -

      Alex: Predictability. When a user navigates to a component, it should not trigger a massive, unexpected change in context. And error handling is huge here. If a user makes a mistake submitting a form, W C A G requires that the error is identified clearly in text, and suggestions for correction are provided. Just putting a red border around an invalid text input is not enough. You need a text message that says "Password must be at least eight characters."

      -

      Jamie: That makes sense. It is about not leaving the user guessing. So the last letter in POUR is R. Robust. What does Robust mean in this context?

      -

      Alex: Robust means content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. Think of it like building a sturdy foundation for a house. If you use standard, well-supported materials, the house will stand up to bad weather. If you use experimental or broken materials, it might collapse.

      -

      Jamie: So this is about writing clean, valid HTML.

      -

      Alex: Exactly. It means your HTML markup does not have major parsing errors, like elements missing their closing tags, or duplicate ID attributes. But the most critical success criterion under Robust is called Name, Role, Value. It states that for every single user interface component, its name, its role, and its current value must be programmatically determinable by assistive technologies.

      -

      Jamie: Name, Role, Value. We are definitely going to dig into that when we talk about ARIA later, because I know that is where ARIA does a lot of the heavy lifting. But before we move on from W C A G, I want to ask about the grading system. I always hear people say things like, "We are targeting W C A G double A compliance." What are the levels?

      -

      Alex: W C A G has three conformance levels. Single A, Double A, and Triple A. Think of them like building codes for accessibility.

      -

      Jamie: Okay, so what is Single A?

      -

      Alex: Level A is the absolute minimum baseline. It removes the most severe barriers that would make the site completely unusable for people with disabilities. Having some form of alt text, and being able to use a keyboard, are Level A. If you do not meet Level A, your site is broken for a lot of people.

      -

      Jamie: So Double A is the next step up.

      -

      Alex: Yes. Level AA includes all the requirements of Level A, plus additional criteria that remove significant barriers. This is the sweet spot. It is the target required by most accessibility laws, government standards, and enterprise policies. GitHub itself is officially committed to W C A G 2 point 2 Level AA compliance. When you are contributing to an open source project and they ask for accessibility, they almost always mean Level AA.

      -

      Jamie: Got it. So what is Level Triple A? Is that like achieving accessibility enlightenment?

      -

      Alex: Sort of. Level AAA includes all A and AA criteria, plus the strictest, most comprehensive rules. It removes remaining barriers for very niche cases. But the W 3 C actually states that it is not recommended to require Level AAA across entire sites, because for some complex content, it is practically impossible to achieve. You apply Triple A where it is feasible, but Double A is your mandatory target.

      -

      Jamie: Okay, so if I am writing code, I am aiming for W C A G 2 point 2 Level AA. And I am keeping POUR in mind. Perceivable, Operable, Understandable, Robust.

      -

      Alex: Exactly. And there are a few specific success criteria you will run into constantly as a developer. We already mentioned 1 point 1 point 1, which requires alt text for non-text content. And 2 point 1 point 1, which requires keyboard accessibility.

      -

      Jamie: What about focus indicators? I know that is a big one for sighted keyboard users and low-vision users.

      -

      Alex: Yes. That is criterion 2 point 4 point 7, Focus Visible. It is a Level AA requirement. It means that when you are navigating with a keyboard, there must be a visible outline or highlight showing you exactly which element currently has focus. And in W C A G 2 point 2, they added a new rule called Focus Appearance, which dictates the minimum size and color contrast of that focus indicator, so it is actually easy to spot.

      -

      Jamie: That is a great addition. I use screen magnification sometimes, and trying to find a tiny, faint gray dotted line around a button is nearly impossible.

      -

      Alex: So, we have covered the W C A G guidelines. Now we need to talk about the tools we use to meet those guidelines when standard HTML is not enough. This brings us to ARIA. A R I A.

      -

      Jamie: Yes, ARIA. I know it stands for Accessible Rich Internet Applications. But for the longest time, I thought ARIA was a totally separate programming language.

      -

      Alex: That is a very common misconception. ARIA is not a separate language. It is a set of specialized attributes you can add to your existing HTML elements.

      -

      Jamie: So why do we need it? If I write good HTML, is that not enough?

      -

      Alex: If you are writing a simple document with headings, paragraphs, standard links, and standard form fields, then yes, native HTML is absolutely enough. In fact, standard HTML is incredibly accessible right out of the box. But the modern web is not just documents anymore. It is full of complex, interactive widgets. Think about a drag-and-drop kanban board, or a multi-select combobox, or an expandable accordion menu.

      -

      Jamie: Right. HTML does not have a native tag for a kanban board.

      -

      Alex: Exactly. HTML has gaps. ARIA fills the gap between what native HTML can express and what complex interactive widgets require. Let me give you an analogy. Imagine a play at a theater. HTML is the script. It tells the actors what to say. But sometimes, a lot is happening on stage without any dialogue. Someone enters the room, someone looks angry, the lights go down.

      -

      Jamie: A sighted audience member can just watch that happen. But a blind audience member needs audio description to know what is going on.

      -

      Alex: Spot on. ARIA is the audio describer for your web application. It does not change how the application looks visually, and it does not change how the application behaves when you click on things. It only changes what is announced to the accessibility tree, which is what screen readers read from. ARIA whispers in the screen reader's ear, telling it the hidden context.

      -

      Jamie: That is a great way to think about it. It only affects the accessibility tree. So, if I add ARIA to a completely broken, unclickable div, it does not magically make it a working button.

      -

      Alex: Correct. Which brings us to the first rule of ARIA. This is so important I want you to remember it above everything else today. The first rule of ARIA is: Do not use ARIA if native HTML suffices.

      -

      Jamie: Do not use ARIA if native HTML works. Why is that?

      -

      Alex: Because native HTML elements come with built-in keyboard support and built-in screen reader support. If you use a native button element, the browser automatically knows it is a button, it automatically makes it focusable with the Tab key, and it automatically lets you activate it with the Enter key or the Spacebar.

      -

      Jamie: But if I use a generic div element, and I just add role equals button to it, what happens?

      -

      Alex: If you add role equals button to a div, your screen reader will announce it as a button. But that is all it does. It does not make it focusable. You would have to manually add a tabindex equals zero attribute. And it does not add keyboard support. You would have to write custom JavaScript to listen for the Enter key and the Spacebar.

      -

      Jamie: Okay, that sounds like a massive amount of extra work just to reinvent a button. I see why the first rule is to just use the native HTML tag.

      -

      Alex: Exactly. You only use ARIA when you are building something custom that HTML cannot handle. Now, ARIA is broken down into three categories. Roles, States, and Properties.

      -

      Jamie: Let us break those down. What is a Role?

      -

      Alex: A Role defines what an element actually is. It is the core identity of the component. We mentioned role equals button. There is also role equals dialog, for pop-up modal windows. Role equals navigation, for a block of navigation links. Once you set a role on an element, it does not change.

      -

      Jamie: Okay, so Role is the identity. What about States?

      -

      Alex: States describe the current condition of the element, and unlike Roles, States are meant to change as the user interacts with the app. For example, if you have a custom accordion menu, it might have aria dash expanded equals false when it is closed. When the user activates it, your JavaScript needs to update that state to aria dash expanded equals true.

      -

      Jamie: Ah, got it. Other states would be things like aria dash checked for a custom checkbox, or aria dash disabled if a button cannot be pressed right now. My screen reader reads those out automatically. It will say, "Submit, button, dimmed" or "button, disabled".

      -

      Alex: Exactly. And the third category is Properties. Properties are stable characteristics that provide extra context, but they do not change like States do. The most common property you will use is aria dash label. You use this to give an accessible name to an element when there is no visible text on the screen.

      -

      Jamie: Like an icon button! On GitHub, there is a button that just looks like a little gear icon to open the repository settings. There is no text that says "Settings". So they use aria dash label equals "Settings", and my screen reader reads that instead of just saying "unlabeled button".

      -

      Alex: Perfect example. Another extremely important set of ARIA roles are the Landmark roles. Landmarks let screen reader users jump directly to major sections of a page, bypassing all the clutter.

      -

      Jamie: Yes! I use landmarks constantly. In NVDA or JAWS, I just press the D key to jump from landmark to landmark. Or if I am on my Mac using VoiceOver, I open the Rotor and navigate by landmarks. It is how I get around complex pages like a GitHub repository.

      -

      Alex: GitHub uses landmarks beautifully. The main ones you will encounter are the banner role, which is the site-wide header at the top. The navigation role, for menus. The main role, for the primary content of the page. And the contentinfo role, which is usually the footer.

      -

      Jamie: I have noticed that on GitHub, there are often multiple navigation landmarks on the same page. There is the main site navigation, the repository navigation, the sidebar. How do I know which is which?

      -

      Alex: That is a great point, and it is a W C A G requirement. When you have multiple landmarks of the same type on a single page, each one must have a unique aria dash label to distinguish them. So GitHub will label one as "Site navigation" and another as "Repository navigation". When you press the D key, your screen reader announces the label along with the landmark role.

      -

      Jamie: That is incredibly helpful. Before we move on to code reviews, I want to ask about one more ARIA feature. Live regions. I have heard developers talk about aria dash live. What does that do?

      -

      Alex: Live regions are magic for single-page applications. Imagine you are filling out a form, and you type in a username. A little message pops up on the screen dynamically that says "Username is available." If you are sighted, you see it appear. But if you are using a screen reader, your focus is still inside the text box. You do not know that new text appeared somewhere else on the page.

      -

      Jamie: Right. Unless I manually navigate around the whole page looking for changes, which is tedious.

      -

      Alex: So, you wrap that message container in an attribute called aria dash live. When you inject new text into an aria-live region, the browser automatically sends that new text straight to the screen reader to be announced aloud, without moving the user's focus.

      -

      Jamie: Oh, that is how that works! I love when applications do that. It makes it feel so snappy. I type my name, and I just hear "Username is available" in the background. Are there different types of live regions?

      -

      Alex: Yes, there are two main settings. Aria dash live equals polite, and aria dash live equals assertive. Polite means the screen reader will wait until it finishes its current sentence before announcing the update. This is what you should use 95 percent of the time. Assertive means the screen reader will immediately interrupt whatever it is currently saying to announce the update. You should only use assertive for critical, urgent errors.

      -

      Jamie: Okay, so we have covered W C A G and the POUR principles. We have covered ARIA, including Roles, States, Properties, Landmarks, and Live Regions. Now, let us make this practical. I am working on an open source project on GitHub. I get assigned to review a pull request, or PR, from another contributor. How do I review their code for accessibility?

      -

      Alex: Reviewing a PR for accessibility is just like reviewing it for security or performance. It is a checklist. And it is completely normal to feel a little intimidated when you are checking someone else's code. But you already know the fundamentals.

      -

      Jamie: So what is on the PR Accessibility Checklist? What are the red flags I should be looking for before I approve and merge someone's code?

      -

      Alex: First, check the HTML structure. Did they add any new images? If yes, verify that every single image tag has an alt attribute. Even if it is a purely decorative image, it needs an empty alt attribute, literally just alt equals quote quote. That tells the screen reader to safely ignore it.

      -

      Jamie: Got it. Check for alt text. What next?

      -

      Alex: Next, look at any new interactive elements. Did they add a new button, a dropdown, or a custom widget? If so, you must verify that it is fully keyboard accessible. Can you reach it with the Tab key? Can you activate it with the Enter key or the Spacebar? And does it have a visible focus indicator when you tab to it?

      -

      Jamie: Okay, so I am checking for the Operable principle. What about forms?

      -

      Alex: If the PR adds any new form fields, check that every input has an associated label element. The HTML label tag needs a "for" attribute that exactly matches the "id" attribute of the input field. This is what guarantees that when a screen reader lands on the text box, it reads the correct label aloud.

      -

      Jamie: I will also check for color reliance. If the PR notes say "Error states are now highlighted in red," I am immediately going to flag that and ask, "Is there also a text explanation or an icon for the error?" Because color cannot be the only indicator.

      -

      Alex: That is fantastic, Jamie. That is exactly the right mindset. And finally, check for dynamic content. If the PR introduces a feature that updates the page without a full reload, like a search filter or a shopping cart counter, check if they used an aria-live region to announce those updates to screen reader users.

      -

      Jamie: Okay, let us say I find an issue. The contributor created a custom toggle switch using a div, and there is no keyboard support and no ARIA role. How do I write that feedback in the PR review without sounding like the accessibility police?

      -

      Alex: The best way to leave feedback is to be specific, objective, and reference the standard. Do not just say, "This toggle is not accessible." Instead, say something like, "This custom toggle switch cannot be operated with a keyboard, which is a barrier for screen reader and keyboard-only users. This fails W C A G 2 point 1 point 1 Keyboard. Could we update this to use a native HTML checkbox, or add role equals switch and keyboard event listeners?"

      -

      Jamie: I like that. It removes the emotion from it. You are not saying they wrote bad code, you are just pointing out that it misses a specific, documented requirement, and you are offering a path to fix it.

      -

      Alex: Exactly. And while you can catch a lot of things by reading the code, you should also test it. There are automated tools you can use, like the axe DevTools browser extension, which will scan the rendered page and catch about 30 to 40 percent of W C A G violations automatically.

      -

      Jamie: Only 30 to 40 percent? That is lower than I expected.

      -

      Alex: It is. Automated tools are great for catching missing alt text or missing labels, but they cannot tell if the alt text actually makes sense, and they cannot test keyboard flow. That is why manual testing is required. The best way to test a PR is to pull the branch to your local machine, unplug your mouse, turn on your screen reader, and try to use the new feature. If you can complete the task smoothly, it is likely in good shape.

      -

      Jamie: Wow, we covered a massive amount of ground today. I actually feel like I have a solid grasp on W C A G and ARIA now. It is not just alphabet soup anymore.

      -

      Alex: You absolutely do. Let us recap the concrete takeaways from today's episode. First, W C A G is the global standard for web accessibility, built on four principles: Perceivable, Operable, Understandable, and Robust. Or POUR.

      -

      Jamie: Second takeaway: The standard target for GitHub and most open source projects is W C A G 2 point 2 Level AA compliance.

      -

      Alex: Third, ARIA is a set of attributes that fills the gaps in native HTML by providing Roles, States, and Properties to the accessibility tree. But remember the first rule of ARIA: Do not use ARIA if native HTML suffices.

      -

      Jamie: And finally, when reviewing a pull request, use your accessibility checklist. Look for alt text, verify keyboard accessibility, ensure forms have labels, and check that dynamic updates use aria-live regions. Unplug your mouse and test it yourself.

      -

      Alex: Perfect summary. You do not need to be an accessibility expert to make a huge impact on an open source project. Just keeping these fundamentals in mind during your code reviews will make the web better for everyone.

      -

      Jamie: So what is up next?

      -

      Alex: In Episode 21, we are moving from theory to practice. We will be diving into the GitHub Interface Deep Dive. We will explore exactly how GitHub's web interface is structured, how to navigate its complex landmark architecture, and the specific keyboard shortcuts that will make you incredibly fast at triaging issues and reviewing code.

      -

      Jamie: I cannot wait for that one. Thanks for listening to Gitt Going with GitHub. We will see you in the next episode!

      +

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

      +

      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.

      +
      +

      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: 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).

      +
      +

      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: 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 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

      - - -

      Download Episode 21 (MP3)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 21: Git Authentication

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is episode twenty-one, Git Authentication. I am Alex, and as always, I am here to help you navigate the world of Git, GitHub, and open source collaboration.

      -

      Jamie: And I am Jamie! I am here to ask the questions, share my own learning bumps, and hopefully make this journey a little smoother for you. And Alex, today we are talking about a topic that caused me more stress than learning Git itself when I started two years ago. Authentication. Proving to GitHub that I am who I say I am.

      -

      Alex: You are definitely not alone in that, Jamie. Authentication is a major hurdle for a lot of developers. You spend all this time writing code, you make your commit, you type your push command, and then the terminal just throws up an error and refuses to let your code through. It feels like getting stopped at the door of a party you were invited to.

      -

      Jamie: Exactly! The bouncer is just standing there shaking their head. So, to set the stage for everyone, why is authentication needed in the first place? We can read repositories and clone open source projects without ever logging in, right?

      -

      Alex: That is exactly right. If a repository on GitHub is public, you do not need to authenticate to clone it to your machine, or to read the issues and pull requests. Think of a public repository like a public library. Anyone can walk in off the street, pull a book off the shelf, and read it. You do not need a library card just to browse.

      -

      Jamie: But if I want to write a chapter in that book, or bring a new book to the library, that changes things.

      -

      Alex: Precisely. When you want to push commits to a repository, clone a private repository, or access an organization's internal code, GitHub needs to know who you are. You need to prove your identity. You need to show your ID badge to get behind the front desk. That is what authentication is: proving you are who you say you are.

      -

      Jamie: Okay, so I need an ID badge. When I first started, I thought I could just type in my GitHub username and my GitHub account password in the terminal. But that does not work anymore, does it?

      -

      Alex: No, it does not. A few years ago, GitHub removed the ability to use your account password for command line operations. It was a security risk. If someone stole your password, they had the master key to your entire account. So today, we have two primary ways to authenticate with GitHub from the command line: HTTPS and SSH.

      -

      Jamie: HTTPS versus SSH. Let us break those down. Which one should we start with?

      -

      Alex: Let us start with HTTPS, because it is the method we recommend for our two-day workshop. It is generally easier to set up using a screen reader because you do it entirely through the GitHub web interface, without needing to configure complex terminal files. When you use HTTPS, you authenticate using something called a Personal Access Token, or a PAT.

      -

      Jamie: A Personal Access Token. I love analogies, so tell me if this works. If my GitHub password is the master key to my entire house, a Personal Access Token is like a valet key for my car. I can give it to the valet, and it lets them drive the car to park it, but it will not unlock the glovebox or the trunk. And if the valet loses it, I can just deactivate that specific key without changing the locks on my whole house.

      -

      Alex: That is a brilliant analogy, Jamie. That is exactly what a Personal Access Token is. It is a password-like string of characters that you generate on GitHub. When Git asks for your password in the terminal, you paste this token instead. And just like the valet key, you can give it specific permissions, which we call scopes, and you can set it to expire automatically.

      -

      Jamie: So how do we create one of these tokens? What is the workflow like for a screen reader user?

      -

      Alex: First, you will log into GitHub, open your account menu, and navigate to the Settings page. From there, you move to the section called Developer Settings, and you will find Personal Access Tokens. Now, when you get there, you are going to see two options: Fine-grained tokens, and Tokens classic.

      -

      Jamie: Oh right, the classic versus fine-grained dilemma. What is the difference?

      -

      Alex: A classic token is like a hotel keycard that opens your room, the gym, and the pool, regardless of what time it is. It applies to all the repositories you have access to. A fine-grained token is much stricter. It is a keycard that only opens your specific room, and maybe only between two and four in the afternoon. You can restrict fine-grained tokens to single repositories.

      -

      Jamie: Fine-grained sounds more secure, but classic sounds easier to deal with when you are just starting out.

      -

      Alex: Exactly. For the workshop, we recommend generating a classic token. It is much faster to set up. So, you select Generate new token classic. First, it asks for a note. Give it a descriptive name, like Workshop Laptop Token. Then, you set an expiration. I highly recommend setting it to thirty or sixty days. Never set a token to no expiration.

      -

      Jamie: Because if you forget about it and it gets leaked months from now, someone has access to your account. Thirty days is perfect for a workshop. And then we set the scopes, right? The permissions.

      -

      Alex: Yes. The scopes are presented as a list of checkboxes. For our workshop, you only need to check two boxes. First, check the box labeled repo. This gives the token full control of private and public repositories, which means you can push your code. Second, check the box labeled workflow. You only need this if you are going to be updating GitHub Actions workflows, but we do touch on that, so it is good to have.

      -

      Jamie: Okay, so I check repo, I check workflow, and I activate the Generate token button. What happens next? This is the part that always catches people off guard.

      -

      Alex: This is critical. When the page reloads, GitHub displays your new token. It is a long string of random letters and numbers. This is the one and only time GitHub will ever show you this token. If you navigate away from this page, you cannot get it back.

      -

      Jamie: You have to copy it right then and there. For our screen reader users, how is this token presented on the page?

      -

      Alex: It appears in a standard read-only text field. You can navigate to it, press Control plus A to select all the text in the field, and press Control plus C to copy it.

      -

      Jamie: And then where do I put it? I know I should not just leave it on my clipboard.

      -

      Alex: You need to store it securely. The absolute best option is a password manager, like 1Password, Bitwarden, or your operating system's built-in keychain. Create a new secure note or password entry and paste the token there.

      -

      Jamie: What should we absolutely avoid doing with this token?

      -

      Alex: Do not paste it into a plain text document that syncs to your cloud storage. Do not email it to yourself. And please, do not save it in a file inside your Git repository, because you might accidentally commit it and push it to GitHub for the world to see. Treat it exactly like your bank password.

      -

      Jamie: Okay, token is generated and safely stored in my password manager. Now, how do I actually use it?

      -

      Alex: The next time you try to push a commit to GitHub, the terminal will pause and prompt you. It will ask for your Username. You type your GitHub username and press Enter. Then it asks for your Password. This is where you paste your Personal Access Token.

      -

      Jamie: And when you paste it in the terminal, it might not read the characters out loud, or even show asterisks on the screen, right? That is a standard terminal security feature.

      -

      Alex: Correct. The terminal hides your input so someone looking over your shoulder cannot see the length of your token. Just paste it, press Enter, and if everything is correct, your push will succeed.

      -

      Jamie: But wait. Do I have to go into my password manager, copy that huge string of text, and paste it into the terminal every single time I want to push a commit? That sounds exhausting.

      -

      Alex: It would be! But thankfully, you do not have to. This is where credential helpers come in. A credential helper is a piece of software that securely remembers your token for you. Think of it like the bouncer at the club remembering your face. You showed your ID once, and now they just wave you through when you come back.

      -

      Jamie: Oh, thank goodness. How do we get one of those bouncers?

      -

      Alex: If you are on Windows and you installed Git for Windows, it comes with something called Git Credential Manager. It is a fantastic, cross-platform credential helper. The first time you push, it will actually pop up a secure window asking you to authenticate, and once you provide your token, it saves it securely in the Windows Credential Manager. You never have to type it again until the token expires. On macOS, it integrates similarly with the macOS Keychain.

      -

      Jamie: Alright, so that is HTTPS and Personal Access Tokens. Generate the token, save it in a password manager, paste it once, and let Git Credential Manager handle the rest. But you mentioned there is a second method. SSH keys. What are those, and why would someone choose SSH over a Personal Access Token?

      -

      Alex: SSH stands for Secure Shell. It is a protocol for securely communicating between two computers. While a Personal Access Token is like a password you type in, SSH uses something called public-key cryptography. It relies on a pair of keys: a private key and a public key.

      -

      Jamie: Okay, time for another analogy. How does public-key cryptography work?

      -

      Alex: Imagine you buy a very special kind of padlock. This padlock comes with a key, but it works in reverse of a normal lock. You keep the physical key on your keychain. That is your private key. You take the padlock itself, make a hundred copies of it, and hand them out to your friends, or in this case, you give one to GitHub. That padlock is your public key.

      -

      Jamie: So I give GitHub the open padlock, and I keep the key.

      -

      Alex: Exactly. When you want to talk to GitHub, GitHub snaps your padlock onto a box of data and sends it to you. Because you are the only person in the world who has the physical key that opens that specific padlock, only you can open the box. That is how the authentication happens. It proves you are you, because only you hold the private key.

      -

      Jamie: That sounds incredibly secure. And the best part is, there is no password to type at all, right? The terminal just uses the key file sitting on my hard drive.

      -

      Alex: Right. Once it is set up, it is completely invisible. You just push, and it works. SSH keys are considered more secure than tokens, and they do not expire unless you tell them to. However, the initial setup requires running several commands in the terminal, which can be a bit more tedious with a screen reader.

      -

      Jamie: Let us walk through that terminal setup. How do I actually make this lock and key?

      -

      Alex: First, you open your terminal and use a command called ssh dash keygen. The full command we recommend is ssh dash keygen space dash t space ed25519 space dash capital C space followed by your email address in quotes.

      -

      Jamie: Let me break that down. Ssh dash keygen is the program. Dash t tells it what type of key to make, and we are using e d two five five one nine. I remember that used to be r s a, but e d two five five one nine is the newer, more secure standard. And then dash capital C is just adding a comment, like our email, so we know whose key it is.

      -

      Alex: Perfect breakdown. When you press Enter, the terminal will ask where you want to save the key. Just press Enter again to accept the default location, which is a hidden folder in your user directory called dot ssh. Then, it will ask if you want to enter a passphrase.

      -

      Jamie: A passphrase? I thought the whole point was to avoid passwords.

      -

      Alex: A passphrase adds an extra layer of security. If someone steals your laptop and extracts your private key file, they still cannot use it without the passphrase. It is highly recommended, but optional. If you do not want one, you can just press Enter twice to leave it blank.

      -

      Jamie: Okay, so the command finishes, and it tells me it saved my keys. What exactly did it create?

      -

      Alex: It created two files in that dot ssh folder. One is called id underscore ed25519. That is your private key. Never share that with anyone. Ever. The other file is called id underscore ed25519 dot pub. Dot pub stands for public. That is the padlock you are going to give to GitHub.

      -

      Jamie: So how do we give it to GitHub?

      -

      Alex: You need to copy the contents of that dot pub file. On Windows, if you are using PowerShell, you can type Get dash Content space tilde slash dot ssh slash id underscore ed25519 dot pub space pipe space Set dash Clipboard. That reads the file and copies it directly to your clipboard.

      -

      Jamie: Oh, that is a fantastic trick. On macOS, you would use pbcopy. So you type p b copy space less than sign space tilde slash dot ssh slash id underscore ed25519 dot pub. It does the exact same thing. The contents of the public key are now on my clipboard.

      -

      Alex: Once it is on your clipboard, you navigate to GitHub in your browser. Go to Settings, then select SSH and GPG keys from the sidebar. Activate the button that says New SSH key. Give it a title, like Workshop Laptop SSH Key. Make sure the Key type is set to Authentication Key, and then paste your clipboard into the Key field. It will look like a long string of gibberish starting with ssh dash ed25519. Finally, activate Add SSH key.

      -

      Jamie: Okay, the padlock is officially registered at GitHub. How do I know if it actually worked? How do I test the connection?

      -

      Alex: You go back to your terminal and type ssh space dash capital T space git at github dot com. This tells your computer to attempt an SSH connection to GitHub. The first time you do this, your computer might say it does not recognize GitHub's fingerprint and ask if you want to continue connecting. You type yes and press Enter.

      -

      Jamie: And what is the success message we are listening for?

      -

      Alex: Your screen reader should read out: Hi followed by your username! You have successfully authenticated, but GitHub does not provide shell access. That means the handshake worked perfectly. You are authenticated.

      -

      Jamie: That is a great feeling when you hear that message. Now, if I originally cloned my repository using HTTPS, but I just set up SSH, do I need to delete the repository and clone it again?

      -

      Alex: No, you do not need to start over. You just need to change the remote URL. Remember from our earlier episodes, the remote is just the address book entry for GitHub. You can change it by typing git space remote space set dash url space origin space followed by the new SSH URL. The SSH URL always looks like git at github dot com colon your dash username slash the dash repository dot git.

      -

      Jamie: Okay, so we have covered authenticating to prove who we are so we can push code. But there is another layer to this that is becoming really important in open source. Commit signing. I have noticed on GitHub, when I review pull requests, some commits have a little green badge next to them that says Verified, and others say Unverified. What is that about?

      -

      Alex: That is a great observation. This is where people often get confused. Authenticating proves you have the right to push code to a repository. Commit signing proves that a specific commit was actually authored by you, and has not been altered by anyone else.

      -

      Jamie: Why do we need to prove that? If I pushed it, didn't I author it?

      -

      Alex: Not necessarily. Remember that in Git, you configure your name and email using git config. I could configure my local Git to say my email is jamie at example dot com. I could write a terrible piece of code, commit it, and if I have push access to a repository, I could push it. The history would say Jamie wrote it, even though Alex actually wrote it. Git does not verify email addresses by default.

      -

      Jamie: Oh, wow. That is a huge loophole. So someone could spoof my identity in the commit history.

      -

      Alex: Exactly. Commit signing fixes that. When you sign a commit, you are applying a cryptographic signature to it. It is like a notary public stamping a legal document, or putting a wax seal on an envelope. GitHub checks that signature, verifies it against the keys you have uploaded to your account, and if it matches, it slaps that Verified badge on the commit. Many open source projects now require signed commits to prevent identity spoofing.

      -

      Jamie: So how do I get that Verified badge? How do I sign my commits?

      -

      Alex: There are two main methods: GPG signing and SSH signing. GPG stands for GNU Privacy Guard. It is the traditional method. You generate a completely separate set of GPG keys, export them, upload them to GitHub, and configure Git to use them. It is highly secure, but it involves a lot of complex terminal commands and key management.

      -

      Jamie: I remember trying to set up GPG years ago and getting so lost in the terminal output. You said there are two methods. What is the other one?

      -

      Alex: The newer, much simpler method is SSH signing. If you already set up an SSH key for authentication, like we just discussed, you can reuse that exact same key to sign your commits.

      -

      Jamie: Wait, really? I can use the same key for both? That is amazing. How do I turn that on?

      -

      Alex: It takes three simple terminal commands. First, you tell Git to use SSH for signing by typing git space config space dash dash global space gpg dot format space ssh. Second, you tell Git which key to use. You type git space config space dash dash global space user dot signingkey space followed by the path to your public key, like tilde slash dot ssh slash id underscore ed25519 dot pub.

      -

      Jamie: And the third command?

      -

      Alex: You tell Git to automatically sign everything. Type git space config space dash dash global space commit dot gpgsign space true.

      -

      Jamie: That is it on the terminal side? What about on GitHub?

      -

      Alex: You just need to upload that same public key to GitHub one more time, but this time, when you add the new SSH key in settings, you change the Key type dropdown from Authentication Key to Signing Key. Once you do that, every commit you make will be signed, and GitHub will display the Verified badge.

      -

      Jamie: For our screen reader users, how do we check if a commit has that Verified badge on GitHub?

      -

      Alex: When you navigate to a repository's commit history, each commit is presented in a list or table row. If you are using NVDA or JAWS, you can use your down arrow to read through the commit row, and it will read the badge text, Verified or Unverified, inline with the commit details. With VoiceOver, you use VO plus Right Arrow through the row, and the badge is read as a button with the text Verified. You can even activate that button to see the signature details.

      -

      Jamie: That is incredibly helpful to know. And there is a setting on GitHub called Vigilant Mode, right? What does that do?

      -

      Alex: Vigilant Mode is an optional setting in your GitHub account. If you enable it, GitHub will actively mark any unsigned commit associated with your account with a yellow Unverified badge. It is a way of telling the world, Hey, I sign all my work. If you see a commit with my name on it that does not have a Verified badge, it is a fake. Do not trust it.

      -

      Jamie: This has been so enlightening, Alex. Before we wrap up, let us do a quick troubleshooting round. What happens when things go wrong? Let us say I try to push, and the terminal says Authentication failed. What is the most likely culprit?

      -

      Alex: If you are using HTTPS, an Authentication failed error almost always means your Personal Access Token has expired. Tokens have a shelf life. When they expire, they stop working silently. The solution is to go back to GitHub, generate a new token, clear your credential manager cache, and try pushing again. Git will prompt you for the new token.

      -

      Jamie: What if I am using SSH, and the terminal says Permission denied publickey?

      -

      Alex: That means GitHub received an SSH connection, but it did not recognize the key. First, verify that you actually added the public key to your GitHub settings. Second, make sure your local SSH agent is running and has your key loaded. You can check this by typing ssh dash add space dash l.

      -

      Jamie: And what if it says Host key verification failed? That sounds scary.

      -

      Alex: It sounds scary, but it usually just means your computer has never connected to GitHub before, and it wants you to explicitly trust GitHub's server. You can fix it by typing ssh dash keyscan space github dot com space two greater than signs space tilde slash dot ssh slash known underscore hosts. That command grabs GitHub's public fingerprint and adds it to your trusted list.

      -

      Jamie: Okay, that makes it feel much more manageable. Authentication errors look intimidating, but they usually just boil down to an expired token or a missing key.

      -

      Alex: Exactly. Do not let the terminal errors panic you. Take a breath, read the error, and remember the core concepts.

      -

      Jamie: Let us summarize our key takeaways for this episode. First, you need authentication to push code to GitHub. Reading public code is free, but writing requires proving who you are. Second, for this workshop, we recommend using HTTPS with a Personal Access Token. It is easier to set up with a screen reader.

      -

      Alex: Third, treat your Personal Access Token or your SSH private key like your bank password. Never share them, and store them in a secure password manager. And fourth, if you want that coveted Verified badge on your commits, set up SSH commit signing. It takes five minutes and adds a tremendous layer of trust to your open source contributions.

      -

      Jamie: I love that. We are all about building trust in open source. So, we are authenticated, our commits are verified, and we are ready to actually start moving code around. What is up next?

      -

      Alex: In Episode twenty-two, we are diving into Forking and Cloning. We will explain how to make your own personal copy of an open source project, bring it down to your local machine, and get it ready for your first real contribution. You will not want to miss it.

      -

      Jamie: I cannot wait. Thanks for listening, everyone, and we will catch you in the next episode!

      +

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

      +
      +

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

      +
      +

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

      - +

      Episode 22: GitHub Flavored Markdown

      Markdown syntax, GitHub extensions, and writing accessible documentation.

      -

      Based on: Appendix E: GitHub Flavored Markdown

      - - -

      Download Episode 22 (MP3)

      +

      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: Welcome to Gitt Going with GitHub. This is episode 22, GitHub Flavored Markdown.

      -

      Jamie: We are officially halfway through our two-day workshop material! If you have been following along, you already know how to clone repositories, navigate branches, and make commits. But today, we are talking about how we actually write the text that goes into our documentation, our pull requests, and our issues.

      -

      Alex: Exactly. Before we dive in, the only prerequisite for this episode is being comfortable opening a file in your editor. If you are using VS Code, that means knowing how to use the command palette with Control plus Shift plus P, or Command plus Shift plus P on a Mac, to navigate to your files.

      -

      Jamie: So Alex, when I first started learning GitHub about two years ago, I kept hearing the word Markdown. People would say, just write it in Markdown, or check the Markdown file. And I realized that almost every project has a file called read me dot M D. The M D stands for Markdown. But what actually is it?

      -

      Alex: At its core, Markdown is a lightweight markup language. And to define that, think about how you might write a document in Microsoft Word. In a heavy word processor, the formatting is hidden. You press a button to make text bold, and the software handles the underlying code. A lightweight markup language flips that. You write in plain text, using standard punctuation marks to indicate formatting, and then a program translates those symbols into a beautifully formatted document.

      -

      Jamie: I love the analogy of writing a plain text email, but you are sprinkling in secret codes that a machine later translates. It is just text. You do not need any special software to read or write it. A screen reader reads it perfectly because it is just letters and punctuation.

      -

      Alex: Exactly. And today we are specifically talking about GitHub Flavored Markdown, often abbreviated as G F M. Standard Markdown has been around for decades, but GitHub added their own special extensions to make it perfect for software development. Things like task lists, alert callouts, and code blocks.

      -

      Jamie: Let us start with the absolute basics. How do we give our document structure?

      -

      Alex: Structure comes from headings. In Markdown, you create a heading by typing a number sign, also known as a hash symbol, followed by a space, and then your text. One hash mark creates a heading level one, or H 1. Two hash marks create a heading level two, or H 2. And this goes all the way down to six hash marks for an H 6.

      -

      Jamie: This is so important for screen reader users. Think of headings like a nested folder structure on your computer, or an outline for a term paper. When I navigate a long read me file, the very first thing I do is press the letter H in my screen reader to jump from heading to heading.

      -

      Alex: Which brings up a critical rule for writing accessible Markdown. You must respect the heading hierarchy. Never skip heading levels just because you want the text to render at a certain size. Do not jump from a heading level two straight to a heading level four. If you do, a screen reader user navigating by heading will think they missed an entire section of your document.

      -

      Jamie: I definitely made that mistake when I started. I thought, oh, heading level three is too big, let me use heading level five. But headings are for structure, not style.

      -

      Alex: Exactly. Now, what about the regular text under those headings? Paragraphs in Markdown are incredibly simple. You just type your text. When you want a new paragraph, you press the Enter key twice to leave a blank line. If you do not leave a blank line, Markdown will just combine the text into the same paragraph.

      -

      Jamie: And if I want to emphasize a word? Say I am writing instructions and I really want to stress the word "not".

      -

      Alex: You have two main types of emphasis: italic and bold. Think of these like vocal inflection. Italic is like leaning in to emphasize a point, while bold is like shouting to ensure it is heard. To make a word italic, you wrap it in single asterisks. Asterisk, the word, asterisk. To make it bold, you use double asterisks. Asterisk, asterisk, the word, asterisk, asterisk.

      -

      Jamie: Screen readers handle this quite well, depending on your verbosity settings. Some will change their pitch slightly when reading emphasized text.

      -

      Alex: Let us move on to something that connects our documents together: links. Markdown gives us a few ways to create hyperlinks.

      -

      Jamie: The standard way is called an inline link. The syntax always tripped me up at first because it uses two different types of brackets.

      -

      Alex: It takes practice! For an inline link, you wrap the clickable text in square brackets, immediately followed by the U R L in parentheses. No spaces between the closing square bracket and the opening parenthesis.

      -

      Jamie: So left bracket, the words GitHub Home, right bracket, left parenthesis, H T T P S colon slash slash github dot com, right parenthesis.

      -

      Alex: Perfect. Think of an inline link like a direct flight. The destination is written right there next to the text. But sometimes, if you have a lot of links in a paragraph, reading the raw Markdown gets very noisy. That is where reference links come in.

      -

      Jamie: Reference links are brilliant. They are exactly like endnotes in a printed book. Instead of putting the U R L right there in the sentence, you put a number or a label in square brackets. So you write, left bracket, GitHub Home, right bracket, left bracket, the number one, right bracket. Then, anywhere else in the document, usually at the very bottom, you define what number one means.

      -

      Alex: You define it by typing left bracket, the number one, right bracket, a colon, a space, and then the U R L. When GitHub renders the document, it turns the text into a standard link. This makes the raw plain text much cleaner to read with a screen reader.

      -

      Jamie: And what about autolinks?

      -

      Alex: Autolinks are the easiest. If you just paste a full U R L that starts with H T T P or H T T P S, GitHub automatically turns it into a clickable link. It is like the internet recognizing a U R L automatically. But be careful here. For accessibility, pasting raw U R Ls is usually a bad idea.

      -

      Jamie: Right, because a screen reader will read out every single character of a messy U R L. It is always better to use an inline or reference link to provide descriptive link text. Instead of a link that says "click here" or a raw U R L, your link text should say "Review the setup instructions."

      -

      Alex: Let us talk about images, because the syntax is almost identical to links, but with one crucial addition.

      -

      Jamie: The exclamation mark! Or as programmers like to call it, the bang.

      -

      Alex: Yes. To embed an image, you start with an exclamation mark, then square brackets containing the alt text, then parentheses containing the U R L or file path of the image.

      -

      Jamie: So, exclamation mark, left bracket, Alt Text goes here, right bracket, left parenthesis, image dot P N G, right parenthesis.

      -

      Alex: This is where we need to talk about writing descriptive alt text. Alt text is alternative text. If an image cannot load, or if a person is using a screen reader, the alt text is what gets read aloud.

      -

      Jamie: Think of alt text like an audio description track for a movie. You need to convey the meaning and context of the image, not just a literal description of every pixel. And please, do not start your alt text with the words "Image of" or "Picture of". The screen reader already announces that it is an image.

      -

      Alex: Exactly. If the image is a screenshot of a command line showing an error message, your alt text should actually include the text of the error message. If the image is a chart showing performance going up, say "Line chart showing a twenty percent increase in performance over three months."

      -

      Jamie: Okay, so we have headings, paragraphs, links, and images. What about lists? I feel like half of my time on GitHub is spent writing lists.

      -

      Alex: Lists are incredibly common. You have unordered lists, which are just bullet points, and ordered lists, which are numbered.

      -

      Jamie: An unordered list is like a grocery list. The order does not strictly matter. To make one, you just start a line with a dash or an asterisk, followed by a space, and then your item.

      -

      Alex: And an ordered list is like a recipe. The steps must happen in sequence. For these, you start the line with a number, a period, a space, and your text. Like, one dot space preheat the oven.

      -

      Jamie: One thing I love about Markdown is that for ordered lists, you can actually just use the number one for every single item. One dot space do this. On the next line, one dot space do that. When GitHub renders it, it automatically numbers them one, two, three. That way, if you insert a new step in the middle, you do not have to renumber everything manually.

      -

      Alex: That is a great tip. And you can nest lists, too. If you are on an item and you want to create a sub-list, you just move to the next line and indent the dash or the number by two spaces. The screen reader will announce the change in list level, telling you that you have entered a nested list.

      -

      Jamie: Speaking of lists, can we talk about task lists? Because this is a specific GitHub Flavor feature that changed my life.

      -

      Alex: Task lists are fantastic. They create interactive checkboxes right inside your pull requests and issues.

      -

      Jamie: Think of a task list like a digital clipboard hanging on a wall. Anyone with permission can walk up and check a box without having to rewrite the whole list.

      -

      Alex: To create a task list item, you write a regular list item using a dash, then a space, then open and close square brackets with a space between them, then another space, and your text.

      -

      Jamie: So it is dash, space, left bracket, space, right bracket, space, "Write tests." That creates an unchecked box.

      -

      Alex: If you want the box to be checked by default, you replace the space inside the brackets with a lowercase letter X. Dash, space, left bracket, X, right bracket, space.

      -

      Jamie: When you view this in a GitHub issue, it renders as a real HTML checkbox. If you are navigating with N V D A or JAWS, it will read as "checkbox, not checked" or "checkbox, checked". And here is the best part: if you have write access to the repository, you do not have to edit the Markdown file to check the box. You can just navigate to the checkbox in the rendered view, switch to focus mode, and press the Spacebar. It updates the Markdown for you automatically.

      -

      Alex: And in a pull request, GitHub actually reads those checkboxes to create a progress bar. It will tell reviewers, "two of seven tasks completed." It is a brilliant way to manage a release checklist.

      -

      Jamie: Let us pivot to writing code in our Markdown. We are developers, after all. We need to document our code.

      -

      Alex: You have two ways to format code: inline code and code blocks. Inline code is for when you want to format a single word, like a variable name or a keystroke, right in the middle of a sentence.

      -

      Jamie: To do this, you wrap the word in single backticks. The backtick key is usually located in the top left of your keyboard, right under the Escape key. Think of inline code like quoting a single phrase from a foreign language in the middle of your English sentence. It tells the reader, "this specific word is code."

      -

      Alex: For larger chunks of code, you use a code block. This is like setting up a dedicated translation booth. You start by putting three backticks on their own line. Then you paste all your code on the following lines. Finally, you close the block by putting three more backticks on their own line at the end.

      -

      Jamie: And you can enable syntax highlighting by typing the name of the programming language immediately after the first three backticks. So three backticks, the word python, and then press Enter.

      -

      Alex: Syntax highlighting is mostly a visual feature. It changes the font colors based on whether a word is a variable, a string, or a function. For screen reader users, the code block is announced as a "code region", but the text itself is read normally. This is why writing clean, well-named variables is the true key to accessible code. The syntax highlighting does not convey any structural information to the screen reader that the raw text does not already provide.

      -

      Jamie: Okay, what if I need to organize data? Can I build a table in Markdown?

      -

      Alex: You can, using pipes and dashes. The pipe character is usually typed by pressing Shift and the Backslash key.

      -

      Jamie: I always describe Markdown tables as drawing a spreadsheet with sticks. The vertical pipes act as the walls between the columns, and a row of dashes acts as the floor separating the header row from the data rows.

      -

      Alex: Exactly. You start a row with a pipe, type your column header, type another pipe, type the next header, and so on. On the second line, you use pipes to separate dashes. This tells Markdown that the first row was a header. Then you fill in your data on the following lines, separated by pipes.

      -

      Jamie: When GitHub renders this, it builds a proper HTML table. Screen readers like VoiceOver or JAWS will announce it as a table, tell you the number of columns and rows, and let you navigate cell by cell using your standard table commands, reading the column headers as you move.

      -

      Alex: Now let us get into some of the newer, advanced GitHub extensions. Starting with Alert blocks, which were introduced in 2023.

      -

      Jamie: I love these. Sometimes you write documentation and there is a critical warning, like "Do not delete this database," but it just gets lost in the paragraphs. Alerts let you pull that text out into a dedicated callout box.

      -

      Alex: Think of an alert block like an intercom announcement interrupting the regular broadcast. To create one, you use the standard Markdown syntax for a blockquote, which is the greater-than sign followed by a space. But then, you add a special tag in square brackets, starting with an exclamation mark.

      -

      Jamie: So to make a Note alert, you type greater-than sign, space, left bracket, exclamation mark, the word NOTE in all capital letters, right bracket.

      -

      Alex: GitHub supports five types of alerts: Note, Tip, Important, Warning, and Caution. You put that tag on the first line, and then on the next line, you type another greater-than sign and write your message.

      -

      Jamie: From an accessibility perspective, these are handled really well. GitHub renders them as a blockquote, but it adds a strong heading with the alert type. So your screen reader will announce "blockquote," and then read the word "Warning," before reading your message. You get the full semantic meaning without needing to rely on visual styling.

      -

      Alex: Another advanced feature you will encounter is Mermaid diagrams. Have you worked with these, Jamie?

      -

      Jamie: I have, and they are a double-edged sword. Mermaid is a tool that lets you generate flowcharts and graphs using plain text. You create a code block, use the word "mermaid" as the language tag, and then write out relationships. Like, A dash dash greater-than B.

      -

      Alex: It is like a text-based blueprint that automatically draws a house. It is incredibly popular in architecture documentation because developers can version control their diagrams just like code.

      -

      Jamie: But here is the massive accessibility catch. When GitHub renders a Mermaid diagram, it turns it into an S V G image. And GitHub does not automatically generate alt text for that image. To a screen reader, it is often just a locked door. It might announce a generic container, or it might skip it entirely.

      -

      Alex: This is a critical point. If you use Mermaid diagrams, you must take responsibility for the accessibility. The rule is simple: always provide a plain text equivalent before or after the diagram.

      -

      Jamie: Right. If your flowchart shows a five-step pull request workflow, just write out those five steps as an ordered list right before the diagram. The diagram is great for visual learners, but the text list ensures no one is blocked from the information.

      -

      Alex: While we are talking about specialized code, GitHub also supports LaTeX for math equations.

      -

      Jamie: LaTeX is like musical notation, but for numbers and complex algorithms. If you are writing documentation for data science or machine learning, you need a way to show formulas.

      -

      Alex: You use the dollar sign. A single dollar sign on each side of your equation renders it inline, right in the middle of a sentence. Two dollar signs on their own lines create a display block, centering the math and making it larger.

      -

      Jamie: GitHub uses a tool called MathJax to render this. The good news is that MathJax includes an aria-label with the spoken form of the equation. So if you write E equals M C squared in LaTeX, most screen readers will actually read out "E equals M C squared". But for incredibly complex equations, it is still best practice to explain the formula in plain English right after it.

      -

      Alex: Let us wrap up with a few features that help with document navigation. Specifically, footnotes and heading anchors.

      -

      Jamie: Footnotes are brilliant for keeping your main text clean. They work like a two-way portal. You drop a marker in your text, and it creates a link that jumps down to the reference.

      -

      Alex: To create a footnote reference, you use square brackets, a caret symbol, which is Shift plus the number six, and an identifier. So left bracket, caret, the number one, right bracket.

      -

      Jamie: Then at the bottom of your document, you type that same marker, a colon, and your footnote text. When GitHub renders it, the marker becomes a clickable superscript number. And down at the footnote, it automatically adds a back-link, which the screen reader reads as "return to footnote reference". It is so seamless.

      -

      Alex: And finally, heading anchors. Every single heading you create in a GitHub Markdown file automatically gets an anchor I D. This means you can link to any specific section of a document.

      -

      Jamie: Think of an anchor like dropping a pin on a specific paragraph. If I have a heading that says "Getting Started", GitHub takes that text, converts it to all lowercase, and replaces the spaces with hyphens. So the anchor becomes "getting-dash-started".

      -

      Alex: You can then create a link anywhere else in the document that points exactly to that heading by using a hash symbol followed by the anchor name. Left bracket, Go to setup, right bracket, left parenthesis, hash getting-dash-started, right parenthesis.

      -

      Jamie: This is exactly how people build Tables of Contents at the top of really long read me files.

      -

      Alex: One last quick tip before we summarize. Markdown allows you to use basic H T M L inside your files. The most useful one is the details element.

      -

      Jamie: Oh, the details element is a lifesaver. If you are filing a bug report and you have a massive stack trace that is five hundred lines long, do not just paste it into the issue. It makes navigating with a screen reader exhausting.

      -

      Alex: Instead, you write the H T M L tag, less-than sign, the word details, greater-than sign. Inside that, you use a summary tag to write a title, like "Click to expand stack trace". Then you paste your massive code block, and close the details tag.

      -

      Jamie: A screen reader will announce this as a collapsed button. You just press Enter or Space to expand it, and the content appears immediately without reloading the page. It keeps the issue clean while still providing all the data.

      -

      Alex: We have covered a massive amount of syntax today. Jamie, what are the top takeaways our listeners should focus on?

      -

      Jamie: First, Markdown is just plain text with punctuation. Headings use hashes, emphasis uses asterisks, and links use brackets and parentheses. Second, always write accessible Markdown. That means respecting your heading hierarchy, writing descriptive link text instead of pasting raw U R Ls, and always, always providing alt text for your images. And third, when using advanced features like Mermaid diagrams, remember that they render visually. You must include a text equivalent so screen reader users get the same information.

      -

      Alex: Perfect summary. Take some time to practice these in VS Code. Create a file called practice dot M D and try building a table, adding a task list, and linking to an anchor.

      -

      Jamie: In our next episode, we are moving away from writing text and getting back to the repository. We will be covering the Pull Request workflow, specifically how to review code and handle merge conflicts.

      -

      Alex: It is going to be a great one. Until then, keep practicing, and happy coding.

      +

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      - +

      Episode 23: GitHub Gists

      Lightweight code sharing: creating, editing, forking, and embedding Gists.

      -

      Based on: Appendix F: GitHub Gists

      - - -

      Download Episode 23 (MP3)

      +

      Based on: Appendix U: GitHub Gists

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 23: GitHub Gists

      Transcript

      -

      Alex: Welcome back to Gitt Going with GitHub. I am Alex, and this is episode twenty three of our audio series. Today, we are talking about a feature called GitHub Gists. That is spelled G I S T S. We will cover what they are, how to create them using both the web interface and the command line, the difference between public and secret Gists, and how to embed them.

      -

      Jamie: Hi everyone, I am Jamie. And I have to say, I see links to Gists all the time when I am searching for coding answers on the web, but for the longest time, I did not really understand what made them different from a regular GitHub repository. Two years ago when I was first starting out, I thought a Gist was just a funny name for a text file.

      -

      Alex: You were not entirely wrong, Jamie. A Gist at its core is a lightweight way to share code snippets, notes, or small files without going through the trouble of creating a full repository. Think of it as a version controlled digital sticky note.

      -

      Jamie: A version controlled sticky note. I like that. So a snippet, just to define that for everyone, is exactly what it sounds like. A small piece of code. Maybe it is ten lines of Python, or a quick configuration file, rather than a whole software program.

      -

      Alex: Exactly. When you are building a full project, you want a standard GitHub repository. A repository is like a heavy duty filing cabinet. It has folders, multiple branches, an issue tracker for bugs, pull requests for code review, and automated testing. It is built for collaboration. But sometimes, you just do not need all of that heavy machinery.

      -

      Jamie: Right, because creating a whole repository just to share a five line script feels like renting a moving van to transport a single piece of mail. It is way too much overhead.

      -

      Alex: That is a perfect analogy. You use a Gist when you want to share a single code snippet, post a configuration example, share error logs with a colleague, or just save some quick documentation for yourself. Gists do not have issues, they do not have pull requests, and they do not have project boards. They are streamlined specifically for sharing small bits of information quickly.

      -

      Jamie: So how do we actually create one? Do I start from my normal GitHub dashboard?

      -

      Alex: You can, but Gists actually live on their own subdomain. To get started, you will open your browser and navigate to gist dot github dot com.

      -

      Jamie: Got it. Gist dot github dot com. What does that page look like with a screen reader?

      -

      Alex: It is a very clean interface. When the page loads, you can press the letter D to cycle through your landmarks until you hear Main landmark. From there, you can press the letter F to navigate through the form fields. The first thing you will land on is the Gist description text box.

      -

      Jamie: What should I put in the description? Is this like a commit message?

      -

      Alex: It is more like the title of your sticky note. You want to be brief but descriptive. For example, you might type, NVDA configuration for GitHub web navigation.

      -

      Jamie: Okay, so I type my description, and then I press Tab to move to the next field?

      -

      Alex: Yes. The next field is the Filename text box. And this part is actually really important. You do not just want to type a name, you need to include the file extension. So instead of just typing nvda config, you should type nvda config dot txt. Or if it is a Python script, script dot py.

      -

      Jamie: Why is the extension so important?

      -

      Alex: Because GitHub uses that extension to determine how to format the text. If you type dot py, GitHub automatically applies Python syntax highlighting. If you type dot md, it knows to treat it as a Markdown file. It makes reading the code much easier for anyone who comes across it.

      -

      Jamie: Oh, that is incredibly smart. I wish I had known that when I started. I used to just leave the filename blank and wonder why my code looked like a giant wall of plain text.

      -

      Alex: It is a very common mistake! So, after you enter your filename, you press Tab again to move into the main content text box. This is where you actually paste or type your code.

      -

      Jamie: And if I am sharing an error log from my terminal, I just copy it from my terminal window and paste it right into that text box.

      -

      Alex: Exactly. Once your content is in there, you have a choice to make about visibility. If you Tab past the content area, you will reach the visibility options. You can choose either Create secret gist or Create public gist.

      -

      Jamie: Let us talk about those visibility options, because I remember being very confused by the word secret. Secret means private, right? Only I can see it?

      -

      Alex: That is a massive misconception, and I am so glad you asked. No. Secret does not mean private.

      -

      Jamie: Okay, warning bells are going off in my head. Please explain.

      -

      Alex: A public Gist is completely open. It appears on your public GitHub profile, it shows up in GitHub search results, and it gets indexed by search engines like Google. Anyone can find it, view it, and leave comments on it.

      -

      Jamie: Like a public post on a message board.

      -

      Alex: Exactly. A secret Gist, on the other hand, is hidden from search engines. It does not appear on your GitHub profile, and it will not show up if someone searches GitHub for keywords. However, anyone who has the exact URL can view it.

      -

      Jamie: So it is like having an unlisted phone number. Or an unlisted video on YouTube. You will not find it in the phone book, but if I hand you a slip of paper with the number on it, you can call it. It is not locked behind a password.

      -

      Alex: That is the perfect way to understand it. Because it is not locked behind a password or tied to user permissions, you must never put sensitive data in a Gist. Not even a secret one.

      -

      Jamie: So no passwords, no API keys, no personal user data.

      -

      Alex: Never. If you need to share proprietary code or secure credentials, you should use a private GitHub repository with strict access controls, or a dedicated secure password manager. If you accidentally paste an API key into a Gist, you need to delete that Gist immediately and go revoke that key with whatever service issued it.

      -

      Jamie: That is really good to know. So if secret Gists are not truly secure, what is the point of them? When would I use one?

      -

      Alex: They are great for sharing things you just do not want cluttering up your public profile. If you and I are troubleshooting a bug, and I want to send you a massive, messy error log, I will make it a secret Gist. I send you the link in our chat, you read it, we fix the bug. The log does not need to be searchable by the whole internet, but I also do not need military grade security for it.

      -

      Jamie: Okay, so let us go back to our form. I have my description, my filename, my code, and I choose Create public gist. I activate that button, and then what happens?

      -

      Alex: GitHub saves the Gist and loads a new page. This page has a unique URL in your browser address bar. It will look something like gist dot github dot com slash your username slash a long string of random letters and numbers. That URL is what you share with people.

      -

      Jamie: What if I need to share two files? Let us say I have a script, but I also have a small configuration file that goes with it. Do I have to make two separate Gists?

      -

      Alex: You do not. You can absolutely add multiple files to a single Gist. When you are on the creation page, right after the main content text box, there is a button called Add file. If you activate that button, it generates a new filename field and a new content text box right below your first one.

      -

      Jamie: Oh, that is clever! So I could share my HTML file, my CSS file, and my JavaScript file all in one single link.

      -

      Alex: Exactly. It keeps related snippets bundled together perfectly.

      -

      Jamie: Now, Alex, you know I am a huge fan of the command line. Doing all of this in the browser sounds fine, but switching windows, navigating form fields, pasting things in. Is there a way to create a Gist directly from my terminal?

      -

      Alex: There is, and it is incredibly fast. If you have the GitHub CLI installed, which is the command line interface we talked about in a previous episode, you can use the command g h space gist space create.

      -

      Jamie: G h gist create. How does that work in practice?

      -

      Alex: Let us say you have a file on your computer called notes dot txt. In your terminal, you just type g h space gist space create space notes dot txt. You press Enter, and the CLI uploads the file to GitHub and prints the brand new Gist URL right there in your terminal.

      -

      Jamie: That is amazing. I do not even have to open my browser. Does it make it public or secret by default?

      -

      Alex: By default, the CLI creates a secret Gist. If you want to make it public, you just add a flag to your command. You would type g h space gist space create space notes dot txt space dash dash public.

      -

      Jamie: I love that. That saves so many steps.

      -

      Alex: So, earlier we called a Gist a version controlled sticky note. Let us talk about what that actually means under the hood.

      -

      Jamie: Right, because what happens if I create my Gist, share the link, and then realize I made a typo in my code? Can I fix it?

      -

      Alex: You can. When you navigate to the page for your Gist, there is an Edit button near the top of the main content area. If you activate that, it opens the form fields back up. You can fix your typo, and then activate the Update button.

      -

      Jamie: Does it change the URL when I update it?

      -

      Alex: No, the URL stays exactly the same, which is great because any links you have already shared will still work. But here is the really cool part. Every single Gist is actually a tiny, fully functional Git repository behind the scenes.

      -

      Jamie: Wait, really? I thought we just said it was not a repository.

      -

      Alex: It is not a full GitHub project repository with issues and actions. But the underlying technology storing your file is Git. That means every time you edit your Gist, Git records a commit. If you navigate to your Gist page, you will find a link called Revisions. If you open that, you can read the entire history of changes made to that file, just like a commit history.

      -

      Jamie: That blows my mind a little bit. If it is a real Git repository, does that mean I can clone it to my computer?

      -

      Alex: Yes, you can! Every Gist page has a clone URL. You can open your terminal, type git clone, and paste that URL. It will download the Gist to your local machine as a folder. You can open it in your code editor, make changes, type git commit, and type git push to send the changes back to GitHub.

      -

      Jamie: That is wild. I had no idea they were that powerful. So if it is a Git repo, can I fork someone else's Gist? Like, if I find a really cool script that someone else wrote, but I want to customize it for my own workflow?

      -

      Alex: Absolutely. Forking is a fundamental concept in open source. To fork means to create a personal copy of someone else's project under your own account. If you are reading a Gist that belongs to another developer, you can navigate to the Fork button and activate it. GitHub instantly creates a duplicate of that Gist in your account.

      -

      Jamie: So it is like taking a recipe card from a friend's kitchen, copying it onto a blank card, and putting it in my own recipe box. Now I can cross out ingredients and add my own notes without messing up their original recipe.

      -

      Alex: That is a wonderful analogy. And because it is connected through Git, your forked copy will always link back to the original author, so they get credit for the initial work.

      -

      Jamie: What if I do not want to copy it, I just want to bookmark it so I can find it later?

      -

      Alex: For that, you use the Star feature. Starring a Gist is exactly like bookmarking it. There is a Star button right next to the Fork button. When you activate it, that Gist is added to your starred list.

      -

      Jamie: How do I find my list of starred Gists, or even just a list of all the Gists I have created myself?

      -

      Alex: You navigate to gist dot github dot com slash your username. That is your personal Gist dashboard. It lists all of your public Gists, your secret Gists, and there is a navigation tab to view the ones you have starred.

      -

      Jamie: What is the screen reader experience like on that dashboard? If I have twenty different Gists, how do I find the one I am looking for?

      -

      Alex: GitHub structures that page very well. Each Gist in your list is marked up as a level two heading, and the heading text is the description you provided when you created it.

      -

      Jamie: Oh, perfect. So I can just press the number 2, or the letter H, to jump from heading to heading until I hear the description I want.

      -

      Alex: Exactly. And right below each heading, you will find links to Edit, Delete, or Star that specific Gist.

      -

      Jamie: You mentioned deleting. If I delete a Gist, is it gone forever?

      -

      Alex: Yes. Deletion is permanent. To do it, you navigate to the Gist, activate the Edit button, and then look for the Delete button. GitHub will ask you to confirm, and once you do, it is removed entirely. But keep in mind, if someone else has already forked your Gist, their forked copy will not be deleted. They own their copy.

      -

      Jamie: Let us talk about comments. You mentioned earlier that people can leave comments on public Gists. How does that work?

      -

      Alex: It works beautifully for collaboration. Let us say you write a script to automate a task, and you publish it as a Gist. I find it, but I notice a small bug. I can scroll to the bottom of your Gist page, press the letter F to find the comment text box, and type out a message. I can even use Markdown to format code blocks in my comment. Then I press Control plus Enter to submit it.

      -

      Jamie: And I get a notification that you commented?

      -

      Alex: Yes, you will be notified. It turns the Gist into a mini discussion forum. It is incredibly common to see popular Gists with long comment threads where developers are suggesting improvements or sharing how they adapted the code for different operating systems.

      -

      Jamie: Speaking of popular Gists, is there a way to browse what other people are sharing? Like a trending page?

      -

      Alex: There is. You can navigate to gist dot github dot com slash discover. The Discover page shows you a feed of public Gists that are currently popular. It is a fantastic place to find useful utilities, learn new coding techniques, and see how other developers structure their configuration files. You can even filter the Discover page by programming language.

      -

      Jamie: Okay, there is one more concept from the checklist we need to cover. Embedding a Gist. What does it mean to embed a Gist, and why would I want to do it?

      -

      Alex: To embed means to place the content of your Gist directly inside another webpage, like your personal blog or a documentation site.

      -

      Jamie: Why wouldn't I just copy and paste the code straight into my blog post?

      -

      Alex: You could, but then your code is static. If you find a bug in your code a week later, you have to go log into your blog, find the post, and edit the text. If you embed a Gist instead, you only ever have to update the code on GitHub. The moment you update the Gist, your blog automatically displays the new, corrected code. Plus, GitHub provides all the beautiful syntax highlighting automatically.

      -

      Jamie: Oh, that makes so much sense. It is like hanging a picture frame on the wall of your blog. The frame stays in the same place, but you can swap out the painting inside it anytime you want, just by updating GitHub.

      -

      Alex: Exactly. To do this, you navigate to your Gist page. Near the top, there is a section called Embed. It provides a small snippet of HTML code that looks like a script tag. You just copy that script tag and paste it into the HTML of your blog post.

      -

      Jamie: How does an embedded Gist behave for someone using a screen reader who is reading my blog?

      -

      Alex: That is a great accessibility question. Technically, the embed script generates an HTML iframe. So when a screen reader user lands on it, they will hear the word frame, followed by the title of the Gist. They can then navigate into the frame to read the code line by line, just like they would on GitHub. It is a very seamless reading experience.

      -

      Jamie: This has been incredibly helpful. I feel like I finally understand where Gists fit into the ecosystem. They are not just plain text files, and they are not full repositories. They are the perfect middle ground for sharing.

      -

      Alex: They really are. So, let us recap our main takeaways for today. First, use a Gist when you want to share a lightweight code snippet, a configuration file, or an error log without the overhead of a full repository.

      -

      Jamie: Second, secret Gists are not strictly private. They are unlisted. Anyone with the link can view them, so never ever put passwords or API keys in a Gist.

      -

      Alex: Third, every Gist is a Git repository under the hood. That means you get version history, and you can clone, fork, and edit them just like a normal project.

      -

      Jamie: And fourth, you can create them incredibly fast straight from your terminal using the command g h space gist space create.

      -

      Alex: Perfect summary. That wraps up episode twenty three. In our next episode, we are going to dive into GitHub Pages, which allows you to host a static website directly from a repository for free. It is one of the most exciting features for showcasing your work. Until then, keep practicing, and happy coding.

      +

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

      +
      +

      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 23. Next in the series is episode 24, where we keep building the same contributor muscles.

      - +

      Episode 24: GitHub Discussions

      Forum-style conversations, Q&A, polls, and navigation with screen readers.

      -

      Based on: Appendix G: GitHub Discussions

      - - -

      Download Episode 24 (MP3)

      +

      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 episode twenty four of Gitt Going with GitHub, the audio learning series designed specifically for blind and low vision developers who are navigating the world of open source collaboration. I am your host, Alex.

      -

      Jamie: And I am your cohost, Jamie! Today, we are diving into a feature that I honestly wish I understood two years ago when I first started my GitHub journey. We are talking all about GitHub Discussions.

      -

      Alex: It is a fantastic topic, Jamie, and one that can save new open source contributors a lot of frustration. In this episode, we are going to cover what Discussions are, how they differ from Issues, the different categories of conversations you will find, and how to effectively navigate, create, and participate in these discussions using a screen reader. We will also talk about polls, marking answers, and when a discussion should actually become an issue.

      -

      Jamie: Before we jump into the deep end, let us do a quick refresher on our prerequisites. To get the most out of today's episode, it helps to be familiar with a few core GitHub concepts we covered earlier in the workshop. First is a repository, which is simply the central storage location or folder where a project's code and files live on the internet.

      -

      Alex: Correct. You also need to know about issues. An issue is essentially a tracking ticket. It is where you report bugs, which are errors in the code, or request specific new features. Issues are highly structured and action oriented.

      -

      Jamie: Right. And finally, we have talked about pull requests. So a pull request, and I love that name because you are literally requesting that someone pull your changes into their project, is the actual mechanism you use when you have written new code and you want the maintainers to merge it into the main repository.

      -

      Alex: Perfectly summarized. So, we have repositories for storage, issues for tracking tasks, and pull requests for merging code. But what happens when you just want to ask a question? What happens when you want to brainstorm an idea, or the project maintainer wants to announce a new version? That is where GitHub Discussions comes in.

      -

      Jamie: So Alex, let us start with the most basic question. What exactly is a GitHub Discussion?

      -

      Alex: At its core, GitHub Discussions is a built in community forum for a repository or an organization. It is where open ended conversations live. Think of it as a dedicated space for questions, ideas, announcements, and community support. It is completely separate from the action oriented world of issues and pull requests.

      -

      Jamie: I remember when I first started using GitHub, I did not even know Discussions existed. I ran into a problem where I could not figure out how to configure a project I had downloaded. So, I navigated to the Issues tab, activated the New Issue button, and asked my question there. About ten minutes later, a bot automatically closed my issue and labeled it as invalid. I felt terrible! I thought I had broken some unspoken rule.

      -

      Alex: That is such a common experience, Jamie. And you did break an unspoken rule, but it is one that nobody explains to beginners! Not every conversation belongs in an issue. Issues are for actionable work. When you open an issue, it signals to the maintainers that there is a task to be done. It might trigger automated testing workflows, send email alerts to dozens of contributors, and inflate the project's to do list.

      -

      Jamie: Wow, I had no idea I was setting off alarms just by asking for help.

      -

      Alex: Exactly. Let us use a real world analogy. Think of a restaurant. Issues are the ticket line in the kitchen. When a ticket comes in, the cooks have to take action. They have to chop vegetables, cook the meal, plate it, and send it out. If you walk into the kitchen and hand the chef a ticket that just says, what is your favorite vegetable, you are going to disrupt the entire workflow.

      -

      Jamie: That makes so much sense. So where do I ask about their favorite vegetable?

      -

      Alex: You ask in the dining room! And that is what GitHub Discussions is. It is the dining room of the repository. It is a space designed for people to sit down, chat, ask what is on the menu, and share their experiences without interrupting the cooks in the kitchen.

      -

      Jamie: I love that analogy. So to break it down, we should use issues when we find a bug, when we want to request a specific feature, or when there is actionable work that needs to be tracked, assigned to someone, and eventually closed.

      -

      Alex: Exactly right. And on the flip side, we use Discussions when we have a question about how something works, when we want to brainstorm ideas before we file a formal feature request, or when we just want community input on a topic that might not have one single right answer.

      -

      Jamie: Okay, so if I am in a repository and I want to visit the dining room, how do I find these discussions?

      -

      Alex: Navigating to Discussions is straightforward, but there is a catch. Discussions is an opt in feature. The repository maintainer has to actively enable it in their settings. So, not every repository you visit will have a Discussions tab.

      -

      Jamie: Good to know. But assuming they do have it enabled, how do we get there with a screen reader?

      -

      Alex: When you navigate to a repository page, you will find a main navigation tab list near the top. This tab list contains links for Code, Issues, Pull Requests, Actions, Projects, and Discussions. If you are using standard screen reader commands, you can press the letter T to navigate through tab items, or simply press the letter K to navigate through links until you hear Discussions. Then, just press Enter to open it.

      -

      Jamie: And what about organization level discussions? I have heard that is a thing now too.

      -

      Alex: Yes, it is! Let us define what an organization is first. On GitHub, an organization is a shared account where businesses or large open source communities can manage multiple repositories at once. Some large organizations enable Discussions at the organization level, completely separate from any specific repository.

      -

      Jamie: Why would they do that?

      -

      Alex: Think of the organization level discussion as the town square, while the repository discussion is a specific building. The town square is for organization wide announcements, community introductions, cross project feature brainstorming, and community spotlights. You find them by navigating to the organization's main page and looking for the Discussions tab there.

      -

      Jamie: Okay, so I have successfully navigated to the Discussions tab on a repository. What am I going to hear as I read down the page? Is it just a giant list of random posts?

      -

      Alex: Not at all. The Discussions home page is highly organized into categories. When you land on the page, the main content area lists the most recent or popular discussions, but they are grouped by these categories. Each category is a section with its own heading.

      -

      Jamie: What kind of categories are we talking about?

      -

      Alex: GitHub provides a few default categories that most repositories use. First is General, which is for exactly what it sounds like, everything that does not fit anywhere else. Second is Q and A, which stands for Questions and Answers. This is for support questions. Third is Ideas, which is for feature brainstorming. Fourth is Show and Tell, where community members can show off projects they built using the repository's code. And finally, Announcements, which is usually restricted so only maintainers can post things like new release details or breaking changes.

      -

      Jamie: That sounds like the channels in a Slack or Discord server. You have your general chat, your help channel, your announcements channel. It keeps things tidy.

      -

      Alex: That is a perfect comparison. To navigate these categories with a screen reader, you can rely heavily on your heading navigation. If you press the number 3 on your keyboard, you will jump directly to the category headings. Once you are under a category heading, you can press the letter K to navigate through the discussion titles within that category, because those titles are links. When you find one that sounds interesting, press Enter to open it.

      -

      Jamie: Is there a way to see all the categories at once?

      -

      Alex: Yes. There is a side panel, which might be on the left or the right depending on your browser width, that shows a list of all categories along with item counts. It also has a section for pinned announcements at the top. This is a great place to start if you want to filter the view to only show discussions from a specific category.

      -

      Jamie: Alright, let us say I have searched through the existing discussions, and I cannot find the answer to my question. By the way, how do I search?

      -

      Alex: Great question. You should always search before posting! You can use the search bar at the top of the Discussions page. Or, if you are using GitHub's global search from anywhere on the site, you can type repo colon owner slash name, space, in colon discussions, followed by your search terms.

      -

      Jamie: Okay, so I have searched, and nobody has asked my question yet. I need to create a new discussion. How do I do that?

      -

      Alex: From the main Discussions tab, you want to navigate to the button labeled New discussion and activate it by pressing Enter.

      -

      Jamie: Okay, that sounds like a lot of steps. I have to find the right tab, search, find a button, pick categories. It feels a bit intimidating for someone just trying to ask a question.

      -

      Alex: It does! But here is the thing, Jamie. You have already done most of this on day one when we learned about creating issues. It is the exact same workflow, just with a different label at the top. You are going to use the exact same text editor, the exact same markdown formatting, and the exact same keyboard shortcuts.

      -

      Jamie: Oh, well that is a relief. So what happens after I activate the New discussion button?

      -

      Alex: The first thing you have to do is select a category.

      +

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

      +
      +

      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 24. Next in the series is episode 25, where we keep building the same contributor muscles.

      - +

      Episode 25: Releases, Tags, and Insights

      Semantic versioning, GitHub Releases, and repository analytics.

      -

      Based on: Appendix H: Releases, Tags, and Insights

      - - -

      Download Episode 25 (MP3)

      +

      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 to Gitt Going with GitHub. I am Alex, and this is episode 25 of our audio series for blind and low-vision developers. Today, we are talking about Releases, Tags, and Repository Insights.

      -

      Jamie: I am Jamie, and I am so excited for this one. Up until now, we have spent a lot of time talking about how to get your code into a project. We have covered making commits, opening pull requests, and getting those pull requests merged. But today is about what happens next. How does that merged code actually get to the people who use the software?

      -

      Alex: Exactly. And as a prerequisite, if you are fuzzy on the pull request workflow, you might want to revisit our previous episodes on creating and merging pull requests, because today builds right on top of that foundation. Today, we will explore how maintainers package up a bunch of merged pull requests into an official version, and how you can explore a repository to understand how active and healthy it is before you even decide to contribute.

      -

      Jamie: I remember when I first started learning GitHub about two years ago. I would get my pull request merged, and I would immediately run over to my terminal, update the software I was using, and my new feature would not be there. I was so confused. I thought merging meant it was instantly available to the world.

      -

      Alex: That is a very common misconception. When your pull request gets merged, it just becomes part of the code on the default branch. But most people who use the software do not download the raw, bleeding-edge default branch every day. They wait for an official release.

      -

      Jamie: Right. And that is exactly what we are going to demystify today. We will cover Git tags, semantic versioning, creating GitHub releases, and then we will switch gears to talk about the Insights tab, which is basically the heartbeat of a repository.

      -

      Alex: Let us dive right in with the fundamental building block of a release. Before we can talk about GitHub releases, we have to talk about Git tags. Jamie, how would you describe a branch compared to a tag?

      -

      Jamie: Well, a branch is a movable pointer. We have talked about this before. When you add a new commit to a branch, the branch pointer moves forward to include that new commit. It is always pointing to the latest work. But a tag is entirely different. A tag is a fixed pointer to one single, specific commit. It never moves.

      -

      Alex: That is spot on. I like to use the analogy of a bookmark in a really long, constantly growing book. The author keeps adding new pages to the end of the book. A branch is like a bookmark that you always keep moving to the very last page you read. But a Git tag is a bookmark you glue onto page 100, and you write chapter one on it. No matter how many more pages the author writes, that bookmark will always point exactly to page 100.

      -

      Jamie: I love that. So when a project reaches a stable point, the maintainer glues a bookmark onto that exact commit and names it something like version 1 point 0. That way, anyone can jump back to that exact state of the code at any time.

      -

      Alex: Precisely. Now, within Git, there are two types of tags you can create. There are lightweight tags, and there are annotated tags.

      -

      Jamie: I know the difference here! A lightweight tag is literally just a name attached to a commit. It is like taking a blank sticky note, writing version 1 point 0 on it, and slapping it on the page. It does not store any extra information. But an annotated tag is much richer.

      -

      Alex: Yes, an annotated tag is stored as a full object in the Git database. Returning to our analogy, an annotated tag is like a formal library index card. It includes the tag name, but it also records the name and email of the person who created the tag, the date it was created, and a tagging message. It can even be cryptographically signed. If you are tagging a public release of software, you almost always want to use an annotated tag.

      -

      Jamie: So we have this tag, and we are going to name it with a version number. But version numbers can be really confusing when you are new. You see things like version 2 point 1 point 4. What do all those numbers actually mean?

      -

      Alex: Most open source projects use a system called Semantic Versioning, often shortened to semver. In semantic versioning, the number is broken into three parts separated by periods. Major, minor, and patch. So in version 2 point 1 point 4, the major version is 2, the minor version is 1, and the patch version is 4.

      -

      Jamie: Okay, so how do I know when to change which number? Let us say I am the maintainer. When do I bump the major, minor, or patch version?

      -

      Alex: Let us use an analogy of a car model to make this concrete. The last number, the patch version, is for backward-compatible bug fixes. If you fix a typo in the code, or resolve a crash without changing how the software is used, you bump the patch number. In our car analogy, this is like fixing a flat tire or replacing a faulty windshield wiper. The car still drives exactly the same way. The user does not have to learn anything new. You would go from version 2 point 1 point 4 to version 2 point 1 point 5.

      -

      Jamie: Got it. Patch means bug fix. What about the middle number, the minor version?

      -

      Alex: You bump the minor version when you add new features, but they are backward-compatible. This means existing users can upgrade without breaking their current setup. In the car analogy, bumping the minor version is like adding a brand new Bluetooth stereo system or heated seats. You added new functionality, but the steering wheel and the gas pedal are exactly where they have always been. The driver can just get in and drive. If you add a new command to your software, you bump the minor version. You would go from version 2 point 1 point 4 to version 2 point 2 point 0. Notice that when you bump the minor version, the patch number resets to zero.

      -

      Jamie: Okay, that makes sense. So that leaves the first number, the major version. I am guessing this is the big one.

      -

      Alex: It is. You bump the major version when you make breaking changes. This means you have changed the existing behavior in a way that is incompatible with previous versions. Users might need to rewrite their own code or change their configurations to use the new version. In our car analogy, a major version bump is like replacing the gas engine with a manual transmission electric engine, and moving the steering wheel to the back seat.

      -

      Jamie: Oh wow, yeah, the driver is going to need a new manual for that.

      -

      Alex: Exactly. If someone tries to drive it exactly like the old car, they are going to crash. So you signal that danger by bumping the major version. You would go from version 2 point 2 point 0 all the way to version 3 point 0 point 0. The minor and patch numbers reset to zero.

      -

      Jamie: That is a really helpful way to think about it. Patch is a fix, minor is a safe new feature, and major means read the instructions because things have changed.

      -

      Alex: So now we understand Git tags and semantic versioning. But a Git tag is just a raw marker in your code history. GitHub takes that concept and builds a whole feature around it called a GitHub Release.

      -

      Jamie: This is an important distinction. A tag is a Git concept. It exists on your local machine and in the terminal. But a Release is a GitHub concept. It only exists on the GitHub platform.

      -

      Alex: Exactly. If a tag is the bookmark glued to a specific page, a GitHub Release is the fancy gift box you hand to your users. Every GitHub Release is backed by a Git tag, but the Release adds extra things. It adds formatted release notes explaining what changed, and it can include downloadable release assets.

      -

      Jamie: Let us talk about those release notes first. When I navigate to a repository on GitHub, how do I actually find the releases with my screen reader?

      -

      Alex: From any repository home page, you can use your screen reader's heading navigation. Press the letter H, or specifically the number 3, to navigate through the level 3 headings in the right sidebar. You will find a heading called Releases. Right below that heading, there is usually a link to the latest release, like version 2 point 1 point 0. You can activate that link to go straight to it. Or, you can navigate slightly further down to a link that says something like Five Releases, which will take you to a list of all historical releases.

      -

      Jamie: And when I open that releases page, what is the structure like? How do I read it?

      -

      Alex: The main releases page lists everything in reverse chronological order. Each release is enclosed in its own section. You can press the number 2 to jump between the major section headings, and the number 3 to jump to individual release titles. Once you are on a release title, you can use your down arrow to read the release notes.

      -

      Jamie: I love reading good release notes. A well-maintained project will categorize the changes. They will have a heading for Breaking Changes, a heading for New Features, and a heading for Bug Fixes. It makes it so easy to skim. And usually, each bullet point mentions the pull request number and the username of the person who contributed it.

      -

      Alex: That is one of the best feelings as a new contributor. You open the release notes for a major project, and right there under Bug Fixes, you hear your own username read aloud. It is tangible proof that your code is out in the world.

      -

      Jamie: At the bottom of the release notes, there is usually a section for downloading release assets. What exactly are release assets?

      -

      Alex: Assets are the actual files the user needs. GitHub automatically generates two source code archives for every release, a zip file and a tar dot gz file. This is just the raw code at that specific tag. But maintainers can also attach custom assets. If it is a desktop application, the assets might be the compiled executable file for Windows, and the dot app file for Mac. You can use the letter K to navigate through the links in the release section to find the asset downloads.

      -

      Jamie: Okay, so that is how we consume releases. But what if I am a maintainer, or I am volunteering on an open source project, and they ask me to create the new release? That sounds like a lot of pressure. Do I have to manually write out every single thing that changed?

      -

      Alex: You used to have to do that, and it was tedious. But GitHub has made this incredibly smooth now. Let us walk through creating a release from the GitHub web interface. First, you navigate to the main releases page, and you activate the link called Draft a new release.

      -

      Jamie: OK that sounds like a lot of steps, but I am guessing it is mostly a form to fill out?

      -

      Alex: It is! You are just filling out a web form. The first thing you do is choose a tag. You can type in a brand new version number, like v 2 point 1 point 0. If the tag does not exist yet, GitHub will automatically create it for you when you publish. Next, you choose the target branch, which is usually your main branch. Then you give the release a title, which is often just the version number again.

      -

      Jamie: And then comes the release notes text area. This is where the magic happens, right?

      -

      Alex: Exactly. Right above the text area, there is a button called Generate release notes. When you activate this, GitHub automatically looks at every single pull request that has been merged since the previous release. It grabs the titles, the author names, and the links, and it formats them perfectly into markdown inside the text area. It is like having a personal assistant summarize a month's worth of meeting notes in two seconds.

      -

      Jamie: Oh that is clever! I wish I had known that when I started. I definitely spent hours manually copying and pasting pull request titles into a text document.

      -

      Alex: We have all been there. Once the notes are generated, you can manually edit them. You might want to group them into headings or add a friendly introductory paragraph. Then, you have the option to attach any binary files if you have them. Finally, you choose whether to publish it, or save it as a draft.

      -

      Jamie: Let us talk about drafts and pre-releases. There are checkboxes for those on the form. A draft release is just what it sounds like, right? It is saved, but only repository collaborators can see it. It is great for preparing the notes a few days before the actual launch.

      -

      Alex: Exactly. And a pre-release is slightly different. A pre-release is published and visible to the public, but it is not marked as the Latest release. When users visit the repository, GitHub will not automatically direct them to a pre-release.

      -

      Jamie: Why would you use a pre-release?

      -

      Alex: You use a pre-release for early testing versions. In semantic versioning, you might append a suffix, like version 2 point 1 point 0 dash alpha point 1, or dash beta point 2. It signals to users, hey, this is available to test, but it might still have bugs. Only adventurous users should download it.

      -

      Jamie: Before we move on from creating releases, I want to mention a massive shortcut for screen reader users who use VS Code. If you are using the Accessibility Agents extension we have talked about in previous episodes, you do not even need to navigate the web form to write your notes.

      -

      Alex: That is right. You can open the GitHub Copilot chat in VS Code, and type the command slash draft dash release, followed by the version number. The agent will analyze your repository, categorize all your merged pull requests into Features, Bug Fixes, and Dependencies, and output perfectly formatted markdown right in your chat window. You can just copy it and paste it wherever you need it.

      -

      Jamie: Alright, so releases tell us what a project has shipped. But what if I am evaluating a new repository, and I want to know if it is actually healthy? I want to know if the maintainers are active, if people are contributing, and if it is a welcoming place. How do I find that out?

      -

      Alex: That is where the Insights tab comes in. The Insights tab is a dedicated section of the repository that shows quantitative activity data. To get there, you navigate to the main repository tab bar by pressing the letter T, and then navigate through the tabs until you find the link called Insights.

      -

      Jamie: Now, I have to be honest here. As a screen reader user, the Insights tab used to be my least favorite place on GitHub. It is heavily visual. It is full of line charts, bar charts, and scatter plots that are rendered in HTML canvas elements. When my screen reader hits those, it just says graphic or image, and I get absolutely zero information.

      -

      Alex: That is a very fair critique, and it is a common frustration. But here is the secret to navigating the Insights tab with a screen reader. Almost every single visual chart on those pages has a fully accessible HTML data table located directly below it. The strategy is to completely ignore the canvas graphics. When the page loads, just press the letter T to jump straight to the data tables. All the exact same information is right there in text format.

      -

      Jamie: That is a lifesaver. Okay, so when I open the Insights tab, the left sidebar has a sub-navigation menu with several different views. The first one, which is the default landing page, is called Pulse. What is Pulse?

      -

      Alex: Pulse is exactly what it sounds like. It is the heartbeat of the project. It gives you a summary of all the activity over a specific time period, usually the last week or the last month. You will find headings for Merged pull requests, Open pull requests, and Closed issues. Under each heading is a plain text list of the actual work that happened, with links to the items.

      -

      Jamie: This is my go-to page when I am looking for an open source project to contribute to. If I look at the Pulse for the last month, and I find zero merged pull requests, and fifty open issues, that is a zombie project. The maintainer is gone. I am not going to waste my weekend writing a pull request that will never get reviewed.

      -

      Alex: That is exactly how you should use it. Conversely, if you see that ten pull requests were merged by five different authors, that tells you the project is alive, active, and welcoming to multiple contributors.

      -

      Jamie: What about the Contributors view? That is another link in the Insights sidebar.

      -

      Alex: The Contributors view shows who is building the project. Visually, it is a big timeline chart, but again, jump down to the table. The table lists every person who has contributed to the default branch. It shows their username, their total number of commits, and how many lines of code they have added and deleted. You can use your Tab key to navigate the column headers and sort the table.

      -

      Jamie: I remember the day my name finally appeared in one of those contributor tables. It was such a proud moment. And it is actually really useful because you can link directly to your section of the contributor page to prove your involvement in a project to potential employers.

      -

      Alex: Absolutely. Next in the sidebar is the Traffic view. Now, you can only access the Traffic view if you are a repository owner or a collaborator with push access. It shows you who is visiting the repository. It tracks total page views, how many times the repository has been cloned, and referring sites, which tells you if people are finding your project from Google, or Twitter, or a specific blog post.

      -

      Jamie: Why does traffic matter for developers? We are not marketing people.

      -

      Alex: It matters for documentation and community growth. The Traffic view has a table called Popular Content that shows exactly which files get the most views. If you see that a specific tutorial file in your repository is getting thousands of views a week, you know that file is critical. You should probably spend time making sure that specific tutorial is perfectly accessible and up to date, because it is the front door to your project.

      -

      Jamie: Let us talk about a view in the Insights tab that has major security implications. The Dependency graph.

      -

      Alex: The dependency graph is crucial. Modern software is rarely built from scratch. We rely on dozens, sometimes hundreds, of external libraries and packages. The dependency graph reads your configuration files and creates a list of everything your project relies on.

      -

      Jamie: I like to think of the dependency graph as a recipe's ingredient list. If I am baking a cake, the dependency graph lists the flour, the sugar, and the eggs. But why is it in the Insights tab?

      -

      Alex: Because it feeds one of GitHub's most important security features, called Dependabot. Let us stick with your recipe analogy. Imagine there is a national recall on the specific brand of flour you use because it is contaminated. Dependabot acts like a grocery store manager who constantly monitors recall lists. Because the manager has your exact ingredient list, your dependency graph, they can immediately tap you on the shoulder and say, hey, your flour is bad. Here is a safe brand to use instead.

      -

      Jamie: And Dependabot actually does more than just tap you on the shoulder. It will automatically open a pull request in your repository to update the vulnerable dependency to a safe version. All you have to do is review the pull request and merge it. It is incredible.

      -

      Alex: It really is. There is one more section in the Insights area we need to cover, and that is Community Standards. You can usually find this in the Insights sidebar, or sometimes linked directly from the main repository page in the right sidebar.

      -

      Jamie: The Community Standards page is essentially a checklist of community health files. It lists things like a README, a Code of Conduct, a Contributing guide, a License, and Issue templates. Next to each item is a simple status of either a checkmark or an X.

      -

      Alex: A fully green checklist signals a mature, well-maintained project. It means the maintainers have taken the time to set rules and provide instructions for newcomers.

      -

      Jamie: And here is a pro-tip for our listeners. If you are looking for an easy way to make your first contribution to an open source project, check their Community Standards page. If they are missing a Code of Conduct or a Contributing guide, those are fantastic good first issues. You can draft the text, open a pull request, and help them turn that X into a checkmark. Maintainers love that kind of help.

      -

      Alex: That is a brilliant suggestion. Now, before we wrap up, I want to offer one more alternative for our screen reader users. If you do not want to navigate the Insights tab in the web browser at all, the Accessibility Agents extension in VS Code has commands for this, too.

      -

      Jamie: Yes! You can open Copilot chat and type slash my dash stats. It will output a beautifully formatted text summary of your personal contributions across all your tracked repositories. It tells you how many pull requests you opened, how many reviews you completed, and how many commits you pushed.

      -

      Alex: And if you are working on a team, you can type slash team dash dashboard. It generates a text-based report of team-wide activity, showing who is reviewing code, what issues are open, and overall project health. It gives you the power of the Insights tab without ever leaving your code editor or fighting with a canvas graphic.

      -

      Jamie: We covered a huge amount of ground today. From gluing bookmarks onto pages, to ingredient lists, to checking the heartbeat of a project.

      -

      Alex: Let us summarize the key takeaways. First, a Git tag is a fixed, named pointer to a specific commit, while a GitHub Release wraps that tag with release notes and downloadable assets.

      -

      Jamie: Second, semantic versioning uses three numbers. Major, minor, and patch. Remember the car analogy. Patch is a bug fix like a new tire. Minor is a new feature like a stereo. And Major is a breaking change like an entirely new engine.

      -

      Alex: Third, when reading the Insights tab with a screen reader, remember to skip past the visual canvas charts by pressing the letter T, and use the accessible data tables located immediately below them to read the exact same information.

      -

      Jamie: And fourth, use the Pulse view to check a project's heartbeat before you contribute. Look for recently merged pull requests to ensure the maintainers are actually active and reviewing code.

      -

      Alex: That brings us to the end of episode 25. Now that we understand how releases and insights work, we are ready to take on larger responsibilities. In our next episode, we will be shifting gears to talk about repository management. We will cover protecting your main branch, setting up rulesets, and managing collaborator access.

      -

      Jamie: I cannot wait. Thanks for listening, everyone. Happy coding!

      -

      Alex: See you next time on Gitt Going with GitHub.

      +

      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: 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 I: GitHub Projects Deep Dive

      - - -

      Download Episode 26 (MP3)

      +

      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: Welcome back to Gitt Going with GitHub. I am Alex, and today we are diving into Episode 26, which is our GitHub Projects Deep Dive.

      -

      Jamie: Hello everyone, I am Jamie! I am very excited for this one. I know we touched on the basics of projects back in Episode 8, along with labels and milestones. But today we are going all in, right?

      -

      Alex: Exactly. Back in Episode 8, we covered the prerequisites. We learned how to attach a project to a single repository and how to find it. Today, we are looking at GitHub Projects version two as a complete project management system. We will cover the different layouts like tables and boards, how to create custom fields, tracking work across multiple repositories at once, and my absolute favorite part, built-in automations.

      -

      Jamie: Automations! That sounds amazing, but also a little intimidating. I remember when I first started learning GitHub about two years ago, just managing a single repository felt like a lot. Now we are talking about automating work across multiple repositories?

      -

      Alex: It does sound like a lot! But here is the thing, you have already done most of this on Day 1 of your journey. You already know how to open an issue, how to close a pull request, and how to assign a label. This is the exact same workflow, just with GitHub handling the heavy lifting of organizing it all for you.

      -

      Jamie: That is a relief. So, before we get into the how-to, you mentioned Projects version two. What happened to version one? And why do I sometimes see older forum posts talking about Projects Beta?

      -

      Alex: Great question. GitHub has two generations of project tooling. The current generation is officially called Projects version two, but you will just see it labeled as Projects everywhere on the platform today. The older version, Classic Projects, was basically just a simple Kanban board. It was like having a basic corkboard on your wall where you could pin up index cards. It was fine, but very limited.

      -

      Jamie: And let me guess, version two is the upgrade?

      -

      Alex: A massive upgrade. If Classic Projects was a simple corkboard, Projects version two is like a smart digital spreadsheet that updates itself. You can add custom fields, switch between different views, and pull in work from anywhere in your organization. When it was first being tested, it was called Projects Beta, but it is fully stable now and it is the default.

      -

      Jamie: So let us start at the very beginning. How do I actually create a new project?

      -

      Alex: You can create a project at two different levels. The repository level, which scopes the project to just one repository, or the organization level, which lets you share the project across all repositories in that organization.

      -

      Jamie: I usually work in an organization with a few different repositories for the frontend, backend, and documentation. So I would probably want an organization-level project, right?

      -

      Alex: Exactly. To do that, you navigate to your organization page. You will activate the tab called Projects. From there, you just tab to the button called New project and press Enter.

      -

      Jamie: Does it just give me a blank slate?

      -

      Alex: It opens a template menu first. You can use your arrow keys to browse through template cards, like a blank table, a blank board, or a feature release template. Once you press Enter on a template, you just type in a name for your project, tab to the Create project button, and you are in.

      -

      Jamie: Okay, so I have created my project. What does it actually feel like to navigate? You mentioned different layouts earlier.

      -

      Alex: Yes, there are three main layouts in Projects version two. The Table view, the Board view, and the Roadmap view. Every concept we talk about today revolves around these three views. Let us start with the Table view, because it is the default, and honestly, it is the most robust for screen reader users.

      -

      Jamie: Table view sounds like a spreadsheet.

      -

      Alex: That is the perfect analogy. The Table view is a massive spreadsheet-style grid. Each row represents a single item, which could be an issue or a pull request. And we should define a pull request again really quickly. I love that name because you are literally requesting that someone pull your code changes into their project.

      -

      Jamie: And so the rows are the issues or pull requests. What are the columns?

      -

      Alex: The columns are fields. Title, Status, Assignee, Labels, Priority, and any custom fields you create. The Table view is best for bulk editing, sorting, and seeing many items at once.

      -

      Jamie: How do I move around this giant spreadsheet with my screen reader?

      -

      Alex: You can press the letter T to jump straight to the table data region. From there, you use your Up and Down arrow keys to move between rows, and your Left and Right arrow keys to move between columns in that row.

      -

      Jamie: What does the screen reader actually announce when I am moving through the rows?

      -

      Alex: If you are arrowing down through the rows, your screen reader will read a summary of that row. It might say something like, Fix keyboard trap in modal dialog, Status In Progress, Assignee Alice, Priority High.

      -

      Jamie: That is really efficient. But what if I want to actually edit one of those cells, like change the priority?

      -

      Alex: If you are using NVDA, you will want to use Browse mode to read the cell content, which you toggle with NVDA plus Space. When you find a cell you want to edit, you press NVDA plus Space again to switch to Application mode, and then press Space or Enter to activate the editor for that cell. If you are using JAWS, you press Enter to switch to application mode in the table.

      -

      Jamie: Oh, I love a good keyboard shortcut. Are there any others for the Table view?

      -

      Alex: Yes! If you are focused on the Title cell of an issue, you can press F 2 to edit the title inline, without ever leaving the table. But the most important key is Enter. If you press Enter on any row, it opens the item detail panel in a right sidebar. You can tab through all the fields for that issue in one vertical list, make your changes, and then press Escape to close the panel and pop right back into your table.

      -

      Jamie: Okay, so Table view is our heavy duty spreadsheet. What is the Board view?

      -

      Alex: The Board view uses Kanban-style columns. Kanban is a project management framework that focuses on visualizing work. Think of it like having three physical baskets on your desk. One basket is labeled To Do, one is In Progress, and one is Done. Each issue is a piece of mail. As you work on an issue, you move it from one basket to the next.

      -

      Jamie: That makes sense for visualizing a workflow. But wait, visually moving cards between columns usually means drag-and-drop. Drag-and-drop is notoriously terrible for accessibility. How do we handle that?

      -

      Alex: You hit the nail on the head. Drag-and-drop is not keyboard accessible in this view. But you do not need to drag anything. Remember that right sidebar detail panel I just mentioned?

      -

      Jamie: Yes, the one you open by pressing Enter.

      -

      Alex: Exactly. To move a card to a different column, you just tab to the card, press Enter to open the detail panel, and navigate to the Status field. You activate the Status dropdown, select your new column like In Progress, and press Escape. The card instantly moves to the new column.

      -

      Jamie: Oh, that is clever! You are just updating the underlying data, and the visual board updates automatically to match it.

      -

      Alex: Precisely. The columns in Board view are just visual representations of a specific field, usually the Status field. Change the field, change the column.

      -

      Jamie: That brings us to the third layout, the Roadmap view. What is that?

      -

      Alex: The Roadmap view is a horizontal timeline. Items appear as blocks spanning across their start and due dates. It is heavily used by product managers for release planning, or communicating timelines to stakeholders. If we stick to our analogies, the Roadmap is like a train schedule. It shows you when things are supposed to depart and arrive.

      -

      Jamie: How accessible is a visual timeline like that?

      -

      Alex: To be completely transparent, the Roadmap view is chart-based. While there is some basic navigation, the underlying data is what matters. For screen reader users, I always recommend treating the Roadmap as a visual summary for sighted colleagues, while you use the Table view for all of your actual planning and editing. Any dates you set in the Table view will automatically populate the Roadmap chart.

      -

      Jamie: Okay, so we have our views. But a project is useless without actual work in it. How do I add my issues and pull requests to this project?

      -

      Alex: From any project view, you can navigate to the bottom of a table or column and activate the button called Add item. When you do that, a text field appears. If you type the number sign, also known as the hash symbol, it instantly triggers a search of your repository issues and pull requests. You just type a keyword or the issue number, arrow down to the one you want, and press Enter.

      -

      Jamie: And that pulls the issue out of the repository and into the project?

      -

      Alex: Not quite! It links the issue to the project. The issue still lives in its home repository. If someone comments on it in the repository, you will see those updates. The project is just a lens for viewing the work.

      -

      Jamie: What if I have an idea for a feature, but I am not ready to create a formal issue in the repository yet? Sometimes I just want to jot down a quick note during a meeting.

      -

      Alex: That is the perfect time to use a Draft Issue.

      -

      Jamie: A draft issue? I have never heard of that.

      -

      Alex: Draft issues are unique to Projects. They live only inside the project board and do not belong to any repository. It is exactly like scribbling an idea on a napkin before you write the official document. To make one, you activate the Add item button, but instead of typing a hash symbol, you just type your idea in plain text and press Enter.

      -

      Jamie: So it just creates a text row in my table?

      -

      Alex: Yes. And later, when you are ready to make it official, you can open that draft row, navigate to the button called Convert to issue, and select which repository it should live in. It instantly transforms into a real GitHub issue.

      -

      Jamie: I love that napkin analogy. Okay, earlier you mentioned custom fields. You said this is where Projects version two really shines. What kind of fields can we create?

      -

      Alex: You can add fields far beyond the GitHub defaults. There are five main types of custom fields. Text fields for free-form notes, Number fields for things like story points or estimates, Date fields for deadlines, Single select fields for dropdown menus, and Iteration fields.

      -

      Jamie: Let us talk about Single select fields. I assume that is for things like priority levels?

      -

      Alex: Exactly. Let us say you want to categorize bugs. In the Table view, you scroll all the way right to the last column header, which is a Plus button. You activate that, choose Single select, and name the field Priority. Then you type your options, like P 0, P 1, and P 2, pressing Enter after each one. You save it, and now every item in your project has a Priority dropdown.

      -

      Jamie: That is so much cleaner than creating a dozen different labels for every possible priority. What about that last field type you mentioned, the Iteration field? What is an iteration?

      -

      Alex: An iteration is a time-boxed cycle of work. Many software teams call these Sprints. You might work in two-week sprints, where the goal is to finish a specific set of tasks before the cycle ends.

      -

      Jamie: So how does the Iteration field handle that? Do I have to manually type in the dates for every single sprint?

      -

      Alex: Nope, GitHub handles the math. You create an Iteration field, tell it your sprints are two weeks long, and pick a start date. GitHub automatically generates the current sprint, the next sprint, and the ones after that. Then you just assign your issues to an iteration using that field, just like you would assign a priority.

      -

      Jamie: Okay, so if I have a massive project board with custom fields, priorities, and sprints, it is going to get really crowded. How do I find exactly what I need without reading through a hundred rows?

      -

      Alex: That is where Views and Filters come in. A view is a saved configuration of your layout, your filters, and your sorting. You can have many different view tabs at the top of your project.

      -

      Jamie: Like asking a librarian for exactly the books you need, and having them keep that specific stack on a desk for you?

      -

      Alex: Perfect analogy. Let us say you only want to see your own work. You can navigate to the filter bar and type a query. The syntax is very similar to standard GitHub search. You would type assignee colon, followed by the at symbol, and the word me. Assignee colon at me.

      -

      Jamie: Oh, I use that all the time in issue searches. Can I combine them? Like, show me only the bugs assigned to me that are currently in progress?

      -

      Alex: Absolutely. You would type assignee colon at me, space, status colon quote In Progress quote. You can also filter by custom fields, labels, or item types. For example, typing is colon issue will hide all the pull requests so you can just focus on issues.

      -

      Jamie: And if I get this filter perfectly tuned, I can save it as a View?

      -

      Alex: Yes. You navigate to the button called New view in the tab bar, set up your layout and filters, and it saves automatically. You can rename the tab to something like My Active Bugs. Every time you open the project, that tab is waiting for you.

      -

      Jamie: Alright, Alex, you promised we would talk about tracking work across multiple repositories. How does that work?

      -

      Alex: This is called a cross-repository project, and it is a game changer for open source maintainers or teams working on complex software. A single project can link to multiple repositories. It is like having a master control room that monitors several different factories at once.

      -

      Jamie: How do I set that up?

      -

      Alex: You navigate to the project overflow menu, which is labeled with three dots in the top right. You select Settings, then Manage access, and then Add repository. You can search for and link as many repositories as you need.

      -

      Jamie: But if I have issues from five different repositories in one table, how do I know where an issue came from?

      -

      Alex: You use the Repository field! In your Table view, you can make the Repository column visible. Then, you can filter by it or even group by it. You can tell the table to visually group all the rows by repository, so you have a section for the frontend repository, a section for the backend, and so on.

      -

      Jamie: Okay, we have reached the part I have been waiting for. Automations. You said I could hire a virtual assistant to move my papers around.

      -

      Alex: I did! Projects version two has native automation rules built right in. You do not need to write any complex scripts. You find them by opening that same project overflow menu and selecting Workflows.

      -

      Jamie: What kind of workflows are we talking about?

      -

      Alex: The built-in ones handle the repetitive status updates. For example, there is a workflow called Item closed. If you enable it, anytime you close an issue or merge a pull request in your repository, GitHub automatically finds that item in your project and changes its status field to Done.

      -

      Jamie: That is amazing. I always forget to update my project boards after I merge code. What else can it do?

      -

      Alex: The most powerful built-in workflow is called Auto-add to project. This is a lifesaver for cross-repository projects. Let us say you are tracking accessibility bugs across your entire organization.

      -

      Jamie: Okay, so I have a project board set up.

      -

      Alex: Right. You go to Workflows, select Auto-add to project, and turn it on. You configure a filter, like label colon accessibility. From that moment on, anytime anyone files a new issue with the label accessibility in any of your linked repositories, GitHub automatically adds it to your project board. No manual triage required.

      -

      Jamie: Wow. That literally does save hours of work. I wish I had known that when I started managing my first open source repository. Does it integrate with GitHub Actions for even more complex stuff?

      -

      Alex: It does. Projects version two has a full GraphQL API. Using GitHub Actions, which we cover deeply in the advanced appendices, you can do things like automatically assign issues to specific people based on which repository they came from, or automatically set due dates. The possibilities are endless.

      -

      Jamie: Before we wrap up, I want to ask about our favorite coding companion. Does GitHub Copilot know anything about our project boards?

      -

      Alex: It absolutely does, through Accessibility Agents. There is a specific command you can use in VS Code Copilot Chat called slash project dash status.

      -

      Jamie: Slash project dash status. What happens when I type that?

      -

      Alex: You type slash project dash status followed by the repository name. Copilot will reach out to GitHub and give you a live text overview of the project board directly in your VS Code editor, without you ever needing to open a browser.

      -

      Jamie: What kind of information does it give me?

      -

      Alex: It gives you a breakdown of how many items are in each column, who they are assigned to, and their average age. It is incredibly smart. It will specifically flag attention items, like issues that are blocked, or stale items that have been sitting in the In Progress column for more than seven days with no activity.

      -

      Jamie: That sounds perfect for checking what I need to work on on a Monday morning, or preparing for a standup meeting.

      -

      Alex: Exactly. It keeps you in the flow of your coding environment while still staying on top of project management.

      -

      Jamie: Alex, this has been an incredible deep dive. I feel like I am ready to upgrade my entire workflow from Classic to version two.

      -

      Alex: I am glad to hear it! Let us summarize with a few concrete takeaways for our listeners. First, remember that the Table view is your best friend. It is a highly accessible, spreadsheet-style interface where you can use keys like T to jump to the table, and Enter to open the item details panel to edit fields quickly.

      -

      Jamie: Second takeaway: you do not need to use drag-and-drop on a Kanban board! If you are in the Board view, just press Enter on a card and change its Status field in the sidebar to move it to a different column.

      -

      Alex: Third, take advantage of Custom Fields. Do not limit yourself to standard labels. Use single-select fields for priorities, number fields for estimates, and iteration fields to manage your two-week sprints.

      -

      Jamie: And fourth, turn on those Workflows! Set up the Auto-add workflow to automatically pull issues into your project based on their labels, and use the Item closed workflow to automatically mark things as Done. Let the robots do the busy work.

      -

      Alex: Perfectly said. That wraps up Episode 26. In our next episode, we are shifting gears slightly to talk about something crucial for every open source contributor: Code Reviews and Pull Request Etiquette. We will learn how to leave accessible review comments, how to request changes, and how to handle feedback on your own code.

      -

      Jamie: I definitely need that one. Thanks for listening, everyone! We will catch you in the next episode.

      -

      Alex: Keep coding, and keep collaborating. See you next time.

      +

      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.

      +
      +

      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.

      +

      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 1. Projects v2: What Changed. GitHub has two generations of project tooling. Put another way, the current generation - called Projects (v2) - is what you'll find on any repository or organization page today. It 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 2. Creating a Project becomes real: projects can be created at the organization level (shared across all repos in an org) or at the repository level (scoped to one repo).

      +
      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with Create from an Organization. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to your organization page (github.com/your-org). Then, select the Projects tab. After that, activate "New project" button. Finally, choose a template (blank table, blank board, feature release, etc.) or start empty. 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, give the project a name and select "Create project". The rhythm is simple: orient, act, verify, then continue.

      +

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

      +

      Alex: Start with Create from a Repository. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to any repository. Then, select the Projects tab. After that, activate "Link a project" or "New project". Finally, follow the same template/name flow. 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: That matters because of the next idea. Start with Learning Cards: Creating a Project. 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 "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. 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.

      +
      +

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

      +

      Alex: Here is the plain-English version of Table View. A spreadsheet-style grid where each row is an issue, PR, or draft item. Put another way, columns are fields (Title, Status, Assignee, Labels, Priority, custom fields you create).

      +

      Alex: This is where the talk moves from concept to action. This is where Screen reader output per row becomes real: "Fix keyboard trap in modal dialog Status: In Progress Assignee: alice Priority: High Labels: bug, accessibility".

      +

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

      +

      Alex: Keep the learner anchored in Board View. Each column represents a status value. This is the part to say slowly: Cards can be dragged between columns (or updated via keyboard by editing the Status field).

      +
      +

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

      +

      Alex: Start with Change a card's column without dragging. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, enter to open the card. Then, navigate to the Status field in the right panel. After that, activate the Status dropdown. Finally, select the new column value. The rhythm is simple: orient, act, verify, then continue.

      +

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

      +

      Alex: First, 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: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Roadmap View: Items appear as bars spanning their start/due dates. The next useful detail is this: Iterations and milestones can be visualized against real calendar time.

      +

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

      +

      Alex: The practical anchors are these. Add a Date custom field (e.g., "Start Date", "Due Date") or use a Milestone field. Items without dates appear in the ungrouped section.

      +
      +

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

      +

      Alex: Start with Learning Cards: The Three Layouts. 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. 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. 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.

      +

      Alex: That connects to another useful point. Keep the learner anchored in 4. Custom Fields. This is one of Projects v2's most powerful features. This is the part to say slowly: You can add fields beyond the GitHub defaults (Title, Assignee, Labels, Milestone, 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 Field Types. What should a learner take away from it?

      +

      Alex: The reason Field Types matters is that text: Free-form notes for things like acceptance criteria or design links. That gives the learner a simple foothold: number: Numeric values such as story points or estimates (for example, "Points: 3").

      +
      +

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

      +

      Alex: Start with Creating a Custom Field. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in Table view, scroll right to the + button at the end of the column header row. Then, activate the + button. After that, select a field type. Finally, name the field and configure options (for select fields, type each option, press Enter to add more). Think 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 Custom Field, what is the practical point?

      +

      Alex: First, confirm - the field appears as a new column. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Editing a Field Value on an Item. What should a learner take away from it?

      +

      Alex: Start with Editing a Field Value on an Item. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in Table view, navigate to the cell where the field intersects the row. Then, enter or Space to activate the editor. After that, type value (text/number) or select from dropdown (single select). Finally, enter or Tab to confirm. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Add an Existing Issue or PR. What should a learner take away from it?

      +

      Alex: This is where Add an Existing Issue or PR becomes real: the issue itself will now show which projects it belongs to in its sidebar. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, activate the "+ Add item" button at the bottom of a table/column. Then, type to trigger the issue/PR search. After that, type a keyword or issue number. Finally, select the item - 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: Before we leave Add an Existing Issue or PR, what is the practical point?

      +

      Alex: First, the issue/PR is now tracked in the project; it still lives in its repository. 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 Add a Draft Issue. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Add a Draft Issue. Draft issues live only inside the project (not in any repository) until you promote them. This is the part to say slowly: When to use drafts: Capturing ideas during planning before you're ready to commit them to a repo.

      +

      Alex: First, activate "+ Add item". Then, type the title directly (no ). After that, press Enter - a draft row appears. Finally, open the draft → "Convert to issue" button → select the repository. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Promote a Draft to an Issue. What should a learner take away from it?

      +

      Alex: Start with Promote a Draft to an Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the draft item (Enter on the row). Then, activate "Convert to issue" in the panel. After that, select the target repository from the dropdown. Finally, confirm - the draft becomes a real issue in that repo. The rhythm is simple: orient, act, verify, then continue.

      +

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

      +

      Alex: Start with Bulk Edit Items. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, check the checkbox on each row (first column, Space to toggle). Then, a bulk action bar appears 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: This is the part worth saying out loud. Here is the plain-English version of 6. Built-In Automations. Projects v2 has native automation rules - no GitHub Actions YAML 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 Accessing Automations. What should a learner take away from it?

      +

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

      +

      Alex: First, select the. menu (project overflow) in the top-right. Then, select "Workflows". After that, you'll see a list of built-in automation rules you can enable/disable. 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 Available Built-In Workflows. Item added to project: When an item is manually added, its Status is set to a value you choose. This is the part to say slowly: Item reopened: When an issue or pull request is reopened, its Status changes back (for example, to "In Progress").

      +
      +

      Jamie: Let's pause on Setting Up Auto-Add. What should a learner take away from it?

      +

      Alex: The reason Setting Up Auto-Add matters is that this is the most powerful workflow for maintainers. That gives the learner a simple foothold: now any matching issue in linked repos is added to your project the moment it's filed - no manual triage step required.

      +

      Alex: First, in Workflows, select "Auto-add to project". Then, toggle it On. After that, configure the filter: e.g., label:accessibility is:issue adds any new issue with the accessibility label automatically. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Here is the practical turn. Start with GitHub Actions Integration: For more complex automations, Projects v2 has a full GraphQL API and works with GitHub Actions. The next useful detail is this: See Appendix Q: GitHub Actions and Workflows for the foundation, and the GitHub documentation on automating projects for advanced patterns. 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 what that changes in practice. Auto-assign items based on repository when added. Set due dates based on linked milestone. Send Slack notifications when high-priority items are added.

      +

      Jamie: Let's pause on 7. Iterations (Sprints). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 7. Iterations (Sprints). An iteration field lets you group work into time-boxed cycles - sprints, weeks, or any cadence you choose.

      +
      +

      Jamie: Let's pause on Creating an Iteration Field. What should a learner take away from it?

      +

      Alex: Start with Creating an Iteration Field. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, add a new field (the + column button in Table view). Then, select "Iteration" as the field type. After that, name it (e.g., "Sprint"). Finally, set the iteration duration (1 week, 2 weeks, custom). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Creating an Iteration Field, what is the practical point?

      +

      Alex: First, GitHub automatically generates current and upcoming iterations. It is 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 Iterations. What should a learner take away from it?

      +

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

      +

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

      +

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

      +

      Alex: First, select the Insights tab (the bar chart icon). Then, select "Current iteration". After that, see: items by status, completion rate, items added vs closed over time. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Jamie: Let's pause on 8. Views and Filters. What should a learner take away from it?

      +

      Alex: Start with 8. Views and Filters: A view is a saved configuration of layout + filters + grouping + sort. The next useful detail is this: You can have many views on one project, each showing a different slice of the data.

      +

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

      +

      Alex: Start with Creating a View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, activate the "+ New view" button in the view tab bar. Then, choose layout (Table, Board, Roadmap). After that, configure filters, grouping, sort. Finally, the view saves automatically with a default name - rename by clicking/activating the tab label. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

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

      +

      Alex: This is where Filter Syntax becomes real: the filter bar accepts a query language similar to GitHub's issue search. That matters in practice: status:In Progress shows only items with that Status value.

      +
      +

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

      +

      Alex: Keep the learner anchored in Grouping. In Table or Board view, you can group rows. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, select "Group by" in the view configuration menu. Then, choose any field: Status, Assignee, Priority, Iteration, Label, Repository. After that, items are collapsible into group sections. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

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

      +

      Alex: The reason Sorting matters is that multiple sort levels are supported.

      +

      Alex: The parts worth keeping in working memory are these. Priority ascending, then due date ascending.

      +

      Alex: Keep the thread going. Start with 9. Cross-Repository Projects: A single project can track issues and PRs from multiple repositories - including repos in different organizations (if you have access).

      +
      +

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

      +

      Alex: Start with Add a Repository to a Project. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in project settings (the. overflow menu → "Settings" ). Then, select "Manage access" → "Add repository". After that, search and select additional repositories. Finally, items from those repos can now be added to the project. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Another way to ground it. This is where Using the Repository Field becomes real: when a project spans multiple repos, the "Repository" field lets you see - and filter by - which repo each item belongs to. That matters in practice: Common use case: An organization project tracking all accessibility bugs across every repo, labeled accessibility, with Auto-add enabled. 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 Project Home Page (list of projects). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 3 → Jump to project titles (they are h3 links); Enter → Open a project. 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 Table View matters is that NVDA note: Use Browse mode (NVDA+Space to toggle) to read all cell content, then App mode (NVDA+Space again) for interactive editing. That gives the learner a simple foothold: NVDA announces cell content as you navigate with arrow keys.

      +

      Jamie: Let's pause on 11. Accessibility Agents: /project-status. What should a learner take away from it?

      +

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

      +

      Alex: Keep the teaching thread moving. Start with What It Shows. There is something to understand, something to try, and something that proves the try worked.

      +

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

      +
      +

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

      +

      Alex: This is where Example Output becomes real: GitHub Project: Accessibility Agents Roadmap (3 active views). That matters in practice: After the overview: "Want to see a specific column or check a team member's workload?".

      +

      Alex: The room should hear these as checkpoints. Stale: "Update screen reader navigation guide" - In Review for 9 days, no activity. Unassigned: "Triage accessibility bug backlog" in In Progress.

      +

      Alex: Keep the teaching thread moving. Start with When to Use It. 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. 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.

      +

      Jamie: Let's pause on Exercise 1: Create a Personal Tracking Project. What should a learner take away from it?

      +

      Alex: Start with Exercise 1: Create a Personal Tracking Project. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, create a new project at the organization level: name it "My Workshop Contributions". Then, add the Board layout. After that, add a custom Priority field with options: P0, P1, P2. Finally, add your fork of accessibility-agents as a linked repository. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Exercise 1: Create a Personal Tracking Project, what is the practical point?

      +

      Alex: First, add any open issue you've filed to the 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 Exercise 2: Set Up Automation. What should a learner take away from it?

      +

      Alex: Start with Exercise 2: Set Up Automation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in your project's Workflows, enable "Item closed" → Status: Done. Then, file a test issue in your fork. After that, close that issue. Finally, verify it moved to "Done" automatically in the project board. Think of 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 3: Create a Sprint View. What should a learner take away from it?

      +

      Alex: Start with Exercise 3: Create a Sprint View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, add an Iteration field named "Sprint" with 2-week iterations. Then, assign your existing project items to the current sprint. After that, switch to Roadmap view - observe the items on the timeline. Finally, check Insights to see the current iteration burndown. Treat 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 4: Cross-Repo Project (Advanced). What should a learner take away from it?

      +

      Alex: This is where Exercise 4: Cross-Repo Project (Advanced) becomes real: 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. That matters in practice: Next: Appendix S: Releases and Insights Back: Appendix Q: GitHub Actions Teaching chapter: Chapter 09: Labels, Milestones, and Projects.

      +

      Alex: First, create a cross-repo project connected to two of your repositories. Then, add the Repository field to the Table view. After that, create a view filtered to is:issue label:accessibility. Finally, set up Auto-add: any issue with the accessibility label in those repos goes to this project automatically. 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 26. Next in the series is episode 27, where we keep building the same contributor muscles.

      - +

      GitHub search query language, qualifiers, and filtering for issues, PRs, and code.

      -

      Based on: Appendix J: Advanced Search

      - - -

      Download Episode 27 (MP3)

      +

      Based on: Appendix N: Advanced Search

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 27: Advanced Search

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is episode 27, Advanced Search. I am Alex, and I am thrilled to be back with you for another deep dive into making GitHub work for us, rather than the other way around. Today, we are unlocking what I consider to be a developer superpower.

      -

      Jamie: And I am Jamie. I am so ready for this one. When I started learning GitHub about two years ago, I spent so much time just tabbing through endless lists of issues, trying to find the one bug I was supposed to be working on.

      -

      Alex: That is a nearly universal experience, Jamie. Most people start by navigating to a repository, moving to the section called Issues, and then tabbing through the pagination links at the bottom of the page. Next page, next page, next page. It is tedious.

      -

      Jamie: Extremely tedious. Especially when you have your screen reader reading out every single issue title, author, and timestamp along the way.

      -

      Alex: Exactly. And that brings us to today's topic. We are going to learn how to bypass all of that navigation by using GitHub's advanced search query language. For screen reader users in particular, using the search bar with precise text commands is exponentially faster and more accessible than navigating filter dropdowns, checking boxes, and waiting for the page to dynamically reload.

      -

      Jamie: I love anything that saves me keystrokes. Before we jump in, let us quickly remind everyone of the prerequisites. You should be familiar with the basic concepts of issues and pull requests, which we covered back in episodes 12 and 15. If you know what an issue is, and you know what a pull request is, you are perfectly positioned for today.

      -

      Alex: Let us start with the interface. The global search bar is located at the top of nearly every page on GitHub. But you do not need to manually navigate your cursor to it. From almost anywhere on the site, you can simply press the forward slash key.

      -

      Jamie: Just the forward slash?

      -

      Alex: Just the forward slash key. When you press it, your focus is instantly moved into the search input field. You can then type your query and press the Enter key. When the results load, they are organized into different categories.

      -

      Jamie: Right, and those categories are called search scopes, correct?

      -

      Alex: That is right. GitHub does not just search one bucket of data. It searches across multiple scopes. The main scopes are repositories, code, issues, pull requests, users, and topics. When you run a global search, GitHub searches across everything, but the results page lets you navigate to specific sections to narrow down what you are looking for.

      -

      Jamie: So how does global search differ from in-repository search? Because I have noticed that if I am already inside a project, the search behaves differently.

      -

      Alex: That is a great observation. Think of global search like walking into a massive department store and shouting, where are the shoes. You might get directed to men's shoes, women's shoes, athletic shoes, or children's shoes across the entire building. That is global search. But if you are already standing in the athletic department, and you ask the same question, the system assumes you only want athletic shoes.

      -

      Jamie: So if I navigate to the accessibility-agents repository, and then I press the forward slash key to focus the search bar, it automatically scopes my search to just that repository.

      -

      Alex: Exactly. GitHub automatically inserts a piece of text into the search bar for you. It will say repo, a colon, and then the name of the repository. This brings us to the core concept of today's episode, which is qualifier syntax.

      -

      Jamie: Qualifier syntax. That sounds like something out of a grammar textbook.

      -

      Alex: It sounds a bit dry, but it is actually very simple. A qualifier is just a filter. And the syntax, or the rules for typing it, always follows a specific pattern. It is a key, followed immediately by a colon, followed immediately by a value. No spaces in between.

      -

      Jamie: Key, colon, value. So if I want to search for a specific language, language is the key, and python is the value. I would type language, colon, python.

      -

      Alex: Spot on. And that rule about no spaces is the single most common stumbling block. If you type language, colon, space, python, GitHub thinks you are searching for the literal word python in the text, rather than filtering the results by the programming language.

      -

      Jamie: Oh, I have definitely done that. I would type author, colon, space, Jamie, and wonder why nothing showed up.

      -

      Alex: We have all been there. So, key, colon, value, no spaces. Let us look at how we apply this to issues. Issues are essentially the to-do list of a GitHub project. When you are participating in a workshop or a hackathon, finding the right issue is step one.

      -

      Jamie: What are the most common issue qualifiers we should know?

      -

      Alex: The most fundamental ones define the state of the issue. You will use the key called is. So you type is, colon, open, to find only open issues. Or is, colon, closed, to find issues that have already been resolved.

      -

      Jamie: That makes sense. What about finding issues that have a specific tag, like the good first issue tag we use in the workshop?

      -

      Alex: For that, we use the label qualifier. You type label, colon, and then the name of the label. Now, if the label name has spaces in it, like good first issue, you must wrap the value in quotation marks. So you type label, colon, quote, good first issue, quote.

      -

      Jamie: Okay, let me recap that. If I want to find an open issue that is a good first issue, I type is, colon, open, space, label, colon, quote, good first issue, quote.

      -

      Alex: Perfect. Notice how you put a space between the two different qualifiers. That is exactly right. You string them together with spaces to combine the filters.

      -

      Jamie: What if I want to find issues that I created? Or issues that someone else is working on?

      -

      Alex: You have two great qualifiers for people. The first is author, which filters by who created the issue. The second is assignee, which filters by who is currently assigned to work on it.

      -

      Jamie: So I could type author, colon, and my username?

      -

      Alex: You could, but GitHub gives us a brilliant shortcut. Instead of typing your username, you can type the at symbol followed by the word me. So author, colon, at sign, me. This is fantastic because you can share that exact query with anyone, and it will automatically filter for whoever is currently logged in.

      -

      Jamie: Oh that is clever! I wish I had known that when I started. I used to type my full username out every single time. So if I want to find open issues assigned to me, I type is, colon, open, space, assignee, colon, at sign, me.

      -

      Alex: Exactly. You can also use the milestone qualifier. A milestone is a way to group issues together for a specific release or a sprint. If you are working on the summer release, you might type milestone, colon, quote, summer release, quote.

      -

      Jamie: OK that sounds like a lot of steps and a lot of syntax to memorize.

      -

      Alex: It does! But here is the thing, you do not have to memorize them all at once. You are just learning a new way to ask for what you want. Think of it like ordering at a restaurant. You do not just say food. You say, item, colon, burger. Temperature, colon, medium. Side, colon, fries. You are just giving GitHub your exact order.

      -

      Alex: Let us move over to pull requests. A pull request, and I love that name because you are literally requesting that someone pull your changes into their project, has its own set of qualifiers.

      -

      Jamie: Because pull requests are basically issues that contain code, right?

      -

      Alex: Exactly. In fact, under the hood, GitHub treats a pull request as a type of issue. That means all the issue qualifiers we just talked about, like is, colon, open, and author, colon, at sign, me, work for pull requests too. But to ensure you only get pull requests and not regular issues, you add the qualifier is, colon, pr. P R stands for pull request.

      -

      Jamie: So if I want to find my open pull requests, I type is, colon, pr, space, is, colon, open, space, author, colon, at sign, me.

      -

      Alex: You got it. Now, let us look at qualifiers unique to pull requests. Often, you want to know if a pull request is ready to be merged, or if it is still a work in progress. You can use draft, colon, true, to find pull requests that are marked as drafts.

      -

      Jamie: And if I am a maintainer, and I want to find pull requests that have been reviewed and approved, how do I do that?

      -

      Alex: You use the review qualifier. You type review, colon, approved. This filters the list to only show pull requests where another developer has formally approved the code.

      -

      Jamie: That is incredibly useful for clearing out a backlog. What about the branches? I know when I make a pull request, I am asking to merge my feature branch into the main branch. Can I search based on those branch names?

      -

      Alex: Yes, and this brings us to two important technical terms, head and base. Let us define head and base using an analogy. Think of a pull request like a train arriving at a train station. The head is the moving train. It contains the new passengers, or in our case, the new code commits. The base is the station platform. It is the destination where the train is arriving.

      -

      Jamie: So the head is my feature branch, and the base is the main branch.

      -

      Alex: Exactly. If you want to find all pull requests that are targeting the main branch, you type base, colon, main. If you want to find pull requests coming from a specific feature branch, you type head, colon, feature dash accessibility.

      -

      Jamie: Alright, we have covered issues and pull requests. But what if I am looking for actual code? Like, what if I want to find every time a specific function is used in a project, so I can see an example of how to write it?

      -

      Alex: Searching code is where this system truly shines. GitHub recently completely overhauled their code search engine, and it is blazingly fast. To search code, you usually want to scope it to a specific repository or organization first, otherwise you will search all the public code in the world.

      -

      Jamie: Which is a lot of code.

      -

      Alex: A massive amount. So you start with the repo qualifier. You type repo, colon, followed by the organization name, a forward slash, and the repository name. For example, repo, colon, community dash access, forward slash, accessibility dash agents. Then, you can just type the word or function name you are looking for.

      -

      Jamie: So if I am looking for the term aria dash hidden, I just type repo, colon, community dash access, forward slash, accessibility dash agents, space, aria dash hidden.

      -

      Alex: Exactly. But we can get much more precise. We can use the language qualifier to only search inside specific programming languages. Language, colon, javascript, or language, colon, python.

      -

      Jamie: What if I only want to search inside markdown files, like documentation?

      -

      Alex: Then you use the extension qualifier. You type extension, colon, m d. M d is the file extension for markdown. You can also use the path qualifier to only search inside a specific folder. For example, path, colon, docs, forward slash. That restricts your search to only files located inside the docs directory.

      -

      Jamie: Let me put that all together. If I want to find the word keyboard inside any markdown file in the docs folder of my repository, I would type repo, colon, my name, forward slash, my project, space, extension, colon, m d, space, path, colon, docs, forward slash, space, keyboard.

      -

      Alex: That is a perfect query. You are narrowing the funnel step by step. First the repository, then the file type, then the folder, and finally the keyword. Your screen reader will then announce the number of code results found, and you can navigate through the actual snippets of code directly from the search results page.

      -

      Jamie: This is making so much sense. We have talked about states, labels, people, and code. What about time? Sometimes I want to find issues that have been sitting around for a long time, or maybe pull requests that were opened just this week.

      -

      Alex: Date range qualifiers are incredibly powerful, but they do require a specific format. You use the keys created, updated, or closed. And the value must be a date formatted as year, dash, month, dash, day. Four digits for the year, two for the month, two for the day.

      -

      Jamie: So for January first, twenty twenty five, I would type twenty twenty five, dash, zero one, dash, zero one.

      -

      Alex: Exactly. But you usually do not want things from exactly one day. You want things before or after a date. To do this, we use the greater than and less than mathematical symbols.

      -

      Jamie: Oh, this is where the syntax gets really strict.

      -

      Alex: It does, but once you type it a few times, it becomes muscle memory. If you want to find issues created after January first, twenty twenty five, you type created, colon, the greater than sign, twenty twenty five, dash, zero one, dash, zero one.

      -

      Jamie: And the greater than sign means after, because the dates are moving forward in time.

      -

      Alex: Correct. And if you wanted issues updated before January first, twenty twenty six, you would type updated, colon, the less than sign, twenty twenty six, dash, zero one, dash, zero one.

      -

      Jamie: What if I get hundreds of results? Can I change the order they are displayed in? Because by default, GitHub seems to show the most relevant ones, but sometimes I just want the newest ones at the top.

      -

      Alex: You absolutely can. And this is another huge time saver for screen reader users, because you do not have to navigate to a sort dropdown menu. You just add a sort qualifier to your text. You type sort, colon, the field you want to sort by, a dash, and then either asc for ascending, or desc for descending.

      -

      Jamie: Ascending means going up, and descending means going down. So if I want the newest items first, I want the creation dates going down from newest to oldest.

      -

      Alex: Right. So you type sort, colon, created dash desc. If you wanted the oldest items first, you would type sort, colon, created dash asc.

      -

      Jamie: Okay, Alex, I have to ask. I know a lot of our listeners, myself included, spend a lot of time in the terminal using the command line interface. Can we do all of this search magic without ever opening a web browser?

      -

      Alex: I am so glad you asked. Yes. The GitHub command line tool, which you access by typing g h in your terminal, has a dedicated search command. You just type g h, space, search, space, issues, and then you can pass in all the same qualifiers we just discussed.

      -

      Jamie: Wait, really? So I can type g h, space, search, space, issues, space, assignee, colon, at sign, me, space, is, colon, open?

      -

      Alex: Yes, exactly like that. And it will print a beautifully formatted list right in your terminal, which your screen reader will read out instantly. For many blind developers, using g h search is the absolute fastest way to find an issue, grab its identification number, and start working on it, entirely bypassing the web interface. You can search issues, pull requests, and repositories right from the command line.

      -

      Jamie: That is a game changer. But whether I am using the web browser or the terminal, typing out these massive queries every single day seems like it would get tiring. Is there a way to save a search? Like building a personal search library?

      -

      Alex: This is an area where GitHub's web interface is slightly lacking. They do not have a native, built in button that says save this search to your profile. However, there is a very simple workaround. Every time you run a search on the GitHub website, your entire query is encoded into the web address, the URL, at the top of your browser.

      -

      Jamie: Oh, so I can just use my web browser's bookmark feature!

      -

      Alex: Precisely. You construct your perfect, complex query once. Maybe it is finding all open, unassigned accessibility bugs in your organization. You run the search, ensure the results look right, and then you just bookmark that page in your browser. You can name the bookmark Open Accessibility Bugs. The next time you want to run that search, you just open your bookmarks and activate that link. It will run the search live against the current data.

      -

      Jamie: That is so practical. I am definitely going to create a bookmark folder just for my daily GitHub workflows. I will have one for my open pull requests, one for issues I need to review, and one for good first issues in the workshop repository.

      -

      Alex: That is a fantastic strategy, Jamie. And that brings us to the end of our deep dive into advanced search. We covered a massive amount of ground today, but remember, you do not need to memorize every single qualifier right now.

      -

      Jamie: Right, the goal is just to know what is possible, so when you are stuck looking for something, you know there is a better way to find it.

      -

      Alex: Exactly. Let us summarize our key takeaways for today. First, you can jump directly to the global search bar from almost anywhere on GitHub by simply pressing the forward slash key. Second, all qualifiers use a strict key, colon, value syntax with absolutely no spaces. Third, you can use shortcuts like the at symbol followed by the word me to easily find your own issues and pull requests.

      -

      Jamie: Fourth, code search lets you find specific functions or keywords across an entire project, and you can narrow it down using the language and path qualifiers. And fifth, you can save your most complex searches by simply bookmarking the results page in your web browser.

      -

      Alex: Perfectly summarized. I highly encourage everyone to spend ten minutes today just experimenting with the search bar. Try finding an issue you worked on last month. Try finding a piece of code you wrote. The more you use these qualifiers, the more natural they will feel.

      -

      Jamie: I am going to go set up my bookmarks right now. What are we covering in the next episode?

      -

      Alex: In episode 28, we are moving from finding things to reviewing things. We will be covering the pull request review interface, including how to navigate inline code comments, how to leave a review, and how to read a diff efficiently with a screen reader. It is a critical skill for open source collaboration.

      -

      Jamie: I cannot wait. I always find reviewing code a bit intimidating, so I am looking forward to breaking it down.

      -

      Alex: We will make it approachable, I promise. Thank you all for listening to Gitt Going with GitHub. Keep practicing your queries, and we will see you in the next episode.

      +

      Alex: Welcome to episode 27 of Git Going with GitHub: Advanced Search. 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 GitHub search query language, qualifiers, and filtering for issues, PRs, and 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 Finding Anything Across All of GitHub: GitHub's search engine is powerful and underused. The next useful detail is this: 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.

      +

      Alex: The next layer is this. Here is the plain-English version of 1. The Search Interface. GitHub's search is accessible from nearly any page. It 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. 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.

      +

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

      +

      Alex: Start with Learning Cards: The Search Interface. 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 / 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. 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.

      +
      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Search Scopes. By default, GitHub searches across all of GitHub. This is the part to say slowly: Example: repo:community-access/accessibility-agents in:title keyboard finds issues/PRs whose titles mention "keyboard" in the accessibility-agents repo.

      +

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

      +

      Alex: The reason Going to the Issues search directly matters is that GitHub's issue/PR search is at github.com/issues (your issues) or github.com/pulls (your PRs). That gives the learner a simple foothold: the search bar there is pre-scoped to "repos you have access to involving you.".

      +

      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 Learning Cards: Searching Issues and Pull Requests. 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 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. 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.

      +
      +

      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. Searching Code. Code search operates differently from issue search. Put another way, as of 2024, GitHub uses an improved code search engine (sometimes called "code search v2") with better indexing.

      +

      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 9. Practical Queries for This Workshop becomes real: bookmark these for use during the hackathon.

      +

      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: Keep the learner anchored in 10. Saving and Reusing Searches. GitHub does not have a built-in saved-search feature, but you can.

      +

      Alex: First, bookmark the URL - every search result page has the query in the URL. Bookmark it in your browser for instant re-run. Then, pin in notifications - if you're watching a repo, set up notification filters. After that, accessibility Agents - use /my-issues and /my-prs for your personal saved-search equivalents without leaving VS Code. 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 Example bookmarkable URL matters is that next: Appendix O: Branch Protection Back: Appendix M: Accessibility Standards Teaching chapter: Chapter 05: Working with Issues. 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 27. Next in the series is episode 28, where we keep building the same contributor muscles.

      - +

      Episode 28: Branch Protection and Rulesets

      Required reviews, status checks, rulesets, and diagnosing blocked merges.

      -

      Based on: Appendix K: Branch Protection and Rulesets

      - - -

      Download Episode 28 (MP3)

      +

      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 back to Gitt Going with GitHub. This is episode 28, Branch Protection and Rulesets. I am Alex, here to guide you through the wonderful, and sometimes slightly rigid, world of repository security.

      -

      Jamie: And I am Jamie. I am so glad we are talking about this today because I vividly remember the first time I tried to contribute to an open source project. I did all the work, I pushed my branch, I created my pull request, and then I navigated to the bottom of the page to merge it. But I could not. The merge button was just completely unavailable to me. There were all these messages about failing checks and required reviews. I honestly panicked. I thought I had broken their entire repository.

      -

      Alex: I promise you, you did not break anything. What you ran into is exactly what we are covering today. That was branch protection doing its job. Think of branch protection like the velvet rope at a museum. You are absolutely welcome to come in, look around, and even sketch your own copy of the artwork. But if you want to actually alter the painting on the wall, there is a very strict process you have to follow, and a curator has to approve it. Branch protection exists to prevent accidental changes to the main branch of a repository.

      -

      Jamie: That makes so much sense. Because the main branch is usually the production code, right? It is the version of the software that people are actually downloading or the website that is live right now. If I could just push my experimental changes straight into main, I could take down the whole project.

      -

      Alex: Exactly. Before branch protection existed, if you had write access to a repository, you could just push directly to main. And people make mistakes. We type the wrong command, or we push a branch that is not finished yet. Branch protection is a safety net. It is a set of rules, configured by the repository administrators, that dictate exactly what must happen before code is allowed to be merged into a protected branch.

      -

      Jamie: So let us break down what those rules actually look like. We mentioned the classic approach to branch protection rules. How does that work?

      -

      Alex: In the classic approach, a repository administrator creates a rule for a specific branch, usually main. You can think of this rule like a pre-flight checklist on a clipboard. The pilot cannot take off until every single item on that clipboard is checked off.

      -

      Jamie: And the most common item on that checklist is probably a required pull request review, right?

      -

      Alex: Yes, absolutely. A pull request, as a quick reminder, is when you are literally requesting that the maintainers pull your changes into their project. When a branch has a required review rule, it means another human being has to look at your code and explicitly approve it. The rule might say you need one approving review, or maybe two or three for a really critical project.

      -

      Jamie: I have definitely seen that. I will navigate to the merge box at the bottom of the pull request page, and my screen reader will read something like, one review required. So I know I have to request a review from someone on the team. But I have a question about this. What happens if I get an approval, but then I realize I made a typo, so I push a new commit to fix it. Does my approval stay?

      -

      Alex: That depends on how the maintainer configured the rule, but usually, the answer is no. There is a setting called dismiss stale reviews. If that is turned on, the moment you push a new commit, any existing approvals are wiped out, and you have to get a fresh review.

      -

      Jamie: Oh, that is clever. Frustrating if you are in a hurry, but clever.

      -

      Alex: It is a great security feature. Think about it like having a co-pilot double-check your flight coordinates. If they approve the coordinates, but then you go in and change the destination by a few degrees, you want them to verify the new coordinates too. Otherwise, someone could get an approval on a perfectly safe piece of code, and then sneak in a malicious change right before merging.

      -

      Jamie: Okay, so required reviews are one part of the checklist. What else is on there? I know I always run into status checks.

      -

      Alex: Required status checks are huge. This is where Continuous Integration, or CI, comes in. CI refers to automated scripts that run every time you push code. The branch protection rule can say, these specific automated tests must pass before this pull request can be merged.

      -

      Jamie: So this is like an automated grammar checker that runs before you are allowed to publish an article. Or an automated car wash that your car has to go through before it goes on the showroom floor.

      -

      Alex: Perfect analogies. You might have a status check that compiles the code to make sure there are no syntax errors. You might have a check that runs the entire automated test suite. You might even have an accessibility-check that scans your user interface changes for basic accessibility violations. If the rule says those checks are required, the merge button will literally be blocked until every single one of them reports back with a success status. If even one test fails, you cannot merge.

      -

      Jamie: Okay, what about keeping things up to date? I sometimes get a message that says my branch is out of date with the base branch.

      -

      Alex: Right. That is another very common branch protection rule. It requires your branch to be entirely up to date with the main branch before you can merge. Let us say you created your branch on Monday. You work on it for a few days. But on Tuesday and Wednesday, other people merged their own changes into main. By Thursday, your branch is missing all the new stuff that was added.

      -

      Jamie: And if I just merge my code anyway, I might accidentally overwrite their changes, or introduce a bug because my code was not tested alongside their new code.

      -

      Alex: Precisely. So this rule blocks you from merging until you bring those new changes from main into your branch. You usually do this by activating the Update branch button in the merge box, which brings all the new main commits into your working branch. Then your automated status checks will run one more time to make sure your code still works with the new updates.

      -

      Jamie: That makes a lot of sense. Now, there is another rule we should talk about, because we covered the prerequisite for it back in our authentication episode. Requiring signed commits.

      -

      Alex: Yes, requiring signed commits is becoming very common, especially in open source. A signed commit includes cryptographic proof of your identity, usually using an SSH key or a GPG key. It proves that you are actually the person who wrote the code, and not someone impersonating you.

      -

      Jamie: Like putting a heavy wax seal with your family crest on an envelope, instead of just writing your return address on it.

      -

      Alex: Exactly. Anyone can write an address, but only you have the stamp for the wax seal. If a repository has a rule requiring signed commits, and you push a commit without a signature, the merge will be blocked. The error will say commits must have verified signatures. You will have to go back to your command line, configure commit signing, and rewrite those commits to include your signature.

      -

      Jamie: Which, speaking from experience, can be a little tricky if you are new to Git. If you ever run into that, definitely go back and listen to our episode on Git Authentication for a refresher. Okay, is there anything else in the classic branch protection rules?

      -

      Alex: There is one more major one, which is restricting who can push to the branch. You can set a rule that says, absolutely nobody is allowed to push directly to main, except for the lead maintainer, or maybe a specific release bot.

      -

      Jamie: Like having keycard access to the server room. Everyone can work in the building, but only the IT administrators have the badge that opens that specific door.

      -

      Alex: Exactly. For everyone else, they must use a pull request.

      -

      Jamie: Okay, so that is classic branch protection. But the title of this episode is Branch Protection and Rulesets. What is a ruleset, and how is it different?

      -

      Alex: Repository Rulesets are the modern, next generation approach to protecting your code. GitHub introduced them recently because classic branch protection, while great, had some limitations as companies and projects grew larger.

      -

      Jamie: What kind of limitations?

      -

      Alex: Well, classic branch protection rules are applied on a single repository, to a single branch name. If your company has five hundred repositories, and you want to ensure every single one of them requires two reviews before merging to main, you used to have to go into all five hundred repositories individually and set up that rule.

      -

      Jamie: Oh wow. That sounds like an absolute nightmare for a system administrator.

      -

      Alex: It was. And if the company policy changed to require three reviews, you had to do it all over again. Rulesets solve this by operating at the organization level. You can create one organization ruleset that says, require two reviews on the main branch for every repository we own.

      -

      Jamie: That is so much better. It is like upgrading from having a physical padlock on every single door in an office building, where you have to manually change the lock on every door if someone loses a key. Upgrading to a programmable smart building system where you can just update the access policy from one central computer.

      -

      Alex: That is a brilliant analogy. Centralized control is a huge benefit of rulesets. Another major difference is how rulesets target branches. With rulesets, you can use tag and branch patterns. Instead of just protecting the branch named exactly main, you can create a pattern using an asterisk as a wildcard.

      -

      Jamie: So I could write a rule for release dash asterisk, and it would automatically protect branches named release dash version one, release dash version two, and so on?

      -

      Alex: Exactly. Any branch that starts with the word release and a dash will automatically inherit all the protections in that ruleset. You do not have to create a new rule every time you cut a new release branch.

      -

      Jamie: That is incredibly powerful. Are there other differences between classic rules and the new rulesets?

      -

      Alex: Yes, two very important ones. Bypass lists and enforcement modes. Let us talk about bypass lists first. In classic branch protection, a rule is a rule. If you require a status check to pass, it must pass. But sometimes, you have a special automated bot that manages your releases, and you want that bot to be able to bypass the rules and merge directly.

      -

      Jamie: Like a VIP list at a club. The bouncer makes everyone else wait in line and check their coats, but the VIPs get to walk right past the rope. Or an emergency override key for the fire department.

      -

      Alex: Exactly. Rulesets allow you to configure a bypass list. You can specify exact users, teams, or automated apps that are allowed to bypass the rules. And when they do bypass a rule, GitHub logs it in an audit trail so you can see exactly who bypassed the system and when.

      -

      Jamie: And what about enforcement modes? You mentioned that was the other big difference.

      -

      Alex: Right. With classic rules, the rule is always active. It always blocks you. With rulesets, you have three modes. Active, Evaluate, and Disabled. Active means the rule is fully enforced and will block merges. Disabled means the rule is turned off. But Evaluate mode is the really interesting one.

      -

      Jamie: Evaluate mode? Does that mean it just watches what happens without actually blocking anything?

      -

      Alex: Exactly. It is essentially a testing mode. Let us say you want to introduce a new rule requiring all commits to be signed, but you are worried it might disrupt your team's workflow because people do not have their keys set up yet. You can turn the ruleset on in Evaluate mode. It will not block anyone from merging. But it will quietly log every time someone merges a pull request with unsigned commits.

      -

      Jamie: Oh, I love that. So you can look at the logs after a week and say, okay, fifty percent of our team is still pushing unsigned commits. We need to do a training session before we switch this rule to Active. It gives you data without causing a crisis.

      -

      Alex: Exactly. It makes rolling out security changes much less stressful for administrators. Now, keep in mind, as a contributor or a workshop participant, you will probably encounter both systems. Many repositories still use classic branch protection rules because they have been around forever. Newer repositories, or large enterprise organizations, are moving toward rulesets. But for you, as the developer trying to merge a pull request, the experience is largely the same. The merge button will be blocked until you meet the requirements.

      -

      Jamie: Okay, let us talk about that experience. Because that is the most stressful part for a learner. You open your pull request, you think you are done, and then you hit a wall. If my merge is blocked, how do I actually figure out what is wrong, especially using a screen reader?

      -

      Alex: This is such an important skill. The first thing to know is that GitHub tells you exactly what is wrong. It does not hide it. All the diagnostic information is located in the merge box, which is near the bottom of the pull request page.

      -

      Jamie: So if I am using my screen reader, how do I get there efficiently? The pull request page can be really long if there is a big conversation happening.

      -

      Alex: There are a few ways. The quickest way is often to use the H key to jump through the headings on the page until you hear something related to merging. The merge box is contained within a section that usually has a heading like, Merging is blocked, or This branch has no conflicts.

      -

      Jamie: If I am using NVDA, I will sometimes press NVDA plus F7 to open the elements list, filter by headings, and just type the word merge to jump straight to that section.

      -

      Alex: That is a fantastic technique. Once your focus is on that heading, you can just use your down arrow key to read the contents of the merge box. GitHub provides a checklist of exactly what is passing and what is failing. As you arrow down, you might hear, Review required. At least one approving review is required. Or you might hear, Some checks were not successful.

      -

      Jamie: Okay, so let us say I hear that some checks were not successful. How do I find out which test failed? Because just knowing a test failed does not help me fix my code.

      -

      Alex: Right. You need to read the diagnostic codes, just like a mechanic reading the engine light on a dashboard. In that same merge box area, you can press the Tab key until you reach a button or link that says, Show all checks. Press Enter to activate it. This expands a list of every single status check that ran against your pull request.

      -

      Jamie: And then I just tab through that list?

      -

      Alex: Yes. As you tab or arrow through the expanded list, your screen reader will announce the name of each check, and its status. It will say something like, build process, successful. Linting, successful. Unit tests, failing.

      -

      Jamie: And when I find the failing one, how do I see why it failed? Is there a log file?

      -

      Alex: Yes. Right next to the status of the failing check, there is a link that says Details. When you press Enter on the Details link, you will navigate away from the pull request page and into the specific log page for that check.

      -

      Jamie: I have found those log pages can be a bit overwhelming. They are basically just giant text dumps of terminal output.

      -

      Alex: They can be, but they follow a predictable structure. When the log page loads, press the H key to jump to the Summary heading. Arrow down from there to read a high-level overview of what failed. If you need to read the raw log output, it is usually presented in a pre-formatted text block or a series of expandable accordions. You can tab to the specific step that failed, press Enter to expand it, and then use your down arrow key to read the terminal output line by line. Look for words like error or exception.

      -

      Jamie: That is super helpful. It sounds like a lot of steps, but it really is just a process of elimination. Jump to the merge box, read the checklist, expand the checks, find the failure, open the details, read the log.

      -

      Alex: Exactly. And I want to normalize this. Having a blocked pull request does not mean you are a bad developer. It happens to senior engineers every single day. A linting check fails because they forgot a semicolon. A test fails because they missed an edge case. Branch protection is not a punishment. It is an automated assistant helping you catch things before they become real problems in production.

      -

      Jamie: I love that reframing. It is not a bouncer kicking you out of the club. It is a friendly assistant saying, hey, your tie is crooked, let us fix that before you go on stage.

      -

      Alex: Exactly! Now, what if you check the merge box, and all the automated checks are passing, but the merge is still blocked. What else could it be?

      -

      Jamie: Well, based on what we talked about earlier, it could be that I need a review. I would hear, review required. In that case, I need to navigate to the right sidebar, find the Reviewers section, and request a review from a maintainer.

      -

      Alex: Correct. What else?

      -

      Jamie: It could be the out of date warning. The screen reader would say, this branch is out of date with the base branch. I would just need to find the Update branch button in that same merge box and activate it.

      -

      Alex: Spot on. And if you hear, commits must have verified signatures, you know you need to go back to your terminal and sign your work. The merge box is your single source of truth for understanding exactly what the repository rules require from you.

      -

      Jamie: So, as we wrap up, I am curious about how these rules look in the real world. Do most repositories have all of these rules turned on?

      -

      Alex: It completely depends on the context. Let us look at a few common configurations. If you are working on a small team, maybe three or four developers building a startup product, the rules are usually pretty light. It is like a local coffee shop. You might have a rule that requires one approving review, and maybe a basic status check to make sure the code compiles. You want to move fast, and you trust your small team.

      -

      Jamie: That makes sense. You do not need a massive security apparatus for four people sitting in the same room. What about an open source project?

      -

      Alex: An open source project is more like a busy public library. Anyone in the world can walk in and suggest changes. So the rules are much stricter. You will almost certainly see requirements for multiple reviews from core maintainers. You will see extensive automated testing, because the code has to work on many different operating systems. And you will very often see a requirement for signed commits, to prevent bad actors from submitting malicious code under someone else's name.

      -

      Jamie: Right, because you do not personally know the people submitting the pull requests. You have to rely on the automated rules to verify their identity and their code quality.

      -

      Alex: Exactly. And finally, you have the enterprise configuration. Think of a massive banking network. Thousands of developers, strict regulatory compliance, and huge financial risk. In an enterprise, you will see complex organization-level Rulesets. They will enforce multiple reviews, extensive security scanning, accessibility checks, and strict branch naming conventions. They will use bypass lists heavily to allow their automated deployment bots to do their jobs, while strictly locking down human access.

      -

      Jamie: It is amazing how flexible the system is. It scales from a tiny startup to a massive bank, all using the exact same underlying concepts.

      -

      Alex: It really is. And as a developer, your job is not necessarily to configure all of these rules, unless you are the repository administrator. Your job is simply to understand that these rules exist, respect the velvet rope, and know how to read the merge box to satisfy the requirements.

      -

      Jamie: This has been incredibly clarifying. I feel like I understand the why behind all those blocking messages now. Let us summarize the key takeaways for our listeners today. First, branch protection exists to prevent accidental or unverified changes from entering the main branch. It is a safety net, not a punishment.

      -

      Alex: Second, classic branch protection uses rules tied to a specific branch in a single repository. Common rules include requiring pull request reviews, requiring automated status checks to pass, forcing branches to be up to date, and requiring signed commits.

      -

      Jamie: Third, Repository Rulesets are the modern upgrade. They allow administrators to apply rules across entire organizations, use wildcards to protect multiple branches at once, set up bypass lists for VIP access, and use Evaluate mode to test rules before enforcing them.

      -

      Alex: And finally, when your merge is blocked, do not panic. Navigate to the merge heading using your screen reader, read the checklist, expand the status checks, and read the logs. The merge box will always tell you exactly what you need to do to move forward.

      -

      Jamie: I am definitely going to be less intimidated the next time I see a grayed out merge button. So, what are we covering in the next episode?

      -

      Alex: Next time, we are going to dive deeper into the actual review process. We have talked about requiring reviews, but how do you actually leave one? We will cover how to navigate a pull request diff, leave inline comments, and officially approve or request changes on someone else's code.

      -

      Jamie: That is going to be great. I cannot wait to learn how to be a good reviewer. Thanks for listening, everyone, and we will catch you in the next episode of Gitt Going with GitHub.

      +

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

      +
      +

      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: 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: 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: 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: 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: 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 L: GitHub Security Features

      - - -

      Download Episode 29 (MP3)

      +

      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 to Gitt Going with GitHub. This is episode twenty nine, GitHub Security Features. I am Alex, and today we are talking about how GitHub helps keep your code, your contributors, and your users safe.

      -

      Jamie: And I am Jamie. I have to be honest, Alex, the word security always makes me a little nervous. It feels like one of those areas where making a mistake has massive consequences. When I first started learning GitHub a couple of years ago, I was terrified I would accidentally break something or leak something important.

      -

      Alex: That is a completely normal way to feel. Security can be intimidating. It sounds like a lot of high stakes pressure. But here is the thing, GitHub has built a massive safety net directly into the platform. You do not have to be a cryptography expert to write secure code. Today, we are going to learn how GitHub automates most of this heavy lifting for you.

      -

      Jamie: That is a huge relief. As a reminder for our listeners, we are at the end of day two of our workshop. We already know how to open pull requests, which we call PRs, and we know how GitHub Actions work. So, what is on the agenda for today?

      -

      Alex: We are going to cover five main areas. First, why security matters so much in open source, specifically supply chain risks. Second, Dependabot, which is your automated dependency assistant. Third, secret scanning, which catches passwords before they leak. Fourth, code scanning using a tool called CodeQL. And finally, private security advisories, which is how you responsibly report a vulnerability if you find one.

      -

      Jamie: Let us start with that first one. Supply chain risks. When I hear supply chain, I think of cargo ships and grocery stores. What does that mean in software?

      -

      Alex: It is a great analogy, actually. Think about baking a cake. If you bake a cake, you probably do not mill your own flour, churn your own butter, and extract your own vanilla. You buy those ingredients from different suppliers. If the flour factory has a contamination issue, your cake is contaminated, even if you did everything perfectly in your own kitchen.

      -

      Jamie: Oh, I see. In software, the ingredients are our dependencies. The libraries and packages we pull into our projects so we do not have to write everything from scratch.

      -

      Alex: Exactly. Modern software is built on thousands of open source dependencies. If an attacker finds a vulnerability in a popular logging library, and your project uses that library, your project is now vulnerable. This is called a supply chain attack. You are only as secure as your weakest dependency.

      -

      Jamie: That sounds terrifying. How am I supposed to know if one of the hundred packages I am using has a security flaw? I cannot read all their code every day.

      -

      Alex: You absolutely cannot, and you should not try. That is exactly where the GitHub Security tab comes in. Every repository has a Security tab. It is your central dashboard for all these features.

      -

      Jamie: How do we navigate to the Security tab using a screen reader?

      -

      Alex: If you are on any repository page, you can move to the secondary navigation landmark. From there, you can tab through the links. You will pass Code, Issues, Pull Requests, Actions, Projects, Wiki, and then you will reach the Security link. Press Enter there.

      -

      Jamie: Is there a keyboard shortcut? I love skipping the tab navigation.

      -

      Alex: There is. If you turn on your screen reader's focus mode or forms mode, you can press G, and then S. G for go, S for security. That will jump you straight to the Security tab.

      -

      Jamie: Okay, so I am on the Security tab. What is the first thing I am going to find there to help with those supply chain risks we talked about?

      -

      Alex: You will find Dependabot. Dependabot is GitHub's automated dependency monitoring system. I like to think of Dependabot as a building inspector who constantly checks the foundation of your house. If it finds a crack, it lets you know. Dependabot does this by issuing what we call Dependabot alerts.

      -

      Jamie: How does it know there is a crack?

      -

      Alex: It checks your project's dependencies against a massive database of known vulnerabilities. When a security researcher discovers a flaw in a package, they publish a Common Vulnerability and Exposure report, or CVE. If Dependabot sees that your project uses a version of a package that has a CVE, it creates an alert.

      -

      Jamie: Are all alerts equally urgent? Because sometimes I feel like I get a lot of them.

      -

      Alex: They are not. Every alert comes with a severity level based on a CVSS score. That stands for Common Vulnerability Scoring System. It is a scale from zero to ten. Critical alerts are nine to ten. Those mean an exploit is likely and the impact is wide. You need to fix those immediately.

      -

      Jamie: What about the other levels?

      -

      Alex: High alerts are seven to eight point nine. You should fix those in your current sprint. Medium alerts are four to six point nine. There is some risk, usually requiring specific conditions to exploit, so you can schedule those fixes. And low alerts are anything under four. The likelihood of an attack is very low, so you can fix them when it is convenient.

      -

      Jamie: Okay, so Dependabot gives me an alert. Let us say it is a High severity alert for a package called lodash. How do I actually read this alert with my screen reader?

      -

      Alex: When you navigate to the Dependabot alerts section in the Security tab, the alerts are presented in a table. If you are using NVDA or JAWS, you can press the T key to jump to the table, and then use your up and down arrow keys to navigate the rows. Each row is an alert. When you find the one for lodash, you can tab to the link and press Enter to open the full details.

      -

      Jamie: What will I find inside the details page?

      -

      Alex: The page is well structured with headings. You can press the H key to move through the Alert title, the Package details, the Description of the vulnerability, and the References. It will tell you exactly which version of lodash is vulnerable, and more importantly, which version includes the fix.

      -

      Jamie: So to fix it, I just need to update my package file, commit the change, and open a pull request?

      -

      Alex: You could do that manually, yes. But Dependabot has a second feature called Dependabot Security Updates. If the repository maintainer has this enabled, Dependabot does not just warn you. It actually opens a pull request for you, automatically updating the dependency to the secure version.

      -

      Jamie: Wait, so the building inspector does not just point out the crack in the foundation, they actually bring a contractor over with the cement and say, here, just sign this paperwork and we will fix it?

      -

      Alex: Exactly. Dependabot writes the branch, updates the package file, and opens the PR. All you have to do as a contributor is review the PR, make sure the tests pass, and merge it. Reviewing and merging Dependabot PRs is honestly one of the highest value, lowest risk ways you can contribute to an open source project.

      -

      Jamie: That is brilliant. Does Dependabot only update packages when there is a security emergency? What if I just want to keep my packages up to date so I do not fall too far behind?

      -

      Alex: That is the third flavor of Dependabot. It is called Dependabot Version Updates. You can configure Dependabot to routinely check for any new versions of your dependencies, regardless of whether there is a security issue.

      -

      Jamie: How do I set that up? Do I use the GitHub website interface?

      -

      Alex: You set it up using a configuration file in your repository. You create a folder called dot github, and inside it, a file called dependabot dot y m l. In that yaml file, you tell Dependabot which package ecosystems to check, like npm for JavaScript or pip for Python, and how often to check, like daily or weekly. Dependabot will then automatically open PRs to keep your project fresh.

      -

      Jamie: Okay, so Dependabot handles the ingredients we bring into our project. But what about the code we write ourselves? I mentioned earlier that I was terrified of leaking something. When I was first learning to code, I accidentally committed an API key to a public repository. It was a nightmare. I had to scramble to figure out what to do.

      -

      Alex: You are definitely not the first person to do that, Jamie. We call things like API keys, database passwords, and authentication tokens, secrets. They are the keys to your digital house. If you hardcode a secret into your project and push it to a public GitHub repository, anyone in the world can find it and use it.

      -

      Jamie: And there are actually bots out there constantly scraping GitHub looking for leaked secrets, right?

      -

      Alex: Yes. If you push an active Amazon Web Services key to a public repo, attackers can find it and spin up thousands of dollars of servers on your account within minutes. That is why GitHub created Secret Scanning.

      -

      Jamie: How does Secret Scanning work? Does it read my code after I push it?

      -

      Alex: It does, but it also does something even better called Push Protection. Push Protection works in real time. When you type git push in your terminal, your code travels to GitHub. Before GitHub accepts the code, it scans it for known patterns of secrets from hundreds of service providers.

      -

      Jamie: What happens if it finds one?

      -

      Alex: It literally bounces your push back to you. Your terminal will display an error message saying Push cannot contain secrets. It will tell you the exact commit, the file name, the line number, and what kind of secret it found, like a GitHub Personal Access Token.

      -

      Jamie: That is like a bouncer at the club checking your pockets, finding your house key, and saying, hey, you cannot bring this inside, you are going to lose it on the dance floor.

      -

      Alex: That is a perfect analogy. Push Protection stops the leak before it ever happens.

      -

      Jamie: But what if I am working on an older project, and someone leaked a secret a year ago, before Push Protection was turned on?

      -

      Alex: That is where Secret Scanning Alerts come in. GitHub continuously scans the entire history of public repositories. If it finds a leaked secret in an old commit, it generates an alert in the Security tab under the Secret scanning section.

      -

      Jamie: Okay, so let us say I am navigating the Security tab, I open the Secret scanning section, and I find an active alert for a leaked token. What is the proper procedure? Do I just delete the token from the file and make a new commit?

      -

      Alex: No, and this is a critical point. Deleting the secret from the file is not enough. Remember, Git keeps a history of every change. Even if you remove it from the latest version of the file, the secret still exists in the older commits. Anyone can look at the commit history and find it.

      -

      Jamie: Oh, right. So the secret is permanently out there. What do I do?

      -

      Alex: You must revoke and rotate the secret. Revoking means you go to the service provider that issued the secret. Let us say it is a Stripe API key. You log into your Stripe dashboard and you delete or disable that specific key. This makes the leaked key completely useless. Even if an attacker has it, it will not work anymore.

      -

      Jamie: And rotating?

      -

      Alex: Rotating just means generating a brand new key to replace the old one, and putting that new key into your secure production environment. Once you have revoked and rotated, you can safely close the alert on GitHub.

      -

      Jamie: How do I avoid hardcoding secrets in the first place? I need my code to talk to databases and APIs.

      -

      Alex: The best practice is to use environment variables. Instead of typing the actual password in your code, you write a variable name, like process dot env dot DATABASE PASSWORD. Then, you store the actual password securely on the server where your code runs, completely outside of Git.

      -

      Jamie: Alright, we have secured our dependencies, and we have made sure we are not leaking passwords. But what if the logic of my code itself has a security flaw? Like, what if I write a function that accidentally allows a hacker to run their own code on my server?

      -

      Alex: That brings us to our fourth topic, Code Scanning. GitHub uses a technique called static analysis to find vulnerabilities in your code. Static analysis means evaluating the code without actually running it.

      -

      Jamie: Like a spellchecker, but for security logic?

      -

      Alex: Exactly. The engine behind GitHub's code scanning is called CodeQL. Q L stands for Query Language. CodeQL essentially treats your codebase like a database. It allows GitHub to write queries that search for common security vulnerabilities, like SQL injection, cross site scripting, or command injection.

      -

      Jamie: How does it know the difference between a safe piece of code and a dangerous one?

      -

      Alex: CodeQL is incredibly smart because it understands data flow. It traces how information moves through your program from a source to a sink.

      -

      Jamie: Source to a sink? Can you explain that?

      -

      Alex: A source is anywhere your program takes in untrusted data from the outside world. Like a user typing into a search box, or a parameter in a web request. A sink is a dangerous function that executes code or interacts with a database. CodeQL looks for paths where untrusted data travels from a source to a sink without being properly sanitized or checked along the way.

      -

      Jamie: I love analogies, so let me try one. It is like a water pipe inspector. The source is where the water enters the house. The sink is the drain. The inspector drops green dye into the water at the source, and then walks through the house to see if any green dye leaks out of the pipes before it safely reaches the drain.

      -

      Alex: That is exactly how data flow analysis works. CodeQL traces the green dye. If the untrusted data hits a dangerous execution function, CodeQL flags it as a vulnerability.

      -

      Jamie: How are these alerts presented to us? Are they easy to read with a screen reader?

      -

      Alex: They are excellent for screen reader users. When you navigate to Code scanning in the Security tab, you will find a table of alerts. You can open an alert by pressing Enter. Inside, you can use the H key to jump through the headings. There is a heading called Code flow. Under that, it gives you a step by step list of exactly how the data travels from the source to the sink.

      -

      Jamie: So it tells me exactly which file and which line number the problem starts on, and where it ends up?

      -

      Alex: Yes. It will say, step one, user input enters at line twelve. Step two, input is passed to the logger function at line forty seven. It makes fixing the vulnerability much easier because you know exactly where to intercept the bad data. Fixing these alerts is a fantastic way to contribute to open source projects.

      -

      Jamie: How do we turn CodeQL on? Is it automatic like Dependabot?

      -

      Alex: You have to set it up, but GitHub makes it very easy. You set it up using a GitHub Action. If you navigate to the Security tab and find the Code scanning section, GitHub will offer to configure CodeQL for you. It will generate a yaml workflow file for GitHub Actions. Once you commit that file, the GitHub Action will automatically run the CodeQL scan every time someone pushes new code or opens a pull request.

      -

      Jamie: Okay, so we have covered all these automated tools. But what happens if the automated tools miss something, and a human being, like me or one of our listeners, discovers a security vulnerability in an open source project? Do I just go to the Issues tab and open a new issue?

      -

      Alex: No. Please, never do that. If you find a security vulnerability, never report it as a public issue.

      -

      Jamie: Why not? I want the maintainers to fix it as fast as possible.

      -

      Alex: Think about it. A public issue is visible to everyone on the internet immediately. If you write down exactly how to crash a server or bypass a login screen in a public issue, you are handing a recipe to every malicious actor in the world. You are shouting that the back door is unlocked using a megaphone, before the owner has a chance to change the locks.

      -

      Jamie: Oh. I did not think about that. So how do I tell the maintainer without telling the whole world?

      -

      Alex: You use a process called responsible disclosure. On GitHub, this is handled through Private Vulnerability Reporting. It allows you to slip a note under the door directly to the security team, without the public ever seeing it.

      -

      Jamie: How do I find out if a project accepts private reports?

      -

      Alex: You should always check the project's security policy first. This is a file in the repository called SECURITY dot m d. You can usually find a link to it in the Security tab under the Policies section. The SECURITY dot m d file will tell you exactly how the maintainers want to be contacted. Sometimes they list a specific email address. But increasingly, they use GitHub's private reporting form.

      -

      Jamie: How do I access the private reporting form?

      -

      Alex: Navigate to the Security tab. If the maintainers have enabled it, you will find a button that says Report a vulnerability. Press Enter on that button.

      -

      Jamie: What does the form look like for a screen reader user?

      -

      Alex: It is a standard web form. You can use your F key or E key to jump between the form fields. First is the Title field, where you provide a short summary. Next is the Description text area. Here you need to be very detailed. Explain exactly how to reproduce the vulnerability, step by step, and what the impact is.

      -

      Jamie: Are there other fields?

      -

      Alex: Yes. There is a dropdown menu for Severity, where you can assess if it is low, medium, high, or critical. There is a field to list the affected versions of the software. And there is an optional field to provide a CVSS score if you know how to calculate one. Once you are done, you navigate to the Submit report button and press Enter.

      -

      Jamie: What happens after I submit it? Do I just wait?

      -

      Alex: The maintainers will receive a private notification. They will review your report, and they might ask you follow up questions in a private advisory thread. They will develop a fix, test it, and publish a new release of the software. Once the fix is public and users have had time to update, the maintainers will publish a public security advisory, and they will often credit you as the person who discovered it.

      -

      Jamie: That sounds like a great way to build a reputation in the open source community. But what if the maintainer ignores me? What if I submit a private report and I do not hear back for a month?

      -

      Alex: The industry standard window for a response is usually thirty to ninety days. If you do not hear back after a reasonable amount of time, you can send a polite follow up in the private thread. If the issue is absolutely critical and the project seems abandoned, you can actually contact GitHub directly, and their security team can assist with coordinated disclosure. But you must give the maintainers a fair chance to fix it first.

      -

      Jamie: Alex, before we wrap up, I saw a strange acronym in the reading materials for this chapter. S B O M. What is an SBOM?

      -

      Alex: SBOM stands for Software Bill of Materials. It is a machine readable inventory of every single component, library, and dependency in a software project.

      -

      Jamie: Like the ingredients list on the side of a cereal box?

      -

      Alex: Exactly. When enterprise companies or government agencies adopt open source software, they need to know exactly what ingredients are inside to ensure they meet compliance and security standards.

      -

      Jamie: How do I make an SBOM for my project? Do I have to type out every single dependency manually?

      -

      Alex: Thankfully, no. GitHub can generate it for you. You navigate to your repository's Insights tab, then move to the Dependency graph section. At the end of the main region, past the graph data, you will find a button called Export SBOM. When you activate that, GitHub generates a standardized JSON file in what is called the SPDX format. It lists all your dependencies, their exact versions, and their open source licenses. It is a very handy feature if you ever work in corporate environments.

      -

      Jamie: That is so easy. One last question. During this workshop, we are working out of a repository called community-access slash accessibility-agents. Do we have to navigate through the web interface to check its security status?

      -

      Alex: You do not. As a special feature for our workshop, the Accessibility Agents repository has a custom slash command. You can type slash security-dashboard in any issue or PR comment. A bot will instantly reply with a clean, accessible text summary of the repository's security health. It will list the number of active Dependabot alerts, confirm if there are any secret scanning alerts, tell you when the last CodeQL scan ran, and even list any open Dependabot pull requests that need reviewing.

      -

      Jamie: Oh, that is clever! I wish I had known that when I started. It puts all the critical information right in front of you without having to dig through multiple tabs and tables. I am definitely going to try running slash security-dashboard on my fork today.

      -

      Alex: That brings us to the end of our deep dive into GitHub Security Features. Let us summarize the key takeaways. First, security is largely about managing your supply chain. Dependabot is your best friend. It alerts you to vulnerabilities in your dependencies and can even open automated pull requests to fix them.

      -

      Jamie: Second, never hardcode passwords, API keys, or tokens in your code. Use environment variables. If you do accidentally commit a secret, Push Protection will try to block it. If a secret does leak, remember that deleting it is not enough. You must revoke the key at the source and rotate it to a new one.

      -

      Alex: Third, use Code scanning with CodeQL to automatically catch logic flaws and vulnerabilities in your own code before they are merged. It traces untrusted data from the source to the sink.

      -

      Jamie: And finally, if you discover a vulnerability in an open source project, be a good citizen. Never open a public issue. Check the project's SECURITY dot m d file and use the Private Vulnerability Reporting form to disclose it responsibly.

      -

      Alex: Perfectly summarized. In our next episode, episode thirty, we are going to shift gears and talk about GitHub Pages. We will learn how to take a repository and turn it into a live, accessible website hosted directly on GitHub for free. You will not want to miss it. Until then, keep practicing, and we will talk to you soon.

      +

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

      +
      +

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

      - +

      Episode 30: VS Code Accessibility Reference

      Complete accessibility settings, audio signals, diff viewer, and screen reader configs.

      -

      Based on: Appendix M: VS Code Accessibility Reference

      - - -

      Download Episode 30 (MP3)

      +

      Based on: Appendix G: VS Code Accessibility Reference

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 30: VS Code Accessibility Reference

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub, the podcast where we make version control and open source collaboration accessible to everyone. I am Alex, and I am thrilled to be here with you today.

      -

      Jamie: And I am Jamie! I am so excited for this one. We are on episode thirty! Episode thirty, Alex. That feels like a massive milestone.

      -

      Alex: It really is. Today's episode is titled VS Code Accessibility Reference. If you have been following along with our two-day workshop material, you already know the basics of the VS Code interface from our earlier episodes. But today, we are going deep. We are handing you the complete manual.

      -

      Jamie: I love that. When I was learning GitHub about two years ago, I knew enough to get by. I knew how to open a file and type. But I did not understand how to make the editor actually work for me. I was just fighting the default settings every single day.

      -

      Alex: Exactly. And you should not have to fight your tools. Today, we are going to cover every accessibility-related setting in VS Code. We will talk about audio cues, the accessible diff viewer, terminal accessibility, and specific configurations for NVDA, JAWS, and VoiceOver. We will even cover troubleshooting when things go wrong.

      -

      Jamie: Just a quick reminder for our listeners. If you are joining us for the first time, you might want to review our previous episode on VS Code Setup and Accessibility Basics. That will give you the lay of the land. But if you are ready to dive into the deep end of the settings pool, stick right here.

      -

      Alex: Let us jump right in.

      -

      Alex: Everything in VS Code accessibility starts with one master switch. It is a setting called editor dot accessibility support.

      -

      Jamie: The big breaker switch for the house!

      -

      Alex: That is a perfect analogy. Just like the main breaker controls the power to your entire house, the editor dot accessibility support setting controls whether VS Code optimizes its interface for a screen reader. By default, this is set to auto. That means VS Code tries to detect if NVDA, JAWS, or VoiceOver is running when it starts up.

      -

      Jamie: But auto can sometimes fail, right? I remember times when my screen reader updated, or I started VS Code before my screen reader was fully running, and VS Code just acted like it had no idea I needed accessibility features.

      -

      Alex: Exactly. That is why I always recommend changing this setting from auto to on. When you force it to on, VS Code will always provide screen reader optimizations, no matter what.

      -

      Jamie: What actually happens when that switch is flipped on? What are the screen reader mode behavior changes?

      -

      Alex: A few critical things happen behind the scenes. First, it disables the visual minimap. The minimap is a zoomed-out visual outline of your code that sighted developers use to scroll quickly. For a screen reader, it is just useless noise that eats up computer memory. So, screen reader mode turns it off. It also changes how word wrap behaves, ensuring that when your screen reader reads a line of code, it reads the whole logical line, not just what visually fits on the screen.

      -

      Jamie: That is so important. If word wrap is handled visually, your screen reader might pause awkwardly in the middle of a variable name just because the window was resized.

      -

      Alex: Right. And while we are talking about customizing the interface, I want to mention high contrast themes and zoom levels. Even if you rely entirely on a screen reader, or if you are a low-vision developer who uses a combination of screen reading and visual tracking, these are essential.

      -

      Jamie: Oh, absolutely. I have low vision, and before I transitioned to using a screen reader full time, I relied heavily on high contrast. VS Code has built-in high contrast themes. You do not have to download anything extra.

      -

      Alex: Yes, you can open the Command Palette by pressing Control plus Shift plus P on Windows, or Command plus Shift plus P on Mac. Then type Preferences Color Theme. You can navigate through the list, and there are specific themes labeled High Contrast Dark and High Contrast Light. These themes add solid borders around panels and increase text contrast significantly.

      -

      Jamie: And for zoom, you can just press Control plus the Equals sign to zoom in, and Control plus the Dash key to zoom out. Or Command on a Mac. It scales the entire interface, not just the text in the editor. The sidebar, the terminal, the menus, everything gets bigger.

      -

      Alex: It is a huge help. Now, let us move from the visual to the audible. I want to talk about how VS Code communicates with you non-verbally.

      -

      Alex: Let us talk about Audio Cues. VS Code has a brilliant system of sounds that play when certain things happen.

      -

      Jamie: I am obsessed with the audio cues. They completely changed how fast I can write code. When I first started, I had to arrow through every single character of a line to figure out if I made a typo. Now, VS Code just plays a tiny little error chord when my cursor lands on a broken line.

      -

      Alex: That is the perfect way to explain it. Think of audio cues like the dashboard warning lights in your car, but for your ears. Instead of your screen reader verbosely announcing Error on line forty two every single time you arrow past it, you just hear a subtle, quick sound.

      -

      Jamie: What kind of sounds are we talking about?

      -

      Alex: There are dozens of them. They are controlled by settings that start with accessibility dot signals. For example, accessibility dot signals dot line has error. There is a sound for when a terminal task completes successfully, a different sound for when a task fails, and sounds for when you hit a breakpoint in a debugger.

      -

      Jamie: My favorite is the sound for folded code. Sometimes I am navigating a huge file, and I do not realize someone collapsed a massive function. The audio cue lets me know there is hidden code under my cursor.

      -

      Alex: You can configure these cues to be on, off, or auto. Auto means they only play if screen reader mode is active. You can find all of these by opening your Settings with Control plus Comma, or Command plus Comma, and searching for audio cue.

      -

      Jamie: But what if I want the editor to actually speak to me instead of just playing a chime? Like, a chime is great for an error, but what if I need to know exactly what the error is?

      -

      Alex: That brings us to Accessibility Announcements. If audio cues are your dashboard warning lights, accessibility announcements are your GPS voice navigation. They give you the specific text details.

      -

      Jamie: How do we control those? Because sometimes VS Code talks way too much.

      -

      Alex: It really can. The announcements are controlled by settings that start with accessibility dot verbosity. You can set the verbosity for different parts of the editor. For example, accessibility dot verbosity dot hover controls whether your screen reader automatically reads the pop-up information when your cursor lands on a function.

      -

      Jamie: Oh, I always turn that off. Or at least to minimal. If I am just arrowing through my code quickly, I do not want the screen reader to suddenly start reading a massive paragraph of documentation just because my cursor paused for half a second.

      -

      Alex: Exactly. You can set these verbosity settings to verbose, minimal, or off. If you set hover verbosity to off, you can still read that documentation whenever you want. You just press Alt plus F2, or Option plus F2 on Mac. That shortcut opens the Accessible View, which takes whatever visual pop-up is on the screen and puts it into a nice, plain text window that you can navigate at your own pace.

      -

      Jamie: Alt plus F2 is a lifesaver. I use it for reading long error messages, hover documentation, and even Copilot suggestions.

      -

      Alex: Speaking of navigating complex information, we need to talk about the Accessible Diff Viewer. This is arguably the most important feature we will cover today.

      -

      Jamie: Yes! A diff, short for difference, is how Git shows you what changed in a file. It compares the old version to the new version. But visually, diffs are usually displayed side-by-side. The old file is on the left, the new file is on the right, and the changes are highlighted in red and green.

      -

      Alex: Which is an absolute nightmare for a screen reader. If you try to navigate a visual side-by-side diff with a screen reader, you will just hear a jumbled mess of old code and new code mashed together.

      -

      Jamie: So how does the Accessible Diff Viewer fix this?

      -

      Alex: It completely restructures the information. Instead of two columns, it presents the changes as a single, vertical list. To access it, when you are in a diff view, you just press F7.

      -

      Jamie: F7. Got it. And what exactly does it show me?

      -

      Alex: It breaks the file down into what are called hunks. A hunk is just a block of related changes. Let us use an analogy. Imagine you are updating a recipe for chocolate chip cookies. You decide to change the amount of sugar, and you also add a step at the very end to sprinkle sea salt on top.

      -

      Jamie: Sounds delicious.

      -

      Alex: Right? In a visual diff, you would have to scan the whole recipe to find those two changes. But the Accessible Diff Viewer just gives you the hunks. Hunk one shows the sugar change. Hunk two shows the sea salt addition. It skips all the unchanged steps in the middle.

      -

      Jamie: That saves so much time. How does it tell me what was added or removed within that hunk?

      -

      Alex: It prefixes every line. If a line was removed, it announces Removed, or reads a minus sign before the line. If a line was added, it announces Added, or reads a plus sign. It also includes about three lines of unchanged code before and after the change, just to give you context. It will prefix those with Unchanged.

      -

      Jamie: So if I changed the sugar from one cup to two cups, it would say something like: Unchanged: butter. Removed: one cup sugar. Added: two cups sugar. Unchanged: vanilla extract.

      -

      Alex: Exactly like that. And you can jump forward to the next hunk by pressing F7 again, or jump backward by pressing Shift plus F7. It is incredibly efficient.

      -

      Alex: Let us transition to the command line. We need to talk about Terminal accessibility. The integrated terminal in VS Code is where you will run your Git commands, start your servers, and run your tests.

      -

      Jamie: The terminal used to be a really frustrating place for screen reader users. It is essentially a live feed of text that is constantly updating.

      -

      Alex: It was. But VS Code has made massive improvements. There is a setting called terminal dot integrated dot screen reader mode. Just like the editor, you should ensure this is turned on. When it is on, VS Code intercepts the raw terminal output and formats it so your screen reader can navigate it line by line using your standard arrow keys.

      -

      Jamie: One of my favorite settings in the terminal is the terminal bell. It is terminal dot integrated dot enable bell.

      -

      Alex: Yes, explain how you use that.

      -

      Jamie: So, if I run a really long command, like installing a bunch of packages for a project, I do not want to just sit there listening to my screen reader read out hundreds of lines of installation logs. I want to go check my email. When you enable the terminal bell, it is like the ding of a microwave. When the command finishes, it plays a sound. You know exactly when to switch back to VS Code.

      -

      Alex: That is a fantastic productivity tip. And if you ever need to read the output of a command that scrolled way off the screen, you can use that same Alt plus F2 shortcut we mentioned earlier. If your focus is in the terminal, Alt plus F2 opens the Terminal Accessible View, which puts the entire terminal history into a static text editor so you can search it, copy from it, and read it at your own pace.

      -

      Alex: Now we need to get into the weeds a bit. We are going to cover Screen reader-specific configurations. VS Code behaves slightly differently depending on whether you are using NVDA, JAWS, or VoiceOver. Let us start with NVDA on Windows.

      -

      Jamie: I use NVDA. When I first started, I had this weird issue where I would be reading a really long line of code, and suddenly NVDA would just stop reading in the middle of it.

      -

      Alex: That is a very common issue, and it has to do with an NVDA setting, not a VS Code setting. By default, NVDA limits how much text it will read on a single line in Browse Mode. To fix this, you need to open your NVDA Preferences, go to Settings, then Browse Mode. Look for the setting called Maximum length of text on a single line.

      -

      Jamie: And what should I change it to?

      -

      Alex: Change it to ten thousand. That ensures NVDA will read the entire line of code, no matter how long the variable names or string text might be. Also in those NVDA settings, you should check the box for Automatic focus mode for focus changes, and uncheck Automatic focus mode for caret movement.

      -

      Jamie: Why do we do that?

      -

      Alex: Because VS Code is essentially a complex web application running on your desktop. You want NVDA to automatically switch into focus mode when you open a menu or a dialog box, so you can interact with it. But when you are just moving your text cursor, your caret, around the editor, you do not want it constantly flipping modes.

      -

      Jamie: That makes perfect sense. What about JAWS?

      -

      Alex: For JAWS users, the setup is similar. You want to go into the JAWS Settings Center, under HTML, PDF, Accessibility. Make sure Auto Forms Mode is checked.

      -

      Jamie: Is there anything specific for reading code with JAWS?

      -

      Alex: Yes. Under Text Processing in JAWS, there is a setting for Blank Line Announcement. By default, JAWS says the word blank every time you arrow over an empty line. In code, there are a lot of blank lines used for formatting. Hearing the word blank fifty times a day gets exhausting. You can change that setting from Speech to Tone. Then, JAWS will just play a tiny click sound when you hit a blank line.

      -

      Jamie: Oh, I love that. Less talking, more coding. And what about our Mac users on VoiceOver?

      -

      Alex: VoiceOver requires a very specific tweak. You need to open the VoiceOver Utility, go to Navigation, and pay attention to Quick Nav. Quick Nav is a feature that lets you navigate web pages by pressing single letter keys. For example, pressing H jumps to the next heading.

      -

      Jamie: But in a code editor, if I press the letter H, I probably just want to type the letter H!

      -

      Alex: Exactly! If Quick Nav is on while you are in the VS Code editor, you will not be able to type normally. You must ensure Quick Nav is toggled OFF when your focus is in the editor. You can toggle it quickly by pressing the Left and Right arrow keys at the same time.

      -

      Jamie: And what about punctuation? Code is just a giant pile of punctuation.

      -

      Alex: Right. In VoiceOver Utility, under Verbosity, then Text, you should set Punctuation to All. You need to hear every bracket, every semicolon, and every parenthesis. If VoiceOver filters them out to make it sound more like natural English, your code will just not make any sense.

      -

      Alex: Let us talk about moving around. Keyboard-only navigation is the lifeblood of using VS Code with a screen reader.

      -

      Jamie: There are so many shortcuts, but you really only need a handful to get started, right?

      -

      Alex: Exactly. You do not need to memorize the entire dictionary. The most important shortcut, the one that rules them all, is the Command Palette. We mentioned it earlier: Control plus Shift plus P, or Command plus Shift plus P.

      -

      Jamie: If you forget every other shortcut, remember that one. Because you can just type what you want to do. If you want to open a new terminal, just open the Command Palette and type terminal. If you want to format your code, type format.

      -

      Alex: Beyond the Command Palette, you need to know how to navigate between the different parts of the window. VS Code has the main editor area where you type, but it also has a sidebar on the left and a panel on the bottom.

      -

      Jamie: The sidebar is where your file explorer is, right? Where you see all the files in your project.

      -

      Alex: Yes. To jump to the File Explorer in the sidebar, press Control plus Shift plus E. Or Command plus Shift plus E on Mac. To jump to the Source Control view, where you manage your Git commits, press Control plus Shift plus G.

      -

      Jamie: And the panel on the bottom is where the terminal lives.

      -

      Alex: Correct. You can toggle that bottom panel open and closed by pressing Control plus the Backtick key. The backtick is that little key usually right above the Tab key on your keyboard.

      -

      Jamie: What about moving between open files? If I have five files open, how do I switch between them without getting lost?

      -

      Alex: You use Control plus Tab. It works just like switching tabs in a web browser. If you hold down Control and press Tab repeatedly, it will cycle through all your open files. When you hear the name of the file you want, just let go of the keys, and your focus will be right there.

      -

      Jamie: One shortcut I use constantly is Control plus G. Go to line. When I run a test and it says there is an error on line one hundred and fifty, I just press Control plus G, type one five zero, hit Enter, and boom. I am exactly where I need to be.

      -

      Alex: Let us wrap up with a crucial topic: Troubleshooting accessibility issues. Because no matter how perfectly you set things up, eventually, something will get stuck.

      -

      Jamie: Oh, the dreaded silent editor. When you press an arrow key and your screen reader just says nothing. It is terrifying. You feel like you broke everything.

      -

      Alex: It happens to everyone. Usually, what has happened is that your system focus has gotten trapped inside a webview or a custom UI element that does not know how to report its state to the screen reader.

      -

      Jamie: How do we fix it? Do I have to restart my whole computer?

      -

      Alex: No, thankfully. The first thing to try is simply pressing the Escape key a few times. Sometimes a hidden menu is open and stealing focus. If that does not work, try pressing F6. F6 is the shortcut to cycle focus between the main parts of the VS Code window: the editor, the panel, the sidebar, and the activity bar. Often, pressing F6 forces the focus out of whatever trap it was in.

      -

      Jamie: And if it is completely frozen?

      -

      Alex: Then you use the Developer Reload Window command. Open the Command Palette with Control plus Shift plus P, and type Reload Window. Hit Enter. This refreshes the entire VS Code interface without actually closing the application or losing your unsaved work. It takes about two seconds and almost always fixes screen reader sync issues.

      -

      Jamie: Another issue I have run into is the Tab key getting trapped. I will be in the terminal, and I press Tab to autocomplete a file name, but instead, it moves my focus to a completely different button on the screen.

      -

      Alex: That is a feature called Tab Trapping. Sometimes it gets toggled on by accident. If your Tab key stops inserting tabs or autocompleting, press Control plus M. That is Command plus M on Mac. That toggles whether the Tab key moves focus between interface elements, or acts like a normal Tab key inside text areas.

      -

      Alex: We have covered a massive amount of ground today. Jamie, what are your top takeaways for our listeners?

      -

      Jamie: First, definitely make sure editor dot accessibility support is set to On, not auto. Do not leave it up to chance. Second, configure your screen reader properly! Change that NVDA line length to ten thousand, or turn off Quick Nav in VoiceOver. Your editor can only do so much if your screen reader is fighting it.

      -

      Alex: Excellent points. I will add a third: Embrace the Accessible Diff Viewer. Press F7 when you are reviewing code changes. Stop trying to read visual side-by-side diffs with a screen reader. And finally, use Alt plus F2 to open the Accessible View anytime you need to read a hover message, an error, or terminal output clearly.

      -

      Jamie: This really is the ultimate reference guide. I wish I had this episode two years ago.

      -

      Alex: All of the settings, JSON configurations, and shortcuts we discussed today are available in Appendix M of your workshop materials. You do not have to memorize them from this audio; they are all written down for you to copy and paste.

      -

      Jamie: What are we covering next time?

      -

      Alex: In our next episode, we are moving from editor configuration to pure magic. We are going to tackle GitHub Copilot. We will explain how to use artificial intelligence to write code, and most importantly, how to navigate and review AI suggestions accessibly using your screen reader.

      -

      Jamie: Oh, that is going to be incredible. Copilot is a game changer. I cannot wait.

      -

      Alex: Until then, keep exploring your settings, customize your audio cues, and we will see you next time on Gitt Going with GitHub.

      +

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

      +
      +

      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").

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      - +

      Episode 31: GitHub Codespaces

      Cloud dev environments, accessibility setup, and screen reader usage.

      -

      Based on: Appendix N: GitHub Codespaces

      - - -

      Download Episode 31 (MP3)

      +

      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 Gitt Going with GitHub. This is episode 31, GitHub Codespaces. I am Alex, and I am so glad you are joining us today as we continue our journey through accessible development and open source collaboration.

      -

      Jamie: And I am Jamie. I am a developer who learned GitHub about two years ago, and I am here to ask all the questions that you are probably thinking right now. I remember exactly what it felt like to be overwhelmed by all this terminology, so we are going to break it down together.

      -

      Alex: Today we are diving into a feature that completely changed how I teach development, and honestly, how I write code myself. We are talking about GitHub Codespaces. Before we jump in, let us quickly remind ourselves of our prerequisites. In our previous episodes, we covered the basic layout of Visual Studio Code, or VS Code, and we talked about fundamental Git commands like commit and push. You will be using all of that today.

      -

      Jamie: Okay, so GitHub Codespaces. I hear this term thrown around a lot in workshops and open source projects. What exactly is a Codespace? Because when I first heard the word, I thought it was some kind of social network for developers.

      -

      Alex: That would be interesting, but no. A Codespace is a cloud hosted development environment. Let us define that. A development environment is everything you need to write, run, and test your code. It is your code editor, your programming languages, your debugging tools, all of it. Historically, you had to install all of this directly onto your own computer.

      -

      Jamie: Right, and I have nightmares about that from when I was learning. I remember spending three days just trying to get Python, Node, and Ruby installed on my computer. I kept messing up my system paths, my screen reader was reading me endless error messages in the terminal, and I had not even written a single line of code yet. It was incredibly frustrating.

      -

      Alex: That is exactly the problem Codespaces solves. When we say it is cloud hosted, we mean GitHub creates a virtual machine, which is basically a computer running in a massive data center somewhere, and they set up all those tools for you. Then, they connect your code editor to that remote computer over the internet.

      -

      Jamie: So I love a good analogy. Is it kind of like renting a fully furnished workshop?

      -

      Alex: That is a perfect analogy. Imagine you want to build a table. You could spend weeks buying a saw, a drill, a workbench, and clearing out space in your garage. That is local development. Or, you could just rent a workshop that already has all the tools laid out on the bench, perfectly tuned and ready to go. You just walk in and start building. That is a Codespace.

      -

      Jamie: That sounds amazing. And because it is in the cloud, does that mean I do not need a super powerful computer to use it?

      -

      Alex: Exactly. This is one of the biggest benefits, especially for accessibility and inclusion. We call this developing on low end devices. Because the heavy lifting, the compiling, the running of the code, is all happening on GitHub servers, your computer is just acting as the display and keyboard. You could run a massive, complex project on an old, inexpensive laptop. You can even run Codespaces on mobile devices.

      -

      Jamie: Wait, really? Like an iPad or a smartphone?

      -

      Alex: Yes. If you pair a Bluetooth keyboard with a tablet, you can open a Codespace in your mobile web browser and have a full desktop class coding environment. The screen reader on your tablet will interact with the web interface. It is incredibly freeing to know you are not chained to a high end machine.

      -

      Jamie: Okay, I am sold on the concept. How do I actually create one? Let us say I am on a repository page on GitHub.

      -

      Alex: The process is very straightforward, but it requires navigating a few specific buttons. When you are on the main page of a repository, you want to navigate to the Code button. There is no direct keyboard shortcut to jump exactly to this button, so you will typically use your screen reader to navigate by buttons, or simply press Tab until you reach it.

      -

      Jamie: Got it. So I press Enter or Space to activate the Code button. What happens next?

      -

      Alex: A panel opens up. Inside this panel, there are usually two tabs. One is called Local, which is for cloning the code to your own computer. The other is called Codespaces. You want to use your arrow keys to select the Codespaces tab. Once you are in that tab, you will find a button called Create codespace on main. Main being the name of the default branch.

      -

      Jamie: Okay, I activate that button. What is the startup experience like? Because you said it is setting up a whole computer for me. That cannot be instant, right?

      -

      Alex: You are correct, it is not instant. When you activate that button, a new browser tab opens. This is where the provisioning happens. Provisioning is just a technical term for allocating the computer and getting it ready.

      -

      Jamie: What is happening behind the scenes during that time?

      -

      Alex: A few things. First, GitHub finds an available virtual machine. Next, it clones the repository you were just looking at directly into that machine. Then, it installs any tools that the project specifically requested. Finally, it starts up the VS Code interface. This whole process usually takes between thirty and ninety seconds.

      -

      Jamie: Ninety seconds to set up a whole environment? I will take that over three days of installing Python any day. While it is loading, does my screen reader tell me what is happening?

      -

      Alex: It does. The page has live regions that announce the progress, like connecting, or setting up environment. Once it finishes, focus automatically shifts into the VS Code editor.

      -

      Jamie: You mentioned a moment ago that GitHub installs the tools the project specifically requested. How does GitHub know what tools the project needs?

      -

      Alex: That is a brilliant question. This brings us to a concept called the dev container. The word dev is short for development. When you start a Codespace, GitHub looks inside your repository for a specific file. It looks in a folder called dot dev container, and inside that folder, it looks for a file called dev container dot json.

      -

      Jamie: Let me guess, json stands for JavaScript Object Notation, which is just a way of formatting data.

      -

      Alex: Exactly. The dev container dot json file is essentially the blueprint for your workshop. It is a text file that tells GitHub exactly how to build the environment.

      -

      Jamie: Can you give me an example of what goes into that blueprint?

      -

      Alex: Sure. Let us say you are working on a web project that needs a specific version of Node JS, and you want all the developers on your team to use an accessibility linting extension to catch errors. You write those requirements into the dev container dot json file. When anyone on your team creates a Codespace, GitHub reads that file, installs that exact version of Node, and pre installs the accessibility extension.

      -

      Jamie: Oh, that is clever! So it eliminates that classic developer excuse of, well, it works on my machine.

      -

      Alex: Precisely. It works exactly the same on everyone's machine, because everyone is using the exact same blueprint. This is especially amazing for workshops. As an instructor, I know that every single student has the exact same setup. Nobody is falling behind because their local environment is broken.

      -

      Jamie: Okay, so the Codespace has loaded. I am sitting in a browser tab. What does it actually look and feel like to my screen reader? Is it a stripped down version of VS Code?

      -

      Alex: Not at all. It is the full VS Code interface, running directly in your browser. It works in Chrome, Edge, Firefox, and Safari. For screen reader users, Chrome and Edge tend to offer the most consistent behavior with NVDA and JAWS.

      -

      Jamie: I remember the first time I used VS Code in the browser, I was worried my screen reader commands would conflict with the browser commands. How does accessibility in Codespaces work?

      -

      Alex: That is a very common concern. The great news is that VS Code is highly optimized for this. When VS Code in the browser detects a screen reader, it automatically activates a feature called Screen Reader Optimized Mode.

      -

      Jamie: What does that mode actually do?

      -

      Alex: It makes several crucial changes under the hood. For example, normally, a code editor might present text in a way that forces your screen reader to read character by character, which is incredibly tedious. Screen Reader Optimized Mode ensures the editor content is presented as a proper text area, allowing you to read line by line seamlessly. It also changes how things like code suggestions and differences between files are announced, making them much more friendly for audio output.

      -

      Jamie: What if it does not detect my screen reader automatically? Can I turn it on myself?

      -

      Alex: Yes, absolutely. You can use the Command Palette. We talked about this in a previous episode. You press Control plus Shift plus P. This opens a search field. You just type the word Toggle, and then the words Screen Reader Accessibility Mode. Press Enter, and it will turn on manually.

      -

      Jamie: Control plus Shift plus P. I use that shortcut probably fifty times a day. Okay, what about audio cues? I rely heavily on those little sounds VS Code makes when I hit an error or a breakpoint. Do those work in the browser?

      -

      Alex: They do. VS Code in Codespaces supports the exact same audio cues as the desktop version. You will hear a specific tone if your cursor lands on a line with an error, a different tone for a warning, and a little chime when a background task completes. The only catch is that sometimes modern web browsers mute audio for new tabs by default. If you are not hearing the cues, you might need to check your browser permissions and ensure that github dot com is allowed to play sound.

      -

      Jamie: Let us talk about the terminal. The terminal is where I run my commands, and it can be notoriously tricky with screen readers. How does the integrated terminal work in a Codespace?

      -

      Alex: It is a standard terminal, but navigating it requires a bit of technique. When you press Control plus grave accent to open the terminal, your focus moves into the terminal input area. The grave accent is the key usually located just above the Tab key on an American keyboard.

      -

      Jamie: Right. And when I type a command, like running a test script, a bunch of text usually flies up the screen. How do I read that?

      -

      Alex: This is where you need to understand your screen reader modes. If you are using NVDA or JAWS, your screen reader has two main modes. Focus Mode, which passes your keystrokes directly to the application so you can type, and Browse Mode, or Virtual Cursor in JAWS, which intercepts your keystrokes so you can read the screen like a document.

      -

      Jamie: So when I am typing the command, I need to be in Focus Mode.

      -

      Alex: Correct. But once the output arrives, you need to manually switch to Browse Mode. For NVDA, you press Insert plus Space. For JAWS, you press Insert plus Z. Once in Browse Mode, you can use your standard arrow keys to read the terminal output line by line. When you are ready to type your next command, you switch back to Focus Mode.

      -

      Jamie: I wish I had known that when I started. I used to just arrow up and down in Focus Mode and it would just cycle through my previous commands instead of reading the output.

      -

      Alex: That is a very common mistake! But VS Code also offers another brilliant feature called Accessible View. If you are in the terminal and you want to review the output without messing with screen reader modes, you can press Alt plus F2.

      -

      Jamie: Alt plus F2. What does that do?

      -

      Alex: It takes the entire output of the terminal and opens it in a temporary text editor buffer. You can read it, search through it, and navigate it exactly like you would a normal code file. When you are done reading, you just press Escape, and you are right back in the terminal input.

      -

      Jamie: Oh, that is huge. Alt plus F2. I am writing that down.

      -

      Alex: Now, we have been talking about using Codespaces in the web browser. But you do not actually have to use the browser. You can connect to a cloud Codespace using your local installation of VS Code on your computer.

      -

      Jamie: Wait, really? Why would I do that if the browser version works so well?

      -

      Alex: A few reasons. First, muscle memory. You might have your local screen reader settings, your keyboard shortcuts, and your operating system commands dialed in perfectly. Second, some VS Code extensions are not compatible with the web browser version. They require a native desktop environment to run.

      -

      Jamie: Okay, that makes sense. How do I connect my local VS Code to the cloud Codespace?

      -

      Alex: You need to install an extension in your local VS Code called GitHub Codespaces. Once that is installed, you open your Command Palette with Control plus Shift plus P. You search for the command Codespaces colon Connect to Codespace. It will ask you to sign into GitHub if you haven't already, and then it will show you a list of your running Codespaces. You pick one, and your local VS Code window refreshes.

      -

      Jamie: And at that point, I am typing in my local app, but the files are in the cloud?

      -

      Alex: Exactly. Your screen reader is interacting with your local desktop application, which is usually faster and more responsive, but all the heavy lifting, the terminal commands, the file saving, is happening on the GitHub server. It is the best of both worlds.

      -

      Jamie: Let us shift gears to something that always confused me. When I am developing locally, and I write a simple website, I usually run a command to start a local web server. Then I go to my browser and type local host colon three thousand to preview my site. But if my code is running on a cloud server in a Codespace, how do I preview my website?

      -

      Alex: That is a fantastic question, and it brings us to a concept called port forwarding.

      -

      Jamie: Port forwarding. Okay, define that for me.

      -

      Alex: Let us use an analogy. Imagine your Codespace is a secure vault on an island. Inside the vault, your website is running on a specific port, say, port three thousand. But you are on the mainland. You cannot just walk in. Port forwarding creates a secure, temporary tunnel from the vault on the island directly to your local computer.

      -

      Jamie: So it forwards the traffic from the cloud to me. How do I set up this tunnel? Does it require complex network configurations?

      -

      Alex: Thankfully, no. VS Code handles it automatically. When you run your web server command in the Codespace terminal, VS Code detects that a server has started. It automatically creates the secure tunnel. You will usually hear a notification from your screen reader saying a port has been forwarded.

      -

      Jamie: And how do I actually open the website to test it?

      -

      Alex: When the notification pops up, it usually includes a button to Open in Browser. If you miss the notification, which is easy to do, you can open the Command Palette with Control plus Shift plus P, and search for the command Ports colon Focus on Ports View. This opens a panel listing all your forwarded ports, and you can simply press Enter on the one you want to open. GitHub assigns it a unique, secure URL that only you can access.

      -

      Jamie: Okay, this all sounds incredibly powerful, which leads me to my next logical question. How much does this cost? Because renting a cloud computer cannot be free forever.

      -

      Alex: You are right, but GitHub provides a very generous free tier for personal accounts. Every month, you get a certain allowance of free compute hours and storage. For most workshop participants and open source contributors doing casual development, you will comfortably stay within this free usage limit.

      -

      Jamie: What happens if I forget to close my Codespace? Will it just run forever and drain my free hours?

      -

      Alex: No, they have thought of that. By default, if you are inactive for thirty minutes, meaning you have not typed anything or run any commands, the Codespace will automatically stop itself.

      -

      Jamie: What is the difference between stopping a Codespace and deleting a Codespace?

      -

      Alex: Think of stopping a Codespace like pressing pause on a movie, or putting your laptop to sleep. The virtual machine shuts down, and you stop using compute hours. However, your files, your uncommitted changes, and your terminal history are all saved on a hard drive. You are still using a tiny amount of your storage allowance, but the computer is off.

      -

      Jamie: And deleting it?

      -

      Alex: Deleting it is throwing the computer in the trash. The virtual machine is destroyed, and the storage is wiped clean. If you have uncommitted changes or code you haven't pushed to GitHub, it is gone forever.

      -

      Jamie: Okay, note to self. Always commit and push my work before deleting a Codespace. How do I manually manage these states? Let us say I am done for the day and I want to stop it manually.

      -

      Alex: You navigate to github dot com slash codespaces. This is your dashboard. It displays a list of all your active and stopped Codespaces. You can use your screen reader to navigate through the list. Next to each Codespace, there is an options menu, often labeled with an ellipsis, or simply announced as an action menu. If you activate that menu, you will find options to Stop codespace, or Delete.

      -

      Jamie: And if I want to resume one that is stopped?

      -

      Alex: From that same dashboard, you just navigate to the stopped Codespace and activate the button that says Open in. It will spin up the machine again, and in a few seconds, you are right back where you left off.

      -

      Jamie: Before we wrap up, I have seen another feature called GitHub dot dev. You just press the period key on any repository and a browser editor opens. Is that the same thing as a Codespace?

      -

      Alex: That is a great clarification. No, they are different. GitHub dot dev is a lightweight editor. When you press the period key, it opens VS Code in your browser, but it does not create a virtual machine. There is no compute power behind it.

      -

      Jamie: So what does that mean in practice?

      -

      Alex: It means you cannot run code. There is no terminal. You cannot run a local web server, and you cannot run tests. It is entirely powered by your browser.

      -

      Jamie: When would I use GitHub dot dev instead of a Codespace?

      -

      Alex: GitHub dot dev is perfect for quick edits. If you spot a typo in a documentation file, or you want to read through the code of a project without waiting ninety seconds for a Codespace to provision, you press the period key. It opens instantly. You make your text edit, commit, and you are done. Plus, GitHub dot dev is completely free and unlimited.

      -

      Jamie: Got it. So GitHub dot dev is for quick edits and reading, and Codespaces is for serious development where I need a terminal and a running environment.

      -

      Alex: Exactly.

      -

      Alex: We have covered a massive amount of ground today. Let us recap our key takeaways. First, a Codespace is a cloud hosted virtual machine running VS Code, giving you a full, pre configured development environment without installing anything locally.

      -

      Jamie: Second, the environment is defined by a blueprint called dev container dot json, which ensures everyone working on the project has the exact same tools and extensions. No more dependency nightmares!

      -

      Alex: Third, accessibility is built in. You can use Codespaces in your browser with Screen Reader Optimized Mode, or you can connect your local desktop VS Code directly to the cloud machine for maximum familiarity.

      -

      Jamie: And finally, port forwarding acts as a secure tunnel, letting you preview web apps running in the cloud right on your local machine. Just remember to commit and push your work before you delete your Codespace from the dashboard.

      -

      Alex: Perfect summary. In our next episode, we are going to dive into branching strategies. We will talk about how multiple people can work on the exact same files at the exact same time without overwriting each other's work. It is where the true magic of Git collaboration happens.

      -

      Jamie: I cannot wait for that one. Thank you all for listening, and we will catch you in the next episode!

      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      - +

      Episode 32: GitHub Mobile

      VoiceOver and TalkBack guide for iOS and Android GitHub apps.

      -

      Based on: Appendix O: GitHub Mobile

      - - -

      Download Episode 32 (MP3)

      +

      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 Gitt Going with GitHub. This is Episode 32, called GitHub Mobile. I am Alex, and I am so glad you are joining us today.

      -

      Jamie: And I am Jamie! If you have been following along with our two-day workshop series, you have already learned how to navigate repositories, open issues, and manage pull requests using the desktop website and VS Code. But today, we are taking GitHub on the go.

      -

      Alex: Exactly. Before we dive in, let us do a quick refresher on our prerequisites. We will be talking a lot about issues and pull requests today. As a reminder, an issue is essentially a tracking ticket for a bug you need to fix or a new feature you want to build. And a pull request, which is my favorite term because you are literally requesting that someone pull your code changes into their project, is how you propose updates to a repository.

      -

      Jamie: If you are comfortable with those concepts, you are perfectly ready for this episode. And I have to say, Alex, I am really excited about this one. When I first learned GitHub about two years ago, I thought I was chained to my computer. If someone asked me to review their code, I felt like I had to drop everything, run home, and open my laptop.

      -

      Alex: That is a very common feeling. And that is exactly why GitHub Mobile exists. We are going to cover what the app offers, how to install it on iOS and Android, and how to navigate it using VoiceOver and TalkBack. We will talk through viewing notifications, reading issues, reviewing pull requests, and browsing code. Finally, we will discuss some current accessibility limitations and when it makes sense to use mobile versus your desktop.

      -

      Alex: Let us start with what GitHub Mobile actually is. It is an official app available for both iOS and Android devices. You can download it by opening the App Store on your iPhone or iPad, or the Google Play Store on your Android device, and searching for GitHub.

      -

      Jamie: And just to be clear, because this confused me at first, GitHub Mobile is not a code editor. You are not going to be typing out hundreds of lines of Python or JavaScript on your phone screen.

      -

      Alex: That is a great point. Think of GitHub Mobile like a walkie-talkie and a clipboard for your project, rather than your actual drafting table. It is designed for communication, project management, and review. The core features are triaging notifications, reading and replying to issues, reviewing pull requests, and doing some light code browsing.

      -

      Jamie: Triaging notifications is my absolute favorite part. Triage just means sorting things by priority, figuring out what needs your attention right now versus what can wait.

      -

      Alex: Yes, and after you install the app and sign in with your GitHub account, the app will prompt you to enable notifications. I highly recommend allowing this. It is the best way to stay on top of review requests and mentions without constantly refreshing your email or the GitHub website.

      -

      Jamie: OK, so I have downloaded the app, I have signed in, and I have allowed notifications. What does the app actually consist of?

      -

      Alex: The app is organized around a main navigation bar containing five tabs. There is the Home tab, which is a personalized feed of activity across all the repositories you watch. A repository, as a quick reminder, is just the project folder where all the files and history live.

      -

      Jamie: Then there is the Notifications tab, which we will talk a lot about. There is an Explore tab to discover new projects. The Pull Requests tab, which collects all the pull requests assigned to you or created by you. And finally, the Profile tab for your personal settings.

      -

      Alex: You can move between these tabs by navigating to them and activating them, just like any other standard app on your phone. But before we get into the specific features, we need to talk about how to actually get around the app using screen readers.

      -

      Alex: Let us talk about iOS and VoiceOver first. If you are using an iPhone or iPad, you likely already know that you can toggle VoiceOver on by triple-clicking the side button on newer phones, or the Home button on older ones. You can also turn it on by navigating to Settings, then Accessibility, then VoiceOver.

      -

      Jamie: When I open GitHub Mobile with VoiceOver running, how do I move around? Is it any different from Safari or Mail?

      -

      Alex: It is very similar. The basic gestures apply. You swipe right with one finger to move your focus to the next element, and swipe left to move to the previous element. When you hear the item you want, you double-tap anywhere on the screen to activate it.

      -

      Jamie: What if I open a really long issue description and I just want VoiceOver to read the whole thing to me while I listen?

      -

      Alex: Great question. You can use a two-finger swipe up to read from the very first item, or a two-finger swipe down to read continuously from your current focus point. If you need to pause the speech because someone asks you a question, just do a two-finger single tap. Another two-finger tap will resume the speech.

      -

      Jamie: I use the two-finger tap all the time. It is a lifesaver. But what about navigating complex screens? Like, sometimes an issue has a lot of comments, and swiping through every single timestamp and author name takes forever.

      -

      Alex: This is where the VoiceOver Rotor becomes your best friend. The Rotor is a feature that lets you change how your up and down swipes behave. Think of it like a physical combination dial on a safe. You place two fingers on the screen and rotate them clockwise or counter-clockwise. As you turn this invisible dial, VoiceOver will announce different settings.

      -

      Jamie: So I twist my fingers on the screen, and I might hear it say "Characters," "Words," "Headings," "Links."

      -

      Alex: Exactly. For GitHub Mobile, the most useful Rotor settings are Headings, Links, and Form Controls. If you select Headings on your Rotor, you can then just swipe down with one finger to jump directly from the issue description, to the first comment, to the second comment, completely skipping all the clutter in between.

      -

      Jamie: Oh, that is clever! I wish I had known that when I started. It is like skipping from chapter title to chapter title in an audiobook instead of fast-forwarding through every word.

      -

      Alex: That is a perfect analogy. You will also use the Form Controls option on the Rotor quite a bit. When you want to leave a comment on a pull request, selecting Form Controls and swiping down will jump your focus straight to the text input field, so you do not have to hunt for it.

      -

      Jamie: OK, but what if I am on an Android device? I know we have a lot of Android users in the workshop who use TalkBack.

      -

      Alex: Absolutely. TalkBack is the built-in screen reader for Android. You can usually turn it on by holding both volume keys for three seconds, or by navigating to Settings, then Accessibility, then TalkBack.

      -

      Jamie: Are the gestures the same as VoiceOver?

      -

      Alex: Many of them are! You still swipe right with one finger to move to the next element, swipe left for the previous element, and double-tap to activate whatever is currently in focus.

      -

      Jamie: What about scrolling? If a screen is really long, how do I move down?

      -

      Alex: With TalkBack, you can scroll down by using a two-finger swipe up, which pushes the content up so you can access what is below. Or, if you prefer the single-finger gestures, you can swipe up then immediately down in one fluid motion to scroll forward. To go back to the previous screen, you can swipe right then left.

      -

      Jamie: And does TalkBack have something like the VoiceOver Rotor for jumping around quickly?

      -

      Alex: It handles this slightly differently, through reading controls and the TalkBack menu. You can swipe up or down with one finger to cycle through your reading granularity, changing it to characters, words, lines, or paragraphs.

      -

      Jamie: So I can set it to paragraphs and swipe right to jump a whole paragraph at a time?

      -

      Alex: Exactly. You can also open the global TalkBack menu by tapping the screen with three fingers, or by swiping down then right. This menu lets you activate specific reading controls or even copy text from an issue description, which is incredibly useful if you need to copy an error message someone posted.

      -

      Jamie: One thing I love doing on Android is Explore by Touch.

      -

      Alex: Yes, Explore by Touch is fantastic on GitHub Mobile. Instead of swiping sequentially through every item, you just drag one finger slowly across the glass of your screen. TalkBack will announce whatever is underneath your finger. It is exactly like reading a tactile map with your hands. Once you learn the general layout of the app, dragging your finger directly to the tab bar is much faster than swiping fifty times to get there.

      -

      Jamie: So now that we know how to move around, let us talk about the feature I use the most. The Notifications tab.

      -

      Alex: I will go a step further, Jamie. I think the Notifications tab on GitHub Mobile is one of the strongest accessibility features GitHub has ever built. For screen reader users, the mobile notification experience is often much better than the desktop web version.

      -

      Jamie: I completely agree. On the website, notifications can feel overwhelming. They are grouped in these complex tables, and sometimes it is hard to figure out why you are even being notified.

      -

      Alex: But on mobile, your notifications are presented as a clean, simple, linear list. It is just one item after another. And the true power comes from the swipe actions.

      -

      Jamie: Right! This is my mail sorting analogy. Imagine you have a massive stack of physical mail. You pick up an envelope, decide what to do with it, and throw it into a bucket. Keep, trash, or read later.

      -

      Alex: Exactly. When your focus is on a notification in the list, you can use the custom actions in your screen reader. On VoiceOver, you swipe up or down when focused on a notification to hear the available actions. On TalkBack, you can use the action menu.

      -

      Jamie: You can mark it as read, archive it, or even unsubscribe from the conversation entirely if it is getting too noisy. You never even have to open the issue to clear it from your inbox.

      -

      Alex: And if you do want to read it, just double-tap the notification. It will open the full issue or pull request right there.

      -

      Jamie: There is also a really great filter feature, right?

      -

      Alex: Yes. If you navigate to the filter button on the notifications screen, it opens a panel with accessible form controls. You can filter your notifications by type, so you only hear about Pull Requests, or only hear about Issues. You can also filter by reason. For example, you can choose to only see notifications where someone directly at-mentioned your username, or where someone explicitly requested your review.

      -

      Jamie: That is a lifesaver when you are working on a massive open-source project and there are hundreds of notifications a day. You just filter by "Review Requested," handle those three items, and get on with your day.

      -

      Alex: Let us talk about what happens when you actually open an issue. Remember, an issue is where conversations happen about bugs or new ideas.

      -

      Jamie: Filing an issue on mobile is surprisingly easy. You navigate to the repository you want, activate the Issues tab, and navigate to the New Issue button.

      -

      Alex: When you activate that, you are presented with a simple form. There is a text field for the title, and a larger text field for the body of the issue. You also have buttons to assign labels, add assignees, or attach it to a milestone.

      -

      Jamie: OK, that sounds like a lot of steps.

      -

      Alex: It does! But here is the thing, you have already done most of this on Day 1 of the workshop. It is the exact same workflow as the website, just presented in a single, vertical column. You type your title, type your description, and activate the Submit button.

      -

      Jamie: Writing comments is where I used to get tripped up, though. I would activate the comment field, the on-screen keyboard would pop up, I would dictate my message, and then I could not find the submit button to actually post it.

      -

      Alex: That is a very common point of friction, and it has to do with how mobile operating systems handle keyboards. When the keyboard appears, it takes up nearly half of your screen, often covering the buttons underneath it.

      -

      Jamie: Exactly! I would swipe right, and suddenly I am just tabbing through my keyboard letters. Q, W, E, R, T, Y.

      -

      Alex: The workaround here is to dismiss the keyboard first, or scroll past it. On iOS, you can sometimes touch an empty area of the screen above the keyboard to dismiss it, or swipe down with two fingers to hide it. Once the keyboard drops out of the way, the Comment button is right there waiting for you.

      -

      Jamie: On Android, I usually just use the system back gesture, which is swiping right then left. That hides the keyboard, and then I can swipe right to find the Comment button. It feels natural once you do it a few times, but the first time it happens, it is definitely confusing.

      -

      Alex: Now let us move on to pull requests. This is where GitHub Mobile really shines for developers on the go.

      -

      Jamie: A pull request, just to recap, is when someone says, "Hey, I wrote some code, and I want to merge it into the main project." And usually, they need someone else to review it and approve it first.

      -

      Alex: Exactly. Mobile is fantastic for quick pull request reviews. Imagine you are waiting for a bus, or sitting in a coffee shop without your laptop, and a teammate messages you saying they fixed a typo and need a quick approval. You can do that entirely from your phone.

      -

      Jamie: When I open a pull request on the app, how is it structured?

      -

      Alex: The screen is divided into clear sections, which your screen reader will announce as headings. There is the Description heading, which contains the summary the author wrote. Then there is a Commits heading, showing the individual history of changes. Then there is Files Changed, which is where you actually look at the code. And finally, a Checks heading, which tells you if the automated tests passed or failed.

      -

      Jamie: I want to talk about the Files Changed section, because this is my other favorite accessibility feature. On the desktop website, looking at a diff, which is the difference between the old code and the new code, can be a nightmare with a screen reader.

      -

      Alex: It really can. The web version often uses complex, multi-column tables. One column for the old line number, one for the new line number, one for the old code, one for the new code. It is very difficult to parse by ear.

      -

      Jamie: But on the mobile app, the diff is simplified! It is just a text list.

      -

      Alex: Yes, this is a huge advantage. Because phone screens are narrow, GitHub Mobile strips away the complex table layout. Instead, each changed line of code is presented as a single item. Your screen reader simply announces "Added" followed by the new code, or "Removed" followed by the old code.

      -

      Jamie: It is so much cleaner. If someone changed a color value, my screen reader just says, "Removed: background blue. Added: background black." It is incredibly easy to understand.

      -

      Alex: Once you have reviewed those changes, you can leave your review. You navigate to the Review Changes button and activate it. This opens a panel where you can choose to Approve the pull request, Request Changes if something is wrong, or just leave a general Comment. You can type an optional message, and then activate the Submit Review button.

      -

      Jamie: What about just browsing code? Sometimes I want to look up how a specific function was written, but I am not reviewing a pull request. Can I do that?

      -

      Alex: You can. If you navigate to any repository, there is an option to browse the code. You can move through the folders and open individual files to read them.

      -

      Jamie: But this goes back to our earlier point. It is like reading the table of contents of a cookbook, and maybe reading a single recipe. You are not going to rewrite the recipe from your phone.

      -

      Alex: Exactly. You can read the code, but there is no syntax highlighting, and more importantly, you cannot edit the files directly in the app. If you need to write code, you need to use a desktop environment or a cloud tool like GitHub Codespaces.

      -

      Alex: Before we wrap up, we need to be honest about the current accessibility limitations of GitHub Mobile. While it is a fantastic tool, it is not perfect.

      -

      Jamie: Yeah, I have definitely run into a few quirks. Sometimes, if a pull request description is really long and has complex formatting, like embedded videos or large markdown tables, VoiceOver just sort of skips over it or reads it in a very confusing order.

      -

      Alex: That is a known issue. Complex markdown parsing on mobile screen readers can be tricky. The best workaround for this is to open the pull request in your mobile browser instead. You can navigate to the More Options menu, which is usually labeled as a button with three dots, and activate Open in Browser. Safari or Chrome will often read complex web layouts better than the native app view.

      -

      Jamie: I have also noticed a quirk with TalkBack on Android regarding the notification badges. You know how apps have a little number telling you how many unread items you have?

      -

      Alex: Yes, the badge count.

      -

      Jamie: Sometimes TalkBack does not announce when that badge count updates live. I will be on the Home tab, and a new notification will come in, but TalkBack will not say anything about it.

      -

      Alex: That is true. The visual badge updates, but the accessibility event does not always fire. To get the current, accurate count read aloud, you need to explicitly navigate your focus to the Notifications tab itself.

      -

      Jamie: And of course, there is the occasional app freeze.

      -

      Alex: Yes, like any app, GitHub Mobile can occasionally freeze or crash. If your screen reader suddenly stops responding while inside the app, the best step is to force close the application. On iOS, you swipe up from the bottom edge and hold to open the app switcher, then swipe up on GitHub to close it. On Android, you open your recent apps and swipe it away. Then just reopen it. If it keeps happening, you can navigate to your Profile, open Settings, and sign out, then sign back in.

      -

      Jamie: So, comparing mobile to desktop, what is the final verdict?

      -

      Alex: It comes down to using the right tool for the job. Think of GitHub Mobile as a Swiss Army knife, and your desktop computer as a full workshop. The mobile app is absolutely excellent for triaging notifications. The linear list and swipe actions are superior to the desktop web experience.

      -

      Jamie: It is also great for quick pull request approvals, leaving simple comments, or checking if your automated tests passed while you are making lunch.

      -

      Alex: But for writing long, detailed pull request descriptions, reviewing massive code diffs with hundreds of changed files, or dealing with complex issue templates, you are going to have a much better time on your desktop using your physical keyboard.

      -

      Jamie: And of course, for actually writing and editing code, desktop is the only way to go.

      -

      Alex: That brings us to the end of Episode 32. Let us recap our main takeaways.

      -

      Jamie: First, GitHub Mobile is an incredibly powerful companion app for iOS and Android, designed for project communication, not for writing code.

      -

      Alex: Second, the app fully supports VoiceOver and TalkBack. Mastering tools like the VoiceOver Rotor or TalkBack reading controls will make navigating complex issues much faster.

      -

      Jamie: Third, the Notifications tab is a game changer. Use the swipe actions to quickly triage your inbox, just like sorting physical mail.

      -

      Alex: And finally, the simplified, linear code diffs on mobile are highly accessible. They announce "Added" or "Removed" sequentially, making quick code reviews by ear much easier than wrestling with web-based tables.

      -

      Jamie: I am definitely going to be doing more PR reviews from my couch now.

      -

      Alex: That is the spirit. In our next episode, Episode 33, we will be pivoting back to the desktop to explore GitHub Actions. We will learn how to automate our workflows, run tests automatically, and make the robots do the heavy lifting for us.

      -

      Jamie: I cannot wait to automate everything! Thanks for listening, everyone.

      -

      Alex: Keep practicing with the mobile app, and we will see you in the next episode. Happy coding!

      +

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

      +
      +

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

      +
      +

      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.

      - +

      Episode 33: Publishing with GitHub Pages

      Free static site hosting, custom domains, HTTPS, and accessibility.

      -

      Based on: Appendix P: Publishing with GitHub Pages

      - - -

      Download Episode 33 (MP3)

      +

      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 to Gitt Going with GitHub.

      -

      Jamie: The audio series for blind and low-vision developers learning GitHub and open source collaboration.

      -

      Alex: I am Alex, and I am thrilled to be here with you today.

      -

      Jamie: And I am Jamie. I am ready to learn, and I have my usual list of questions.

      -

      Alex: This is episode 33, Publishing with GitHub Pages. Today, we are taking all that Markdown and code you have been writing and turning it into a live, public website. Free of charge, directly from your repository.

      -

      Jamie: I remember when I first learned about this. I had been paying ten dollars a month for a basic web host just to put my resume online. When someone told me GitHub would host it for free, I honestly did not believe them.

      -

      Alex: It is one of the best kept secrets for beginners, though it is incredibly popular once you know about it. Before we dive in, let us do a quick check on prerequisites. For this episode, you will want to be comfortable with basic git concepts like making commits and working with branches, which we covered back in episode 4. You should also be familiar with writing Markdown, from episode 12.

      -

      Jamie: So, Alex, let us start at the very beginning. What exactly is GitHub Pages?

      -

      Alex: GitHub Pages is a static site hosting service built directly into GitHub. It takes the files from a specific branch or folder in your repository and serves them to the internet as a website.

      -

      Jamie: You used the phrase static site. I hear that a lot, usually contrasted with dynamic sites. Can we define what static means in this context?

      -

      Alex: Absolutely. A static website means that the server is simply handing over files exactly as they exist in your repository. It serves HTML, CSS, JavaScript, images, and documents. But it does not run any server-side logic.

      -

      Jamie: So no database connections, no PHP, no Python running on the server to generate the page on the fly.

      -

      Alex: Exactly. Think of a static site like a printed brochure or a bulletin board. What is printed on the paper is exactly what the reader sees. If you want to change the text, you have to print a new brochure. A dynamic site, on the other hand, is like a vending machine. You press a button, machinery whirs into action behind the glass, and it constructs a custom response based on what you asked for.

      -

      Jamie: That is a great analogy. So GitHub Pages only gives out printed brochures. If I want a vending machine, like a site where users log in and post comments to a database, GitHub Pages is not the right tool.

      -

      Alex: Spot on. But for many things, a brochure is exactly what you need. GitHub Pages is perfect for documentation sites, project landing pages, personal portfolios, and even simple blogs. In fact, the workshop materials for this very audio series are hosted on GitHub Pages.

      -

      Jamie: Okay, I am sold. How do I actually turn this on for my repository?

      -

      Alex: It is all done through the repository settings on the GitHub website. Let me walk you through the navigation path using a screen reader. First, navigate to your repository page. In the top navigation bar, you will find a link called Settings. Activate that link.

      -

      Jamie: Got it. The main settings page.

      -

      Alex: Once the Settings page loads, move to the left sidebar. This sidebar has a series of navigation links grouped by category. Navigate down to the group heading called Code and automation. Under that heading, you will find a link simply called Pages. Activate that Pages link.

      -

      Jamie: Okay, I am on the Pages settings screen. What am I looking for here?

      -

      Alex: Navigate to the section heading called Build and deployment. Here, you have a choice for your publishing source. You will find a dropdown menu or radio buttons depending on the current interface layout, offering two main choices. One is Deploy from a branch, and the other is GitHub Actions.

      -

      Jamie: Let us start with Deploy from a branch. That sounds simpler.

      -

      Alex: It is the simplest option. When you select Deploy from a branch, two new standard select dropdown menus will appear. You can navigate these easily with your arrow keys. The first dropdown asks you to select a branch, like your main branch. The second dropdown asks you to select a folder.

      -

      Jamie: What are my folder options?

      -

      Alex: You have two choices. You can select the root folder, which is represented by a forward slash. Or, you can select the docs folder, represented by forward slash docs.

      -

      Jamie: Why would I choose one over the other?

      -

      Alex: If your repository is just a website, like a personal portfolio where the HTML files are right there in the main directory, you choose the root folder. But let us say your repository is a complex software project, like a Python library. Your root folder is full of Python code, setup files, and tests. You do not want to publish all of that as a website.

      -

      Jamie: Oh, I see. So I would create a folder called docs, put my HTML documentation in there, and tell GitHub Pages to only look at that folder.

      -

      Alex: Exactly. Think of it like pointing a spotlight at a very specific folder on your messy desk. GitHub Pages only illuminates and publishes what is inside the docs folder, ignoring the rest of your source code.

      -

      Jamie: That is incredibly useful. So I click Save, and then what? Does it go live instantly?

      -

      Alex: Almost instantly. GitHub will take a minute or two to build and deploy the site. Once the first deployment succeeds, a message will appear at the top of that Pages settings screen with your new live URL.

      -

      Jamie: Let us talk about that URL. If I do not have my own domain name, what address does GitHub give me?

      -

      Alex: The default URL structure is your username dot github dot io, followed by a forward slash, and then your repository name. So if your username is Jamie Codes, and your repository is called my dash project, your website will be live at jamie codes dot github dot io slash my dash project.

      -

      Jamie: That is pretty clean. But what if I just want jamie codes dot github dot io, without the repository name at the end? Like for my main personal website?

      -

      Alex: GitHub has a special feature just for that. If you create a repository and name it exactly your username dot github dot io, GitHub automatically recognizes this as your user profile repository. When you enable Pages for that specific repository, it serves the site at the root level. No forward slash repository name required.

      -

      Jamie: I love that. I definitely used that trick for my first portfolio. But let me ask you about something that used to happen to me all the time. I would type the URL wrong, or I would try to visit a page I had not uploaded yet, and I would get this very generic GitHub 404 Page Not Found error. Can I change that?

      -

      Alex: You absolutely can, and you should! To create a custom error page, all you have to do is create a file named exactly four oh four dot html in the root of your publishing source.

      -

      Jamie: So just the numbers 4 0 4 dot html?

      -

      Alex: Yes. When GitHub Pages cannot find a file a visitor is looking for, it automatically serves that specific file. It is a great place to put a friendly message and a link back to your home page. Think of it like hiring a polite receptionist to tell visitors they have the wrong room, rather than just letting them walk face-first into a locked brick wall.

      -

      Jamie: Okay, so we have talked about hosting plain HTML files. But writing a whole website in raw HTML sounds exhausting. If I have a blog with fifty posts, I do not want to copy and paste my navigation menu fifty times.

      -

      Alex: And you definitely should not. This is where Static Site Generators come in. Remember our factory assembly line analogy? A static site generator is a factory. You feed it raw materials, usually Markdown files containing your content, and a few HTML templates. The generator runs the assembly line, stitches the templates and Markdown together, and spits out a complete folder of finished HTML pages.

      -

      Jamie: That sounds exactly like what I need. Does GitHub Pages include a factory like that?

      -

      Alex: It does. GitHub Pages has native support for a static site generator called Jekyll. Jekyll is built in Ruby, and it is the default engine behind GitHub Pages. If you push a repository full of Markdown files, and you have not told GitHub otherwise, it will quietly run Jekyll behind the scenes to convert those Markdown files into a website.

      -

      Jamie: That is why my README file automatically showed up as a website when I tested this last year! I was so confused about how my Markdown magically became HTML.

      -

      Alex: That was Jekyll doing the heavy lifting. But Jekyll is not the only static site generator out there. There is Hugo, which is incredibly fast. There is Eleventy, which is very popular in the accessibility community. There are frameworks like Next dot js that can export static files.

      -

      Jamie: But if Jekyll is the only one built in, how do I use Eleventy or Hugo with GitHub Pages?

      -

      Alex: That brings us back to the Build and deployment section in the Pages settings. Remember how the first option was Deploy from a branch? The second option is GitHub Actions.

      -

      Jamie: Ah! Okay, I have heard of GitHub Actions, but it always sounded a bit intimidating.

      -

      Alex: It does sound intimidating! But here is the thing, you have already done most of this on Day 1. The workflow is exactly the same, just with a server handling the commands instead of you typing them. GitHub Actions is basically a way to hire a robot assistant to run tasks for you every time you push code.

      -

      Jamie: So instead of the built-in Jekyll factory, I am telling my robot assistant to bring in the Eleventy factory, build my site, and then hand the finished files to GitHub Pages?

      -

      Alex: Precisely. You create a configuration file, specifically a yaml file, in a folder called dot github slash workflows. In this file, you write out the instructions for your robot assistant.

      -

      Jamie: What do those instructions look like?

      -

      Alex: It is a step by step list. First, you tell the robot to check out your repository code. Second, you tell it to set up the environment, like installing Node dot js if you are using Eleventy. Third, you tell it to run your build command, like npm run build. And finally, you use a pre-built GitHub Action called upload pages artifact to take the folder of finished HTML and hand it to the GitHub Pages service.

      -

      Jamie: That actually makes a lot of sense. And I assume there are templates for these workflow files so I do not have to write them from scratch?

      -

      Alex: Tons of them. When you select GitHub Actions as your source in the settings, GitHub will actually suggest pre-written workflow files based on the code in your repository. If it sees a Next dot js project, it will offer you a Next dot js template. You just commit the file, and the robot takes over.

      -

      Jamie: Alright, let us talk about domains. Because jamie codes dot github dot io is nice, but I really want my site to be at jamie codes dot com. Can I use a custom domain with a free GitHub Pages site?

      -

      Alex: Yes, you can use a custom domain on the free tier. It is one of the best features. But it does require a little bit of configuration using DNS, which stands for Domain Name System.

      -

      Jamie: DNS always confuses me. It feels like dark magic.

      -

      Alex: It can feel that way! But DNS is simply the phonebook of the internet. When someone types jamie codes dot com into their browser, their computer looks up that name in the DNS phonebook to find out the actual IP address of the server hosting your website.

      -

      Jamie: So how do I tell the phonebook to point to GitHub?

      -

      Alex: There are two steps. First, you go to your GitHub Pages settings. There is a field labeled Custom domain. You type jamie codes dot com in there and activate the Save button. GitHub will then create a file called CNAME in the root of your repository to remember your domain.

      -

      Jamie: Okay, step one is telling GitHub to expect visitors looking for my domain. What is step two?

      -

      Alex: Step two happens over at the company where you bought your domain name, your domain registrar. You need to log into their dashboard and add some records to your DNS settings. The type of record depends on whether you are using a subdomain or an apex domain.

      -

      Jamie: Can you define apex domain?

      -

      Alex: An apex domain is the root level of your domain, like jamie codes dot com. A subdomain has an extra prefix, like blog dot jamie codes dot com, or www dot jamie codes dot com.

      -

      Jamie: Got it. So what is the difference in the setup?

      -

      Alex: If you are using a subdomain, you create what is called a CNAME record. You tell your registrar that the CNAME for blog dot jamie codes dot com should point directly to your default GitHub address, jamie codes dot github dot io. It is basically a mail forwarding rule.

      -

      Jamie: And for the apex domain?

      -

      Alex: For an apex domain, you have to use A records. A stands for Address. You will create four separate A records, and point them to four specific IP addresses owned by GitHub. You can find these four IP addresses in the GitHub documentation.

      -

      Jamie: Okay, so I update the phonebook. Does it work right away?

      -

      Alex: Not always. DNS changes can take up to 48 hours to propagate across all the servers in the world, though it usually happens in a few minutes. If you push a change and do not see it, you might need to do a hard refresh of your browser. You can do this by pressing Control plus F5 on Windows, or Command plus Shift plus R on a Mac, to bypass your local cache.

      -

      Jamie: That is a great tip. Now, what about security? I notice most websites start with HTTPS these days. Does GitHub Pages support that?

      -

      Alex: It does better than support it, it enforces it. GitHub Pages automatically provisions an SSL certificate for your site using a service called Let's Encrypt. This ensures that all traffic between your visitor and your website is encrypted.

      -

      Jamie: Like putting the website data in a sealed, tamper-proof envelope before sending it across the internet.

      -

      Alex: Exactly. For the default github dot io domains, this happens automatically. For custom domains, once your DNS finishes updating, GitHub will request the certificate. You just need to make sure the Enforce HTTPS checkbox is checked in your Pages settings. It will redirect anyone trying to use the old, insecure HTTP protocol directly to the secure version.

      -

      Jamie: That is amazing that it is all free. Are there any security risks I should worry about?

      -

      Alex: There is one massive security rule you must remember. Never, ever store secrets, API keys, passwords, or private data in a GitHub Pages repository.

      -

      Jamie: Because it is a static site, so anyone can just view the source code?

      -

      Alex: Yes. And more importantly, if you are on a free GitHub account, your repository must be set to Public to use GitHub Pages. That means your entire source code history is visible to the world. Even if you delete a file with a password in it, that file still exists in your git history. So keep your secrets out of your repository.

      -

      Jamie: Let us pivot to something I care deeply about. Accessibility. If I publish a website using GitHub Pages, is it automatically accessible to screen readers?

      -

      Alex: I wish I could say yes, but no. Publishing a site just makes it available on the internet. It does not automatically make it accessible. The accessibility of your published site depends entirely on the HTML, CSS, and JavaScript you or your static site generator produce.

      -

      Jamie: Right, so the factory just builds what you tell it to build. If you feed it inaccessible templates, it will print inaccessible brochures.

      -

      Alex: Exactly. When you are building your site, you need to ensure you are using semantic HTML. This means using the correct tags for the correct purposes. For example, your primary content should be wrapped in the main landmark tag. You should have a logical heading hierarchy, starting with an H1, followed by H2s, and so on.

      -

      Jamie: What about navigation? If I have a blog with a big menu on every page, it can be really tedious for a keyboard user or screen reader user to tab through that menu on every single page load.

      -

      Alex: That is a critical point. For sites with repeated navigation, you should implement a skip link.

      -

      Jamie: Can you explain how a skip link works?

      -

      Alex: A skip link is an anchor tag placed at the very top of your HTML body. Its href attribute points directly to the id of your main content area. The text usually says something like Skip to main content. Using CSS, you can hide it visually until it receives keyboard focus. This allows keyboard and screen reader users to press the Tab key once, activate the link, and jump right over the navigation menu to the actual content of the page.

      -

      Jamie: I love skip links. They save so much time. What about Single Page Applications? I know some static site generators use JavaScript to load new pages without refreshing the browser.

      -

      Alex: That requires careful focus management. If the browser does not fully refresh, a screen reader user might not even realize the page content has changed. If you are using a framework that does this, you must ensure that when the new content loads, keyboard focus is programmatically moved to the new H1 heading, or to a wrapper element with a tabindex attribute set to negative one.

      -

      Jamie: Okay, so semantic HTML, skip links, focus management. How do I test all this once it is live?

      -

      Alex: You should definitely test the live URL. Some issues, like broken relative links or color contrast problems, might only become obvious once the site is fully rendered in a browser. You can use automated tools like WAVE or Axe DevTools.

      -

      Jamie: Wait, Axe DevTools? Can I use that robot assistant we talked about earlier to run Axe automatically?

      -

      Alex: You absolutely can! That is one of the most powerful reasons to use GitHub Actions for your deployment. You can add a step in your workflow file to install the Axe core command line interface. Before the robot deploys your site, it runs Axe against your built HTML files.

      -

      Jamie: And if Axe finds an accessibility violation?

      -

      Alex: You configure the workflow to fail. The robot stops the assembly line, refuses to deploy the broken site, and sends you an alert. It completely blocks inaccessible code from reaching your live website.

      -

      Jamie: That is brilliant. I am definitely setting that up for my next project. I wish I had known that when I started.

      -

      Alex: We have covered a lot of ground today. Let us recap our main takeaways. First, GitHub Pages is a free hosting service that serves static files directly from your repository. It is perfect for documentation, portfolios, and blogs, but it does not run server-side code.

      -

      Jamie: Second, you can serve files directly from your main branch, or isolate them using a docs folder. And if you want to use a custom static site generator like Eleventy or Next dot js, you can use GitHub Actions to automate the build process.

      -

      Alex: Third, GitHub Pages supports custom domains through DNS configuration, and it automatically enforces HTTPS using Let's Encrypt to keep your traffic secure. Just remember to never store sensitive secrets in your public repositories.

      -

      Jamie: And finally, publishing a site does not make it accessible. You still need to use semantic HTML, implement skip links, and manage focus. But you can use GitHub Actions to run automated accessibility tests and block deployments if violations are found.

      -

      Alex: Perfect summary, Jamie. In our next episode, we are going to explore GitHub Discussions, a feature that allows you to build a community and have open-ended conversations right next to your code.

      -

      Jamie: I am looking forward to it. Thanks for listening, everyone!

      -

      Alex: Keep practicing, and we will catch you in the next episode of Gitt Going with GitHub.

      +

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

      - +

      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)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 34: GitHub Actions and Workflows

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub, the audio learning series for blind and low-vision developers who are mastering GitHub and open source collaboration. This is episode 34, titled GitHub Actions and Workflows. I am your host, Alex.

      -

      Jamie: And I am Jamie. I am so excited for this one. We have spent the last thirty-three episodes talking about how to write code, how to commit code, and how to open pull requests. But today, we are talking about what happens after you open that pull request. Because a lot of magic happens, and sometimes it can feel a little bit like a black box.

      -

      Alex: That is a perfect way to describe it, Jamie. Before we dive into that black box, let us do a quick prerequisite check. To get the most out of this episode, you should already be comfortable with the concepts of commits, pushing branches to a remote repository, and opening a pull request. If you need a refresher on those, head back to episode 28. Assuming you are ready, let us talk about GitHub Actions.

      -

      Jamie: So, I will admit, when I first started learning GitHub about two years ago, I kept hearing the phrase GitHub Actions. And I thought it just meant the literal actions I was taking on the website, like creating a repository or adding a collaborator. But it is actually a specific feature, right?

      -

      Alex: Exactly. GitHub Actions is GitHub's built-in automation system. It is a way to define automated tasks that run in response to specific events happening in your repository. The best way to think about it is that GitHub Actions is like having a tireless robot assistant living inside your repository.

      -

      Jamie: I love a robot assistant. What kind of things is this robot doing for us?

      -

      Alex: Well, you get to tell the robot exactly what to do. You can say, hey robot, every time someone opens a pull request, I want you to download their code, install all the dependencies, run our automated test suite, and report back on whether the tests passed or failed. Or you could say, hey robot, every time I push code to the main branch, I want you to package up the application and deploy it to our live web server.

      -

      Jamie: Oh, that is incredibly powerful. Because otherwise, a human maintainer would have to manually pull down my branch, run the tests on their own machine, and then manually reply to my pull request. This robot is saving everyone a massive amount of time.

      -

      Alex: Precisely. It is event-driven automation. Something happens in the repository, which is the event, and that triggers the automation, which is the action. And as a contributor to open source, you usually do not need to write these automations from scratch. The repository maintainers have already set them up. But you absolutely need to understand how to read them, what they are doing, and what to do when they fail on your pull request.

      -

      Jamie: Okay, so if the maintainers have set up this robot assistant, where do the instructions for the robot actually live? Is it a setting in the repository dashboard somewhere?

      -

      Alex: That is a great question. The instructions do not live in a dashboard. They live directly in the repository itself, right alongside the code, as plain text files. They live in a very specific, mandatory folder structure. If you navigate to the root directory of a repository, you will find a folder called dot github.

      -

      Jamie: And just to clarify for everyone listening, when we say dot github, we mean a folder name that literally starts with a period character, followed by the word github. My screen reader usually reads it out as dot github. When I first saw that, I thought the period was a typo.

      -

      Alex: It is not a typo, but it is a convention borrowed from Unix-based systems where putting a dot at the start of a file or folder name marks it as hidden. So depending on your editor settings, you might need to enable a setting like show hidden files in your file explorer to navigate to it. Inside that dot github folder, there is another folder called workflows. And inside that workflows folder is where the magic lives.

      -

      Jamie: Dot github, slash workflows. Got it. And what kind of files are in there? Are they JavaScript files or Python scripts?

      -

      Alex: They are YAML files. That is spelled Y A M L. And they usually have the file extension dot y m l. YAML stands for YAML Ain't Markup Language, which is a classic nerdy recursive acronym. But really, it is just a plain text format used for configuration files. It uses key and value pairs, separated by colons.

      -

      Jamie: I have a love-hate relationship with YAML. The syntax is very clean because it does not use a bunch of curly braces or brackets, but it relies heavily on indentation to define structure. And as a screen reader user, indentation can be tricky if you are not prepared for it.

      -

      Alex: That is a really important point. When you are reading a YAML file, the spacing at the start of the line tells you how things are nested. If you are reading these files, I highly recommend configuring your screen reader to announce indentation. In NVDA, you can do this by pressing NVDA plus Control plus D to open the document formatting settings, and then checking the box to announce line indentation.

      -

      Jamie: Yes, I do exactly that. Or sometimes I use an extension in Visual Studio Code that plays a little audio tone that goes higher in pitch the more indented a line is. It is super helpful for YAML. So, we have these YAML files in the workflows folder. What is the vocabulary we need to know to actually read them? I know there is a specific hierarchy of terms.

      -

      Alex: There is. The hierarchy goes like this. Workflow, event, job, step, and action. Let us break those down. A workflow is the entire automated process. Each YAML file in that folder represents one workflow. For example, you might have a file called tests dot y m l. That entire file is your testing workflow.

      -

      Jamie: Okay, workflow is the whole file. And what triggers the workflow?

      -

      Alex: That is the event. In the YAML file, you will find a key called on, spelled O N. This defines the trigger event. Common events include push, which triggers when someone pushes a commit to a branch. Another is pull underscore request, which triggers when a pull request is opened or updated.

      -

      Jamie: So if the file says on colon pull underscore request, that workflow will run every single time I update my pull request.

      -

      Alex: Exactly. There are other triggers too. You can use schedule to run a workflow on a timer, like every Monday at nine in the morning. Or you can use workflow underscore dispatch, which is a fancy way of saying manual trigger. It adds a button to the GitHub interface so a maintainer can run the workflow whenever they want.

      -

      Jamie: Alright, so we have the workflow, which is the whole file. We have the event, which wakes the robot up. What comes next?

      -

      Alex: Next is the job. A workflow can have one or more jobs. A job is a group of steps that run together on the same machine. In the YAML file, you will see a key called jobs. Underneath that, you name your jobs. You might have a job called run dash tests, and another job called build dash documentation.

      -

      Jamie: You mentioned they run on the same machine. Where is this machine? Is it my computer?

      -

      Alex: No, it is not your computer. This is one of the coolest parts of GitHub Actions. GitHub provides the computers for you, completely free for public open source repositories. These computers are called runners. They are essentially fresh, clean virtual servers in the cloud. In your YAML file, every job must specify what kind of runner it needs using a key called runs dash on.

      -

      Jamie: Oh, I have seen this. It usually says something like runs dash on colon ubuntu dash latest.

      -

      Alex: Exactly. Ubuntu dash latest tells GitHub to spin up a virtual machine running the latest version of the Ubuntu Linux operating system. You can also ask for windows dash latest or macos dash latest if your code needs to be tested on those specific operating systems. So, your job asks for a runner, GitHub provisions that runner, and then the job executes its steps on that machine.

      -

      Jamie: Which brings us to steps. I am guessing steps are the individual commands we want the runner to execute?

      -

      Alex: You got it. Steps are executed in order, one by one. A step can just be a simple shell command. For example, you could have a step with the key run, followed by the command npm install. The runner will open its terminal and type npm install. The next step might run npm test.

      -

      Jamie: This makes so much sense. To use an analogy, the workflow is like a recipe for baking a cake. The event is someone saying they are hungry. The job is the kitchen you are cooking in, like the ubuntu latest kitchen. And the steps are the literal recipe instructions. First, measure the flour. Second, crack the eggs.

      -

      Alex: That is a brilliant analogy, Jamie. And that analogy leads us perfectly to the final piece of the hierarchy, which is the action. Sometimes, a step is not just a simple shell command. Sometimes, a step uses a pre-built piece of automation called an action.

      -

      Jamie: Ah, so this is where the name GitHub Actions comes from. What is a pre-built action?

      -

      Alex: Let us go back to your kitchen analogy. Imagine your recipe requires you to make a complex pastry dough. You could write out fifty steps to make it from scratch. Or, you could just buy pre-made pastry dough from the store and save yourself a ton of time. An action is that pre-made dough. It is a reusable unit of code that someone else wrote, which you can just plug into your workflow.

      -

      Jamie: Oh, that is clever. How do I use one of these actions in my YAML file?

      -

      Alex: Instead of using the run key for a shell command, you use the uses key. For example, almost every workflow starts with a step that uses an action called actions slash checkout. You write uses colon actions slash checkout at version four.

      -

      Jamie: What does the checkout action do?

      -

      Alex: Remember that the runner is a brand new, empty computer. It does not have your code on it yet. The checkout action is a pre-built script that securely authenticates with GitHub, downloads your repository, and places it into the runner's workspace. Doing that from scratch with shell commands would be tedious and error-prone, but the pre-built action does it perfectly in one line.

      -

      Jamie: That is amazing. Are there other pre-built actions I can use?

      -

      Alex: Thousands of them. GitHub hosts a directory called the GitHub Marketplace where anyone can publish an action. There are actions to set up specific versions of Python or Node. There are actions to send a message to a Slack channel when a job finishes. There are even actions that use artificial intelligence to scan your code for accessibility issues. It is basically an app store for automation.

      -

      Jamie: Okay, so I understand the structure now. Workflows have events. Events trigger jobs. Jobs run on runners. And jobs are made of steps, which can either be shell commands or pre-built actions. That feels very logical. But let us talk about how this actually impacts me as a contributor. When I open a pull request, what are the most common workflows I am going to encounter?

      -

      Alex: The two most common concepts you will hear about are CI and CD. CI stands for Continuous Integration. CD stands for Continuous Deployment. Let us start with CI. Continuous Integration is the practice of automatically testing every single change made to a codebase.

      -

      Jamie: So when I open a pull request, the CI workflow is the one that grabs my code and runs the tests.

      -

      Alex: Exactly. The CI workflow is usually triggered by the pull underscore request event. It spins up a runner, checks out your branch, and runs the project's test suite. It acts like an automated spellchecker for your logic. It ensures that your new code did not accidentally break any existing features.

      -

      Jamie: And what about CD? Continuous Deployment?

      -

      Alex: Continuous Deployment usually happens after your pull request is approved and merged. The CD workflow is typically triggered by a push event to the main branch. When the maintainer merges your pull request, the CD workflow wakes up, packages the application, and automatically deploys it to the live production server.

      -

      Jamie: Wow. So nobody is manually copying files over to a server via FTP anymore. The CD workflow just handles it. It is like an automated printing press that publishes the book as soon as the final edit is approved.

      -

      Alex: Exactly. Now, there are a few advanced workflow patterns you will see in open source repositories that are worth knowing about. One is called a matrix build.

      -

      Jamie: A matrix build. That sounds like something out of a science fiction movie. What does it do?

      -

      Alex: It is actually very practical. Imagine you are writing a JavaScript library that other developers will use. You want to make sure your library works on Node version eighteen, Node version twenty, and Node version twenty-two. Instead of writing three separate jobs, you define a matrix strategy in your YAML file. You provide a list of the Node versions, and GitHub Actions automatically multiplies your job, running three identical runners side-by-side, each testing a different version.

      -

      Jamie: Oh, I see! Going back to the kitchen analogy, that is like testing a new cookie recipe by baking one batch in a gas oven, one in an electric oven, and one in an air fryer, all at the exact same time, to make sure they all taste good.

      -

      Alex: That is exactly what it is. And it saves a massive amount of time. Another concept you will encounter is workflow artifacts.

      -

      Jamie: Artifacts. Like ancient pottery?

      -

      Alex: Similar concept, actually! When a job runs on a runner, any files it creates are trapped on that virtual machine. When the job finishes, GitHub deletes the runner. It is completely destroyed. So if your job generates a test report, or compiles a binary executable, that file will be destroyed too. Unless you upload it as an artifact.

      -

      Jamie: Ah, so an artifact is a way to save a file before the virtual machine self-destructs.

      -

      Alex: Exactly. You use a pre-built action called actions slash upload dash artifact. You tell it which folder to save, and GitHub attaches it to the workflow run as a downloadable zip file. It is like asking the restaurant for a takeaway box for your leftovers before they clean off your table.

      -

      Jamie: I love that. Takeaway boxes for code. And what about passwords? If a workflow needs to deploy to a live server, it needs the server password. But you said these YAML files are plain text in the repository. We definitely should not put passwords in plain text YAML files, right?

      -

      Alex: Right. You should never, ever put passwords, API keys, or security tokens in a workflow file. Instead, GitHub has a feature called Secrets. Maintainers can go into the repository settings and save a password as an encrypted secret. Let us say they name it SERVER underscore PASSWORD. In the YAML file, you can reference that secret using a special syntax. GitHub Actions will securely inject the password into the runner when the job starts, and it will even mask the password in the text logs so nobody can read it.

      -

      Jamie: That makes sense. It is like putting the password in a locked safe, and only the robot assistant has the combination.

      -

      Alex: So we have covered how workflows are built. But now we need to talk about the most important part for you as a contributor. Status checks. When you open a pull request, how do you know if the CI workflow passed or failed?

      -

      Jamie: I know this one! If you navigate to the conversation tab of your pull request and scroll down near the bottom, right above the merge button, there is a section called status checks.

      -

      Alex: Exactly. If you are using a screen reader like NVDA or JAWS in browse mode, you can press the letter H or the number 2 to navigate through the headings until you hear the section for checks. If you are using VoiceOver on a Mac, you can open your rotor with VoiceOver plus U, select headings, and navigate to checks.

      -

      Jamie: And what does the screen reader actually announce when I get to that section?

      -

      Alex: It will announce a list of the jobs that ran on your pull request. Each item in the list will announce its name, and its status. If a workflow is currently running, you will hear that it is pending or in progress. If it finishes successfully, you will hear a green checkmark or passed. And if it fails, you will hear a red cross or failed.

      -

      Jamie: Okay, let us talk about failure. Because the first time I got a red cross on my pull request, I panicked. I thought I broke the entire open source project and that the maintainers were going to be furious with me.

      -

      Alex: I am so glad you brought that up. We need to normalize failing status checks. A failing check is not a judgment on your worth as a developer. It is not a sign that you did something terrible. It is simply the robot assistant doing its job. It is giving you information. It is saying, hey, this specific test did not pass with your new code.

      -

      Jamie: That is a very comforting way to look at it. But okay, the robot says I failed. How do I find out why I failed? How do I read the error?

      -

      Alex: This is where we need to navigate the Actions tab. From that list of status checks on your pull request, every failed check is actually a link. If you press Enter on the failed check, it will take you away from the pull request and into the detailed workflow run page.

      -

      Jamie: Okay, I am on the workflow run page. There is a lot of information here. How do I find the actual error message efficiently?

      -

      Alex: The page is organized with a sidebar showing the jobs, and a main content area showing the steps for the selected job. If a job failed, the steps list will show exactly which step caused the failure. Navigate through the list of steps. They are interactive elements. When you find the step that failed, press Enter to expand its log output.

      -

      Jamie: And the log output is just a big text area showing everything the terminal printed out during that step, right?

      -

      Alex: Exactly. And these logs can be thousands of lines long. Reading them from top to bottom with a screen reader is completely inefficient. Instead, you should use your screen reader's find command. If you use NVDA, press NVDA plus Control plus F. If you use JAWS, press Insert plus F. If you use VoiceOver, press VoiceOver plus F.

      -

      Jamie: And what word should I search for?

      -

      Alex: Search for the word error, or the word failed in all caps. This will usually jump your cursor directly to the line that explains what went wrong. You might find a message saying syntax error on line forty-two, or assertion failed expected true but received false. Once you have that information, you can go back to your code, fix the issue, and commit the change.

      -

      Jamie: And do I need to manually restart the workflow after I commit the fix?

      -

      Alex: Usually, no. Because the workflow is listening for the pull underscore request event, pushing a new commit to your pull request branch will automatically trigger the workflow to run again. The yellow pending indicator will appear, and you can wait to see if it turns into a green checkmark.

      -

      Jamie: Alex, before we wrap up, I want to ask about something specific to our audience. We are a community of blind and low-vision developers. Are there workflows that specifically help with accessibility?

      -

      Alex: Absolutely. The open source accessibility community relies heavily on GitHub Actions. Many repositories configure automated accessibility scanners to run on every pull request. These workflows use tools like axe-core or pa11y to scan the HTML output of your code and check for WCAG violations.

      -

      Jamie: Oh, so if I accidentally write an image tag without an alt attribute, the workflow will catch it?

      -

      Alex: Exactly. The status check will report as failed. And when you read the log, it will tell you that the image is missing an alt attribute. GitHub even has a new AI-powered accessibility scanner action in the marketplace that helps identify and suggest fixes for these issues.

      -

      Jamie: That is fantastic. But I assume automated tools cannot catch everything, right?

      -

      Alex: You are entirely correct. Automated accessibility tools catch only about thirty to forty percent of all accessibility issues. They are great for catching structural errors like missing labels or poor color contrast. But they cannot tell you if a complex widget is actually usable with a screen reader. They cannot evaluate the logical flow of a page.

      -

      Jamie: Which is exactly why manual testing by developers who actually use screen readers every day is so incredibly valuable. The robot assistant can do the basic checks, but it needs us to ensure the experience is actually accessible.

      -

      Alex: Perfectly said, Jamie. The robot handles the baseline, so we can focus on the human experience. There is one last thing I want to mention about workflows and open source. Sometimes, you will open a pull request on a repository for the very first time, and the workflows will not run at all. Instead, you will see a message saying a maintainer must approve the workflow runs.

      -

      Jamie: Oh, I have seen that! I thought I did something wrong. Why does it require approval?

      -

      Alex: It is a security feature. Remember that GitHub provides free cloud computers to run these jobs. In the past, bad actors would open automated pull requests with malicious code designed to mine cryptocurrency on GitHub's free servers. To prevent this, GitHub requires a human maintainer to approve the first-time workflow run from any new contributor.

      -

      Jamie: So if I see that message, I just need to be patient?

      -

      Alex: Yes. You can leave a polite comment on your pull request saying, this is ready for review, could a maintainer please approve the workflow runs? Once they approve you that first time, future pull requests from you will trigger the workflows automatically.

      -

      Jamie: This has been an incredibly enlightening episode. I feel like the black box of GitHub Actions is finally open. I understand what the robot assistant is doing.

      -

      Alex: I am glad to hear it. Let us recap our concrete takeaways for today. First, GitHub Actions is an automation system defined by YAML files living in the hidden dot github slash workflows directory.

      -

      Jamie: Second, the hierarchy goes workflow, event, job, step, and action. Events are triggers like a push or a pull request. Jobs run on cloud computers called runners. And steps execute commands or use pre-built actions from the marketplace.

      -

      Alex: Third, CI workflows test your code on every pull request, acting like an automated spellchecker. CD workflows deploy your code when it merges to the main branch.

      -

      Jamie: Fourth, failing status checks are normal and helpful. Use your screen reader's find command to search for the word error in the workflow logs so you can quickly fix the issue and push a new commit.

      -

      Alex: And finally, automated accessibility workflows are great for catching baseline issues, but they do not replace the vital manual testing that developers using assistive technology provide.

      -

      Jamie: This was fantastic. What are we covering next time?

      -

      Alex: Next time, in episode 35, we are taking everything we learned today about GitHub Actions and taking it to the next level. We will be discussing GitHub Agentic Workflows. We will learn how to invite a cloud-based AI coding agent to execute tasks inside these workflows, essentially upgrading our robot assistant with artificial intelligence.

      -

      Jamie: I cannot wait for that.

      -

      Alex: Until then, keep exploring, keep pushing code, and we will talk to you next time on Gitt Going with GitHub.

      +

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

      +
      +

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

      - +

      Episode 35: Profile, Sponsors, and Wikis

      Profile README, GitHub Sponsors, and repository Wikis.

      -

      Based on: Appendix R: Profile, Sponsors, and Wikis

      - - -

      Download Episode 35 (MP3)

      +

      Based on: Appendix T: Profile, Sponsors, and Wikis

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 35: Profile, Sponsors, and Wikis

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub, the audio learning series for blind and low-vision developers who are mastering Git, GitHub, and open-source collaboration. I am Alex, and I am thrilled to be here with you for Episode 35, Profile, Sponsors, and Wikis.

      -

      Jamie: And I am Jamie. I am so ready for this episode because up until now, we have been very focused on the code. We have talked about repositories, commits, branches, and pull requests. But today feels a little different. Today feels like we are talking about the people behind the code.

      -

      Alex: That is exactly right, Jamie. GitHub is the largest host of source code in the world, but it is also a massive social network for developers. And just like any community, how you present yourself, how you support others, and how you share knowledge all matter deeply. Today, we are covering three community-facing features. First, your profile page and how to create a custom profile README. Second, GitHub Sponsors, which is a way to financially support open-source maintainers. And third, GitHub Wikis, which is a built-in tool for creating project documentation.

      -

      Jamie: I remember when I first started learning GitHub about two years ago, I was terrified to look at my own profile page. I felt like it was this giant blank billboard announcing to the world that I was a beginner.

      -

      Alex: That is such a common feeling! Let us start right there. Your profile page is what visitors encounter when they navigate to github dot com slash your username. Think of it as your digital front porch, or your developer business card. By default, it shows your name, maybe a bio if you filled one out in your account settings, a list of repositories you have contributed to, and a contribution graph. But a few years ago, GitHub added a secret feature, an Easter egg, really, that lets you completely customize this page.

      -

      Jamie: Oh, I love a good Easter egg. What is the secret?

      -

      Alex: It is called the profile README. If you create a brand new repository, and you name that repository exactly the same as your GitHub username, something special happens.

      -

      Jamie: Wait, let me make sure I understand. My username is Jamie Codes. So I would create a repository and literally name it Jamie Codes?

      -

      Alex: Exactly. It is case-sensitive, so it needs to match perfectly. You create a new public repository named Jamie Codes. You initialize it with a README file. And here is the magic part. Whatever you write inside that specific README file will be automatically displayed right at the top of your main GitHub profile page.

      -

      Jamie: That is incredibly clever. So instead of just a generic list of my projects, I can actually write an introduction. I can say, Hello, I am Jamie, I am learning Python, and I am passionate about digital accessibility.

      -

      Alex: Exactly. You have complete control. You write it in Markdown, which, as a reminder, is the lightweight text formatting language we use all over GitHub to create headings, lists, and links. Your profile README is the perfect place to include an introduction, your current focus or what you are learning right now, the skills you bring to the table, and how people can get in touch with you.

      -

      Jamie: I have to admit, okay, when I finally figured this out, I went a little overboard. I found all these tutorials online about adding dynamic widgets and fifty different skill badges for every piece of software I had ever touched.

      -

      Alex: And how did that work out for your screen reader?

      -

      Jamie: It was a nightmare! My screen reader would just announce, graphic, JavaScript logo, graphic, Python logo, graphic, HTML logo. It took forever to read through my own profile. I realized I had made my digital front porch completely inaccessible to other blind developers.

      -

      Alex: That is a brilliant point, and it brings us to making your profile README accessible. Because visitors are skimming this page, you want to keep it clean and structured. First, always use proper heading levels. Start with a level one heading for your name, and level two headings for sections like Skills or Get in Touch. This allows screen reader users to press the H key and jump straight to the information they want.

      -

      Jamie: Yes, heading structure is a lifesaver. And what about images? I know some people like to put a banner image at the top.

      -

      Alex: If you use an image, you must provide alternative text, or alt text. In Markdown, you write an exclamation mark, then square brackets containing your description, followed by the image link in parentheses. But even more important than alt text is what you should avoid. You mentioned those auto-generated statistics widgets, like the ones that say Jamie has made forty commits this week. Those are often rendered as complex scalable vector graphics, or SVGs, without proper text equivalents. They are completely silent or read as a jumble of code to a screen reader.

      -

      Jamie: And let us talk about ASCII art. You know, when people use hundreds of punctuation marks to draw a picture of a cat or a spaceship?

      -

      Alex: Please, do not put ASCII art in your profile README. A screen reader will dutifully read every single character. Dash dash dash slash backslash asterisk asterisk. It is incredibly frustrating for someone just trying to find your email address. Keep it human, keep it authentic, and keep it simple. A well-written paragraph about who you are is far more impactful than a wall of noisy widgets.

      -

      Jamie: I ended up deleting all those badges and just writing a few bullet points about my current projects and my screen reader testing experience. It felt much more authentic. Now, Alex, you mentioned the contribution graph earlier. I have heard my sighted colleagues talk about this a lot. They talk about their green squares and keeping their streak alive. Can you explain what the contribution graph is and what those squares actually represent?

      -

      Alex: Absolutely. The contribution graph is a visual calendar on your profile page that shows your GitHub activity over the past year. Sighted users see a grid of little squares, where each square represents a day. If you made a contribution on that day, the square is colored green. The more contributions you made, the darker the green.

      -

      Jamie: And what counts as a contribution?

      -

      Alex: A contribution is recorded when you commit code to a repository's default branch, when you open an issue, when you propose a pull request, or when you submit a pull request review. So it is essentially a data log of your public activity.

      -

      Jamie: It sounds like a fitness tracker, but for coding. Like hitting your ten thousand steps, but instead, you are making commits.

      -

      Alex: That is a perfect analogy. And just like a fitness tracker, it can be motivating, but it can also be a little toxic if you obsess over it. Some developers feel immense pressure to have a contribution every single day, to keep their streak going. But taking a break is healthy. From an accessibility standpoint, GitHub has improved the screen reader experience for this graph. You can navigate through the grid, and your screen reader will announce the date and the number of contributions made on that day. But remember, this graph is just one metric. It does not measure the quality of your code, your mentorship, or the time you spent reading documentation. It just measures activity.

      -

      Jamie: Okay, so we have talked about how to present ourselves to the community using the profile README. But part of being in a community is supporting others. Let us talk about GitHub Sponsors. What exactly is it?

      -

      Alex: GitHub Sponsors is a feature that allows you to financially support the developers and projects that you depend on. If you are familiar with platforms like Patreon, where you can subscribe to support an artist or creator, GitHub Sponsors is exactly like that, but built directly into GitHub for open-source maintainers.

      -

      Jamie: That makes a lot of sense. Because so much of the software we use every day, even the tools that run the internet, are built by volunteers working in their free time.

      -

      Alex: Exactly. Many open-source maintainers spend twenty, thirty, or even forty hours a week managing pull requests, fixing bugs, and writing documentation, completely unpaid. GitHub Sponsors was created to help make open-source more sustainable. When you sponsor someone, you usually choose a monthly tier, like five dollars, ten dollars, or twenty-five dollars a month. And the best part is that GitHub covers all the payment processing fees, so one hundred percent of your sponsorship goes directly to the developer.

      -

      Jamie: That is incredible. So if I am using an open-source screen reader add-on, and it saves me hours of work every week, I could set up a five-dollar monthly sponsorship just to say thank you. How do I actually do that?

      -

      Alex: It is very straightforward. When you navigate to a user's profile page, or to a specific repository, you can explore the page by pressing the B key on your keyboard to jump between buttons. If that developer has opted into the program, you will eventually land on a button called Sponsor. It usually has a little heart icon next to it for sighted users.

      -

      Jamie: And when I activate that Sponsor button?

      -

      Alex: It takes you to their Sponsor profile. There, you can read about why they are seeking sponsorship, and you can navigate through the different payment tiers they have set up. You choose a tier, enter your credit card or PayPal information, and you are done. Your sponsorship will then show up on your own profile page under a Sponsors tab, which is a nice way to publicly show your support for the community, though you can also choose to sponsor privately.

      -

      Jamie: Some developers offer perks too, right? Like early access to new features or a private chat server for sponsors?

      -

      Alex: Yes, they can! It is entirely up to the maintainer. Some offer priority bug fixes, others offer one-on-one mentoring, and some just offer their deep gratitude.

      -

      Jamie: So, flipping the script. What if I am the one building something useful? Can I receive sponsorships?

      -

      Alex: Absolutely. If you maintain an open-source project, or even if you just contribute regularly to other projects, you can set up a sponsor profile. You navigate to github dot com slash sponsors, and you select the button to join the waitlist or set up your profile. You will need to connect a bank account or a Stripe account so GitHub can send you the funds. Then, you create your tiers and write a description of your work.

      -

      Jamie: I want to highlight this for our listeners because I know several blind developers who use GitHub Sponsors to fund their accessibility advocacy. They spend hours testing open-source software with screen readers, filing detailed bug reports, and submitting pull requests to fix focus management or ARIA labels. That is incredibly valuable work, and setting up a Sponsors page is a great way to let the community compensate you for that labor.

      -

      Alex: I am so glad you brought that up, Jamie. Accessibility work is highly specialized, and it absolutely deserves financial support. If you are doing that work, do not be shy about setting up a Sponsors profile and sharing the link in your pull requests or on social media.

      -

      Jamie: All right, we have covered profiles and sponsors. Let us move to the third topic for today, which brings us back to repositories. GitHub Wikis. I know what Wikipedia is, but what is a GitHub Wiki?

      -

      Alex: Every repository on GitHub has the option to enable a Wiki. A Wiki is a space for documentation that lives alongside your code, but is kept separate from the code itself. It is entirely text-based, written in Markdown, and is designed to be a lightweight, multi-page reference guide for your project.

      -

      Jamie: Wait, why would I need a Wiki if I already have a README file? I thought the README was the documentation.

      -

      Alex: That is a great question. Let us use an analogy. Think of your repository as a workshop where you build furniture. The README file is the welcome mat and the directory poster on the front door. It tells people what the workshop is, what tools are inside, and gives them a quick start guide to building their first chair.

      -

      Jamie: Okay, so the README is the quick summary.

      -

      Alex: Right. But what if you have a fifty-page manual on the specific types of wood you use, a troubleshooting guide for the table saw, and a frequently asked questions section about varnishes? If you put all of that on the front door, the poster would be a mile long. Nobody would read it. That is where the Wiki comes in. The Wiki is the filing cabinet or the reference library inside the workshop. It is meant for deep, multi-page documentation.

      -

      Jamie: That makes perfect sense. So the README gets them started, and the Wiki gives them the deep dive. How do I actually access a Wiki?

      -

      Alex: When you navigate to any repository on GitHub, there is a navigation menu at the top of the page with tabs like Code, Issues, and Pull Requests. If the maintainer has enabled it, one of those tabs will be called Wiki. If you activate that tab, you are taken to the Wiki home page. If no pages exist yet, you will find a button that says Create the first page.

      -

      Jamie: And creating a page is pretty straightforward?

      -

      Alex: Very straightforward. When you activate the New Page button, you are given a simple form with two main fields. First, a text input for the page title. Second, a large text area for the page content. You write your content using the exact same Markdown syntax you use for issues and pull requests. Then, you move to the bottom of the page and activate the Save Page button.

      -

      Jamie: I assume I need to use good heading structure here too, right?

      -

      Alex: Always. Because Wikis often contain long articles, using clear heading levels is crucial for screen reader users to navigate the content. Another great feature of Wikis is that GitHub automatically generates a sidebar navigation menu with links to all the pages you create, so visitors can easily jump between different topics. And you can link between pages yourself. If you type two opening square brackets, the name of another Wiki page, and two closing square brackets, GitHub automatically creates a link to that page.

      -

      Jamie: That is really handy. But I have another question. Let us say I have a repository, and inside my code files, I just create a folder called docs, D O C S. And I put a bunch of Markdown files in there. How is a Wiki different from just having a docs folder in my code?

      -

      Alex: This is where we get into the architecture of GitHub. When you put documentation inside a docs folder in your main repository, it is version-controlled exactly like your code. If someone wants to change a typo in the documentation, they have to create a branch, make a commit, and open a pull request. The maintainer has to review it and merge it.

      -

      Jamie: Which is great for control, but maybe a bit heavy for a simple typo.

      -

      Alex: Exactly. A Wiki, on the other hand, is actually an entirely separate Git repository running quietly behind the scenes. By default, Wikis are designed to be community-editable. Depending on how the maintainer configures the settings, any GitHub user might be able to navigate to a Wiki page, activate the Edit button, make a change, and save it instantly, without going through a pull request review process.

      -

      Jamie: Oh, wow. So no pull requests, no branch protection rules. Just edit and save.

      -

      Alex: Yes. Which makes Wikis incredibly powerful for community-driven knowledge bases. If you have an active community of users, they can collectively maintain a list of frequently asked questions or community tutorials without bottlenecking the main developers with pull requests.

      -

      Jamie: But that also sounds a little risky for official documentation.

      -

      Alex: It is. And that is the primary caveat. Because changes to the Wiki bypass your branch protection rules and pull request reviews, you should not use a Wiki for your primary, critical, version-controlled documentation. If your documentation needs to be tied to specific versions of your software, you should use a docs folder or a tool like GitHub Pages. But if you want a collaborative scratchpad, a community FAQ, or a lightweight reference guide, the Wiki is the perfect tool.

      -

      Jamie: This has been a really refreshing episode. It is nice to zoom out from the command line and think about the community aspects of open source.

      -

      Alex: I completely agree. The tools are only as good as the people using them, and these features help us connect as humans. Let us recap our key takeaways for today. First, you can create a custom profile README by creating a public repository with the exact same name as your GitHub username. This acts as your developer business card.

      -

      Jamie: Second, keep that profile README accessible. Use proper headings, include alt text for images, and please, skip the ASCII art and those noisy SVG stat badges. Keep it authentic and readable.

      -

      Alex: Third, GitHub Sponsors is a powerful way to financially support the maintainers who build the open-source tools you rely on. It is also a platform you can use to receive funding for your own contributions, including critical accessibility advocacy.

      -

      Jamie: And finally, GitHub Wikis provide a separate, multi-page reference library attached to your repository. They use Markdown and are great for community-editable guides, but remember they bypass the standard pull request review process.

      -

      Alex: Perfect summary, Jamie. You now have the tools to build your presence, support your peers, and document your projects. In our next episode, we are going to look at how teams organize themselves on GitHub. We will be covering GitHub Organizations and Repository Templates, which are essential when you start collaborating with larger groups.

      -

      Jamie: I cannot wait to dive into that. Thank you all for listening, and we will catch you in the next episode!

      -

      Alex: Happy coding, everyone. Keep building, and keep sharing.

      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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.

      - +

      Episode 36: Organizations and Templates

      GitHub Organizations, repository templates, visibility, and archiving.

      -

      Based on: Appendix S: Organizations and Templates

      - - -

      Download Episode 36 (MP3)

      +

      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 Gitt Going with GitHub. This is episode 36, Organizations and Templates. I am your host, Alex, and as always, I am here to help you navigate the world of version control and open source collaboration.

      -

      Jamie: And I am Jamie. I am here to ask all the questions that you are probably thinking as you listen. I started learning GitHub about two years ago, and I still remember how wild it felt to move past just hosting my own small projects. Today, we are graduating. We are moving from single player mode into massive multiplayer mode.

      -

      Alex: That is a perfect way to describe it. In our previous episodes, we have spent a lot of time talking about personal accounts. We covered how to create your own repositories, how to fork someone else's repository, and how to create a pull request, which is when you request that someone pull your changes into their project. But if you look at a massive open source project, or if you get a job working as a developer at a company, they are not just hosting all their code on one person's personal account.

      -

      Jamie: Right. It would be pretty funny if the entire infrastructure of a massive company was just sitting on an account called cool coder ninety nine.

      -

      Alex: Exactly. And that brings us to our first major concept for today, which is the GitHub Organization. A GitHub Organization is a shared account designed for groups of people. It is a completely different type of account from your personal user account.

      -

      Jamie: So, how should I think about the difference between my personal account and an organization account?

      -

      Alex: I like to use a real estate analogy for this. Think of your personal GitHub account like your personal apartment. You are the only person who holds the master key. You decide what goes on the walls, you decide who is allowed to visit, and everything in it belongs to you. A GitHub Organization is more like an office building. It is a shared space. It has a name on the outside of the building, and inside, there are many different people working together. The assets, which are the repositories, belong to the organization itself, not to any one single person.

      -

      Jamie: That makes a lot of sense. And I know this changes the web address too. My personal repositories live at github dot com slash my username slash the repository name. But for an organization, it uses the organization's name in that middle spot. For example, the project we use in our workshop lives at github dot com slash community dash access slash accessibility dash agents. In that address, community dash access is the organization.

      -

      Alex: Spot on. Now, anyone can create an organization, and you might be wondering about the cost. Creating a GitHub Organization can be completely free, or it can be a paid plan.

      -

      Jamie: I always get a little nervous when I hear the word paid. If I want to start an open source community with a few friends, do I need to pull out my credit card?

      -

      Alex: Not at all. The free tier for organizations is incredibly generous and is designed specifically to support open source communities. You can have unlimited public and private repositories, and you can invite as many members as you want. The paid plans are really for businesses and enterprises. The paid plans add features like advanced auditing, single sign on integration so employees can log in with their corporate credentials, and highly specific access controls. But for almost any community project, the free tier is exactly what you need.

      -

      Jamie: Okay, so let us say I create an organization for my friends and me. We have this virtual office building now. How do we manage who gets to do what? Because in my personal apartment, I am the boss. But in an office building, you usually have different people with different jobs.

      -

      Alex: That is where Organization Roles come into play. When you invite someone to join your organization, you have to assign them a role. The three main roles you need to know about are Owner, Member, and Billing Manager.

      -

      Jamie: Let me guess. The Owner is the person who holds the keys to the entire building.

      -

      Alex: Exactly. Owners have complete administrative control over the organization. They can delete the organization, they can remove other members, and they can change any setting. You usually want to keep the number of owners very small. Then you have the Member role. This is the standard role for almost everyone else in the organization. Members can create repositories, they can collaborate on projects, and they can be assigned to specific teams. Finally, there is the Billing Manager. This role is strictly for the person paying the bills. A Billing Manager can update credit card information and view receipts, but they do not get access to the code. Think of them as the accountant for the building. They can access the financial office, but they cannot walk into the engineering labs.

      -

      Jamie: I love that. The accountant does not need to see my messy code anyway. So, if I am a standard member, how do I actually join? Does someone just add me and suddenly I am in?

      -

      Alex: An owner has to invite you. When they do, you will receive an email and a notification inside GitHub. You have to explicitly accept the invitation. You can navigate to github dot com slash settings slash organizations to accept it, or just open the link in your email.

      -

      Jamie: I want to share a quick story about this, because I was so confused by this when I first joined an organization. I got the invite, I accepted it, and I was so proud. I immediately went to my public GitHub profile page to see the organization badge shining on my profile. But it was not there. I thought I did something wrong.

      -

      Alex: That is a very common experience. By default, when you join an organization, your membership visibility is set to private. That means only you and the owners of the organization can see that you are a member. To the rest of the outside world, you are invisible.

      -

      Jamie: Which is great for privacy, but terrible for my ego.

      -

      Alex: Exactly. If you want people to know you are part of that community, you have to navigate to your organization settings and manually change your membership visibility from private to public. Once you do that, the organization's logo will appear on your public profile.

      -

      Jamie: Okay, so we have our office building, we have our owners, and we have our members. But what happens when the organization gets really big? Like, hundreds of members. How do you keep track of who is working on what?

      -

      Alex: That is where Teams come in. Teams within organizations allow you to group members together based on their role or their project. Staying with our office analogy, if the organization is the building, teams are the different departments. You might have a design department, a security department, and an accessibility review department.

      -

      Jamie: And this actually solves a problem I used to run into. Sometimes I would open a pull request, and I needed someone with screen reader expertise to review my code. Before I knew about teams, I had to guess who to ask, or I would just mention the one person I knew. Which meant that one poor person got pinged every single time I needed a review.

      -

      Alex: Yes, that is a quick way to burn out your volunteers. Teams solve this beautifully. An organization owner can create a team, let us call it accessibility dash reviewers, and add five people to it. Then, when you open your pull request, you do not need to mention a specific person. You just type the at symbol, followed by the organization name, a forward slash, and the team name. So you would type at community dash access slash accessibility dash reviewers. GitHub will automatically notify everyone on that team that a review is requested.

      -

      Jamie: That is so clever. It distributes the workload. As a contributor, I do not usually have permission to create teams, right?

      -

      Alex: Usually not. Creating teams is generally reserved for owners or specific team maintainers. But as a contributor, you need to understand what teams are so that you know why you are suddenly getting notifications when a team you belong to is mentioned, and so you know how to request reviews from teams yourself.

      -

      Jamie: Let us talk about the repositories inside these organizations. In my personal account, a repository is either public, meaning anyone on the internet can see it, or private, meaning only I can see it unless I invite someone. Does an organization have those same options?

      -

      Alex: Yes, but organizations get one additional option. Repository visibility in organizations can be public, private, or internal.

      -

      Jamie: Internal? How is that different from private?

      -

      Alex: Let us go back to our analogies. A public repository is like a public park. Anyone can walk in, sit on a bench, and look around. You do not even need a GitHub account to read the code in a public repository. A private repository is like a locked room inside the office building. Only specific people who are explicitly handed a key to that exact room can get in. Even if you work in the building, if you do not have a key to that room, you cannot see it.

      -

      Jamie: Okay, so where does internal fit in?

      -

      Alex: An internal repository is like the company breakroom. It is completely hidden from the outside public, but anyone who is a member of the organization can walk in. You do not need a special invitation to that specific repository. If you are in the organization, you can see all the internal repositories. This is incredibly useful for companies that want to share code freely among their own employees, but do not want that code leaked to the public internet.

      -

      Jamie: That makes perfect sense. For our listeners using screen readers, how do we actually know what the visibility of a repository is when we land on the page?

      -

      Alex: When you open a repository page, the visibility badge is displayed very prominently at the top of the page. For screen reader users, the easiest way to find this is to press the number one key to navigate to the main heading level one, which is the repository name. Right next to that heading, your screen reader will announce a label that says Public, Private, or Internal. It is usually the very next element in the reading order.

      -

      Jamie: Okay, let us shift gears a bit. We have talked about how to organize people and control visibility. But I want to talk about actually creating new projects. In the past, I have always just created a blank repository and started from scratch. But I have been seeing this button lately called Use this template. It sits right next to the Fork button. And honestly, it confuses me. What is a repository template, and how is it different from a fork?

      -

      Alex: This is a fantastic question, and it is a point of confusion for almost every developer when they first encounter it. Let us break it down. A repository template is a special status that a maintainer can apply to a repository. It turns that repository into a starting point, or a boilerplate, for new projects.

      -

      Jamie: So how is that different from forking? Because when I fork a repository, I am also getting a copy of someone else's project to use as a starting point.

      -

      Alex: The difference is all about the history and the future relationship between the projects. Let us use an analogy. Forking a repository is like taking a collaborative document and making a linked copy. You get the entire revision history of every change ever made to that document. And more importantly, a fork maintains a permanent umbilical cord back to the original project. The whole purpose of a fork is that you plan to make changes and send those changes back up to the original owner via a pull request.

      -

      Jamie: Okay, so a fork is for contributing back. What about a template?

      -

      Alex: A template is like buying a cookie cutter, or a blank piece of official stationery. When you use a template, you are creating a brand new repository that stamps out a copy of the files, the folders, and the structure. But it strips away all of the commit history. You start completely fresh with a clean slate. And there is no umbilical cord. Your new repository has absolutely no connection to the template it came from. You cannot easily open a pull request back to a template. You use a template when you want to start your own distinct project, but you do not want to spend two hours setting up the basic folder structure and configuration files.

      -

      Jamie: Oh, that is huge. The commit history part is the real differentiator. With a fork, I get thousands of old commits from the original authors. With a template, commit number one is just me creating the project.

      -

      Alex: Exactly.

      -

      Jamie: So, what actually transfers over when I use a template? Is it just the main branch?

      -

      Alex: By default, yes. When you use a template, GitHub creates a new repository containing all the files and folders from the template's default branch. It does not transfer issues, it does not transfer pull requests, and it does not transfer repository settings or branch protection rules. It just gives you the files so you can get to work. However, there is a checkbox you can select during the creation process that says include all branches. If you check that, it will copy the files from all the branches, but again, without the commit history.

      -

      Jamie: OK that sounds like a lot of steps to set up. How do I actually use a template if I find one?

      -

      Alex: It might sound like a lot, but it does! But here is the thing - you have already done most of this on day one of your GitHub journey. It is the exact same workflow as creating a standard repository, just with GitHub handling the heavy lifting of copying the files for you. To use a template, you simply navigate to the template repository. Near the top of the page, right next to the Code button, there is a button labeled Use this template.

      -

      Jamie: For screen reader users, what is the fastest way to get to that button?

      -

      Alex: The quickest way is to press the letter B to navigate through the buttons on the page. Once you hear Use this template, press Enter. That will open a dropdown menu. Use your down arrow key to navigate to the option that says Create a new repository, and press Enter again. From there, you will be taken to a page that looks almost identical to the standard new repository page. You give it a name, you choose whether it should be public or private, and you confirm. Within seconds, you have a brand new repository fully populated with the template files.

      -

      Jamie: That is incredibly smooth. What if I want to be the one providing the cookie cutter? How do I turn one of my own repositories into a template so other people can use it?

      -

      Alex: It is literally one checkbox. You must have maintainer or owner access to the repository to do this. You navigate to the repository, open the Settings tab, and stay on the General page. If you navigate down through the page, you will find a checkbox labeled Template repository. Just check that box. The moment you do, the Use this template button will appear for anyone who visits your repository.

      -

      Jamie: Alright, we have covered how to build the office building, how to assign the teams, and how to stamp out new projects using templates. Let us talk about the end of a project's lifecycle. Sometimes projects die. Or they finish, which is a nicer way to think about it. I have noticed sometimes I land on a repository and my screen reader announces a big warning banner that says the repository has been archived. What does archiving a repository mean, and why do maintainers do it?

      -

      Alex: Archiving a repository is a way of officially retiring a project while preserving its history. Think of it like taking a historical document and placing it inside a glass display case at a museum. People can walk up to the glass, they can read the document, and they can even take a picture of it. But they cannot touch it, and they definitely cannot edit it with a pen.

      -

      Jamie: So it becomes completely read only?

      -

      Alex: Exactly. When a repository is archived, no one can open new issues, no one can submit new pull requests, and no one can add new comments to existing discussions. Even the repository owners cannot push new code to it unless they unarchive it first.

      -

      Jamie: Why not just delete the repository if the project is over? Why leave it up in a glass case?

      -

      Alex: Because in the open source world, history is incredibly valuable. Even if a piece of software is no longer being updated, thousands of people might still be using it. Or developers might want to look at the code to see how a specific problem was solved. Deleting a repository breaks links, destroys historical context, and frustrates the community. Archiving is the responsible way to say, we are no longer maintaining this, do not expect any bug fixes, but we are leaving the code here for educational purposes.

      -

      Jamie: That makes a lot of sense. If I am a screen reader user, how do I know if I have stumbled into a museum? Because I do not want to spend an hour reading a codebase only to realize I cannot contribute to it.

      -

      Alex: GitHub puts a prominent yellow banner at the very top of the page. When you navigate to an archived repository, I highly recommend pressing Control plus Home to jump to the very top of the web page, and then use your down arrow to read the first few lines. Your screen reader will read the banner text, which says, This repository has been archived by the owner on, and then it gives the date. It is usually the very first major piece of text before the repository name. If you hear that, you know you are looking at a retired project.

      -

      Jamie: If I really love an archived project, can I still fork it?

      -

      Alex: Yes, you can! You can fork an archived repository and continue the work on your own account. In fact, if you find a repository that you planned to contribute to is archived, the best thing to do is to check the network graph or search GitHub to see if someone else has already forked it and created a successor project.

      -

      Jamie: We have one last topic to cover today, and this is one that genuinely intimidated me the first time I had to do it. Transferring repository ownership. Sometimes you build a project on your personal account, it gets really popular, and you decide to move it into an organization. How does transferring work, and is it as scary as it feels?

      -

      Alex: It is totally normal to feel intimidated by this. Transferring a repository is like handing over the deed to a house. You are giving full control of the project to someone else, or to an organization. But GitHub has built in several safety nets to ensure you do not do this by accident.

      -

      Jamie: What actually happens to the repository when it moves? Do all the links break?

      -

      Alex: No, and that is the magic of GitHub's transfer system. When you transfer a repository, GitHub automatically sets up a redirect. If someone tries to visit the old web address on your personal account, GitHub smoothly redirects them to the new address in the organization. It also transfers all the issues, the pull requests, the commit history, and the stars. Everything moves over intact.

      -

      Jamie: That is a relief. So how do I actually execute the transfer?

      -

      Alex: You navigate to the Settings tab of your repository, scroll all the way to the bottom to the Danger Zone. That section is literally called the Danger Zone, and it is usually marked by a heading level two. In that section, you will find a button to Transfer ownership. When you activate that button, GitHub will ask you to type the name of the new owner or organization.

      -

      Jamie: And this is where the safety net comes in, right?

      -

      Alex: Yes. GitHub will force you to manually type out the full name of the repository you are transferring just to confirm. You cannot just accidentally click a button and lose your project. You have to explicitly type out the name to prove you are paying attention. Once you confirm, the new owner receives an email, and they must accept the transfer. The repository does not actually move until they say yes.

      -

      Jamie: That is really good to know. The typing confirmation definitely makes me feel better. It is like the digital equivalent of being asked, are you sure, are you really sure, okay, sign here.

      -

      Alex: Exactly. It is designed to make you pause and think.

      -

      Jamie: Wow. We covered a massive amount of ground today. We moved out of the personal apartment and into the corporate office building.

      -

      Alex: We did. Let us summarize the key takeaways for today. First, GitHub Organizations are shared accounts designed for communities and companies. They allow you to group people into teams, which makes requesting reviews and managing permissions much easier.

      -

      Jamie: Second, organization repositories have an extra visibility option called internal. This is like the company breakroom. It is hidden from the public internet, but visible to everyone who is a member of the organization.

      -

      Alex: Third, repository templates allow you to stamp out new projects with a clean commit history. Remember, a fork keeps the history and the connection to the original project because you want to contribute back. A template gives you a fresh start with no strings attached.

      -

      Jamie: And finally, archiving a repository puts it in a read only museum display case. It preserves the history without allowing new changes. If you are using a screen reader, press Control plus Home when you load a repository page to check for that archived warning banner at the top of the page.

      -

      Alex: Perfect summary. You now have the conceptual foundation to navigate massive open source communities and corporate GitHub environments. In our next episode, episode 37, we are going to look at Issue Forms and Community Health Files. We will explore how maintainers use templates to guide contributors on exactly what information to provide when reporting a bug.

      -

      Jamie: I cannot wait. Those issue forms save so much back and forth communication.

      -

      Alex: They really do. Until then, keep exploring, keep practicing, and we will see you next time on Gitt Going with GitHub.

      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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.

      - +
      +

      Day 1: GitHub Foundations

      Episode 37: Contributing to Open Source

      Finding issues, scoping contributions, the fork-to-PR workflow, and building habits.

      -

      Based on: Appendix T: Contributing to Open Source

      - - -

      Download Episode 37 (MP3)

      +

      Based on: Chapter 8: Contributing to Open Source

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 37: Contributing to Open Source

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub. This is Episode 37, Contributing to Open Source. I am Alex, and I am here with Jamie.

      -

      Jamie: Hello everyone! I am so excited for this episode. We are well into Day 2 of our GitHub workshop, and today we are talking about taking everything we have learned so far and actually putting it out into the world.

      -

      Alex: Exactly. Over the past few episodes, and throughout Day 1 of the workshop, we covered the core mechanics. We talked about branches, commits, and pull requests. We have set up our local environments. Now, we are going to talk about using those skills to collaborate on public open source projects.

      -

      Jamie: And I have to admit, when I first heard the phrase open source contribution, I was terrified. Before I learned GitHub a couple of years ago, I thought contributing to open source meant you had to be a professional developer with twenty years of experience, writing complex operating system code in C plus plus.

      -

      Alex: That is such a common misconception, and it keeps so many talented people from getting involved. The truth is, open source software is just software whose source code is publicly available. Anyone can read it, use it, and contribute to it. But the word code in source code makes people think that programming is the only way to contribute.

      -

      Jamie: Which is completely false!

      -

      Alex: Completely false. What counts as a contribution is so much broader than that. Writing or improving documentation is a massive contribution. Filing a clear, reproducible bug report is a contribution. Reviewing other people's changes, translating content, adding automated tests. All of these are essential to keeping a project healthy.

      -

      Jamie: I like to think of an open source project like a community garden. Yes, planting seeds is important, which would be like writing new features. But if nobody waters the plants, or fixes the broken lock on the front gate, or paints the signs so people know what is growing where, the garden falls apart. Writing documentation is painting those signs. Filing bug reports is telling the community that the gate is broken.

      -

      Alex: I love that analogy. And for our listeners, who are blind and low-vision developers, I want to emphasize something very specific. You possess a superpower in the open source world. Assistive technology users bring a perspective that the vast majority of sighted, mouse-first developers simply do not have.

      -

      Jamie: Oh, absolutely. When I navigate a webpage, I know immediately if the heading structure is broken. Or if I land on a form and my screen reader just says button, button, button, because there are no accessible names. A sighted developer using a mouse might never notice those missing labels because the buttons have visual icons on them.

      -

      Alex: Exactly. When you encounter a project with those issues, filing a bug report that explains exactly what your screen reader is announcing, and how it breaks your navigation, is a high-value contribution. Suggesting a fix, like adding an aria-label or fixing the heading levels, improves that project for everyone. You do not need anyone's permission to do this. If a repository's issues are public, you can suggest an improvement today.

      -

      Jamie: Okay, so let us say I am convinced. I want to help fix the garden. How do I actually find my first issue? Because there are millions of repositories on GitHub. It feels like looking for a needle in a haystack.

      -

      Alex: It does, but GitHub has specific tools to help you narrow it down. Most welcoming open source projects use labels to categorize their issues. When you are on a repository page, you can navigate to the Issues tab, and filter by these labels.

      -

      Jamie: And there are specific labels meant just for beginners, right?

      -

      Alex: Yes. The most common one is the label called good first issue. This label means the project maintainers have explicitly reviewed the task and decided it is a great starting point for someone who has never contributed to their project before. It usually means the problem is well-defined and does not require understanding the entire architecture of the software.

      -

      Jamie: Another one I always search for is the label help wanted. That usually means the maintainers know this is an issue, but they do not have the time to fix it themselves, and they are actively inviting community members to pick it up.

      -

      Alex: Right. You might also encounter labels like beginner, or easy, or first-timers-only. And do not forget labels that describe the type of work, like documentation or accessibility. If you want to start without writing code, filtering for the documentation label alongside good first issue is a brilliant strategy.

      -

      Jamie: What if I do not have a specific project in mind yet? Can I search across all of GitHub?

      -

      Alex: You can. You can use GitHub's global search. For example, if you type label colon quote good first issue quote, space, is colon open, space, language colon markdown. That search string will return open issues labeled as good first issue, specifically in repositories that use Markdown, which usually means documentation tasks. It is a fantastic way to find small typos or broken links to fix.

      -

      Jamie: So, I run my search, and I find an issue that sounds interesting. How do I know if the project itself is a good place to contribute? Because some communities are more welcoming than others.

      -

      Alex: That is a crucial question. Before you invest time in a project, you should evaluate the project and the community. First, check their activity. Navigate to the repository's main page and check when the last few commits were made. If the project has not been updated in four years, your contribution might sit there forever without being reviewed.

      -

      Jamie: I also like to read through a few recent issues or pull requests to gauge responsiveness. If people are opening issues and the maintainers are replying politely within a few days, that is a great sign. If people are asking for help and getting ignored, or worse, getting rude responses, I usually move on. There are plenty of finding communities that welcome new contributors, so there is no need to waste time on toxic ones.

      -

      Alex: Absolutely. Another major indicator of a welcoming community is a Code of Conduct. This is usually a file named CODE OF CONDUCT dot md. It outlines the community's standards for behavior and how they handle harassment or unacceptable behavior. A project that takes the time to establish and enforce a Code of Conduct is actively thinking about creating a safe space for contributors.

      -

      Jamie: And while we are talking about files in the repository, we have to mention the CONTRIBUTING dot md file.

      -

      Alex: Yes! Every project has different expectations. The contributing file is essentially the rulebook for that specific project. It tells you exactly how the maintainers want you to submit your work.

      -

      Jamie: Going back to analogies, it is like staying at a guest house. Before you start rearranging the kitchen, you should read the house rules left on the counter. The contributing file might tell you that they want commit messages formatted a specific way, or that you need to run a certain command to test your code before opening a pull request. Reading that file saves everyone a lot of time.

      -

      Alex: Let us talk about the issue itself. You found a welcoming project, you read the contributing file, and you found an issue labeled good first issue. Before you start typing, you need to read the issue carefully and scope your contribution.

      -

      Jamie: Scoping is so important. When I first started, I would find an issue about a broken link, and while I was in the file, I would decide to rewrite three paragraphs, fix some formatting, and reorganize the folders. And then my pull request would get rejected because it was too massive and touched too many things.

      -

      Alex: That is the classic trap! A good first contribution needs to be tightly scoped. Start small. Pick one thing. If the issue is about a broken link, fix only the broken link. One pull request, one problem.

      -

      Jamie: Exactly. If you are a plumber hired to fix a leaky faucet, you do not decide to spontaneously replumb the entire house without asking. It is too much to review.

      -

      Alex: A sign that a contribution is too large for a first attempt is if your proposed pull request touches more than three or four files, or if you feel like you need to understand the entire codebase just to make the change. A well-executed small contribution, like fixing a single typo, is infinitely more valuable than a massive contribution that never gets merged because it is too complex for the maintainers to review.

      -

      Jamie: Also, check the issue comments before you start. Is anyone else already working on it? Look for recent comments from other developers saying, I will take this, or check if there is an open pull request linked to the issue. If someone else is actively working on it, you probably want to find a different issue to avoid duplicating effort.

      -

      Alex: If the coast is clear, and the issue makes sense, leave a brief, polite comment. Something like, I would like to work on this, I will open a draft pull request shortly. This claims the issue and lets the maintainers know you are on it.

      -

      Jamie: Alright, we have claimed the issue. Now we have to actually do the work. OK, this part sounds like a lot of steps when you first hear it.

      -

      Alex: It does! But here is the thing. You have already done most of this on Day 1 of the workshop. It is the exact same workflow, just with one extra step at the beginning because we are working across different accounts. Let us walk through the contribution workflow end to end.

      -

      Jamie: Step one is the new part. We have to fork the repository.

      -

      Alex: Right. Because you do not have write access to someone else's public project, you cannot just create a branch directly on their repository. So, you navigate to their repository on GitHub, and activate the Fork button. A fork is simply a complete copy of their repository that lives under your own GitHub account.

      -

      Jamie: I like to think of a fork like copying a recipe card. The original author has their recipe for chocolate chip cookies in their recipe box. You cannot go into their house and write on their card. But you can make a photocopy, put it in your own recipe box, and then make all the notes and changes you want.

      -

      Alex: Perfect analogy. So, you fork the repository. Step two is to clone your fork to your computer, or open it in a GitHub Codespace. Cloning is just downloading that recipe from your GitHub account down to your local workspace.

      -

      Jamie: Step three, we create a branch. We learned this on Day 1. You never work directly on the main branch. You create a new branch with a descriptive name, like fix slash broken dash link. You can do this in the terminal, or by opening the command palette in VS Code by pressing Control plus Shift plus P, and typing Git Create Branch.

      -

      Alex: Step four, you make your change. You open the file, you edit the broken link, you save the file, and you test it with your screen reader to make sure it reads correctly.

      -

      Jamie: Step five, we commit the change. Again, Day 1 stuff. We stage the file, and write a clear commit message. Not just fixed stuff, but fixed broken link in setup guide.

      -

      Alex: Step six, you push the branch. This sends your saved changes from your local computer back up to your fork on GitHub.

      -

      Jamie: And finally, step seven. The grand finale. You open a pull request. You navigate back to the original repository on GitHub, and GitHub will usually display a banner recognizing your recent push, with a button to Compare and pull request. You activate that, and you are literally requesting that the maintainer pull your changes from your recipe box back into their original recipe box.

      -

      Alex: When you reach that pull request screen, you need to write a description. Writing a pull request description that maintainers will appreciate is an art form. You are handing them a piece of work to review, and they might have zero context about who you are or what you are doing.

      -

      Jamie: A good pull request description should answer three questions. What, Why, and How.

      -

      Alex: Exactly. What did you change? Why was the change needed? And how did you verify it works?

      -

      Jamie: So instead of just writing, I fixed the link, you would write, Fixed a broken link on line thirty four of setup guide dot md. The link pointed to an old setup page that no longer exists. I updated it to the new pre workshop setup page. I verified the target file exists and the anchor link routes correctly.

      -

      Alex: If I am a maintainer, and I read that description, I can approve your pull request almost instantly. You have given me all the confidence I need that your change is safe and correct.

      -

      Jamie: But what if they do not approve it instantly? What if they leave a comment asking me to change something? I remember my first pull request, the maintainer asked me to reword a sentence. I felt like I had failed the test. I thought they were rejecting my work.

      -

      Alex: That is such a natural reaction, but it is so important to reframe that. Responding to review feedback is not a rejection. It is collaboration. It is totally normal for a maintainer to ask for tweaks. Think of them like an editor at a newspaper. You submitted an article, and they are just doing a quick copy edit before it goes to print.

      -

      Jamie: So when they ask for a change, do I have to start the whole process over? Do I close the pull request and make a new one?

      -

      Alex: No, and this is the magic of Git. Your pull request is tied to your branch. If a maintainer asks for a change, all you do is go back to your editor, make the change they requested, save the file, commit the change, and push it to your branch again. The pull request on GitHub automatically updates with your new commit.

      -

      Jamie: That was a huge aha moment for me when I learned that. You just keep pushing to the same branch, and the conversation continues in the pull request until everyone is happy.

      -

      Alex: And remember, assume good intent. Maintainers are often volunteers managing these projects in their spare time. If they are brief, or if they take a week to reply, it is usually just because they are busy. If you are waiting for a review, it is completely appropriate to leave one polite follow up comment after a week or two, just saying, Hi, checking in on this when you have a moment.

      -

      Jamie: So, the maintainer reviews it, they approve it, and they merge it. What happens next?

      -

      Alex: When your pull request is merged, your name is permanently added to the project's commit history. The issue is closed, and you are officially listed as a contributor to that project. This record is publicly available on your GitHub profile. It demonstrates that you know how to scope a problem, communicate with a team, address feedback, and deliver a solution.

      -

      Jamie: It feels amazing. But the hardest part is definitely just starting. Getting that first one merged. Once you do it once, you realize the workflow is totally manageable. So how do we build a sustainable contribution habit after this workshop ends?

      -

      Alex: The best way is to set a low bar. Do not pressure yourself to build major features. Keep a list of open source tools, screen readers, or libraries you use every day. When you find a typo in their documentation, fix it right then. If you run into a bug, take fifteen minutes to write a clear, reproducible bug report. A bug report is a real contribution.

      -

      Jamie: And another great way to build the habit is by continuing to learn. Which brings us to a fantastic resource that is completely free, highly accessible, and lets you practice all of this in a safe environment. GitHub Skills.

      -

      Alex: Yes, we need to talk about GitHub Skills. This is GitHub's self-paced interactive learning platform. What makes it unique is that there is no external website, no separate login, and no videos to watch. Every course runs entirely inside GitHub.

      -

      Jamie: It is so cool. When you start a course, GitHub copies a training repository into your own account. And then, an automated bot named Mona becomes your teacher. Mona will open an issue in your repository with instructions for step one.

      -

      Alex: And because it all happens through standard GitHub issues and pull requests, the screen reader navigation skills we have practiced apply perfectly. You use your heading navigation to jump through Mona's instructions. You navigate to the code tab to make your changes. When you complete a task, like opening a pull request, Mona automatically detects it, validates your work, and posts the next step as a comment.

      -

      Jamie: We actually use three of these courses during Day 1 of the workshop. Introduction to GitHub, Communicate Using Markdown, and Review Pull Requests. But there are over thirty courses available in the GitHub Skills catalog, organized into learning paths.

      -

      Alex: Exactly. If you want to continue structured learning after Day 2, you can choose a path that matches your goals. For example, Path 1 covers Git Fundamentals. It includes a great short course on resolving merge conflicts, which is a skill every developer needs to practice.

      -

      Jamie: Path 2 focuses on GitHub Collaboration. That is where you learn repository management, setting up branch protection, and using GitHub Pages to host a website. If you want to get deep into open source maintainership, that is the path for you.

      -

      Alex: There is Path 3 for GitHub Actions and Automation, where you learn to build automated workflows to test your code. And Path 4 is all about GitHub Copilot. It teaches you how to use AI-assisted development, from basic code completion to using Copilot's agent mode and building custom extensions.

      -

      Jamie: And the best part is, you can take your time. Each course takes maybe thirty to sixty minutes. You can track your progress by keeping a list of the courses you have completed. All the links are available in Appendix Z of the workshop materials.

      -

      Alex: We have covered a lot of ground today. Let us wrap up with some concrete takeaways for contributing to open source. First, remember that code is only one type of contribution. Documentation, bug reports, and accessibility reviews are incredibly valuable and desperately needed.

      -

      Jamie: Second, start small. Search for issues labeled good first issue or help wanted, and scope your work tightly. One problem, one pull request. Do not try to replumb the whole house.

      -

      Alex: Third, respect the project's workflow. Evaluate the community for a Code of Conduct, read the contributing rules, and write clear pull request descriptions explaining what you changed, why, and how you tested it.

      -

      Jamie: And finally, embrace feedback. When a maintainer asks for changes, they are collaborating with you, not rejecting you. Just make the change, commit, and push back to your branch.

      -

      Alex: That is exactly right. Build the habit by starting with GitHub Skills, fixing small things, and participating in communities you already use.

      -

      Jamie: I cannot wait to see what everyone contributes. So, what is coming up in our next episode?

      -

      Alex: In Episode 38, we are shifting gears. We will be diving deep into GitHub Actions. We are going to demystify continuous integration and continuous deployment, and show you how to automate your testing and workflows so the robots do the heavy lifting for you.

      -

      Jamie: Oh, I love making the robots do the work. That is going to be a fun one.

      -

      Alex: It really is. Thank you all for listening to Gitt Going with GitHub. We will see you in the next episode!

      +

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

      +
      +

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

      +
      +

      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 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: 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: 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: 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 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). 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: 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 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. 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 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: 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 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. 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 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: 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 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. 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 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 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: 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 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: 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.

      - +
      +

      Appendices

      Tools, references, communities, and continued learning paths.

      -

      Based on: Appendix U: Resources and Links

      - - -

      Download Episode 38 (MP3)

      +

      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: Welcome back to Gitt Going with GitHub. This is episode 38, called Resources and Links. I am Alex, your lead host, and as always, I am joined by Jamie.

      -

      Jamie: Hello everyone. We are getting toward the end of our two-day workshop material, and I have to admit, my brain is feeling a little bit full. We have covered issues, pull requests, merge conflicts, Copilot, VS Code, and custom agents. It is a massive amount of information.

      -

      Alex: It really is, Jamie. And if you are listening to this and feeling slightly overwhelmed, I want to completely normalize that. It is a lot of steps. It is a whole new vocabulary. But here is the thing, you have already done the hardest part. You have built the mental model. You understand how these pieces fit together. Now, it is just about having the right references so you do not have to memorize every single command or keyboard shortcut.

      -

      Jamie: That is a relief. Because I definitely do not have every shortcut memorized yet. When I learned GitHub about two years ago, I spent half my time just trying to figure out where to go when I got stuck. It felt like walking into a massive library without a card catalog.

      -

      Alex: Exactly. And that is exactly what this episode is for. We are going to build your personalized card catalog. We are covering every tool, link, and community reference mentioned in this workshop, plus where to go for help after the workshop ends. We will talk about official documentation, continued learning paths, and how to find accessibility-focused open source projects to contribute to.

      -

      Jamie: So, where do we start? Do I need to bookmark fifty different websites right now?

      -

      Alex: No, actually, you only need one. The central project repository from this workshop. The Accessibility Agents repository that you forked on Day 1. That is your permanent reference.

      -

      Alex: Let us talk about that fork. When you fork a repository, you are making your own personal copy of the project on GitHub. But the real magic happens when you bring it down to your own computer. We call that cloning. Cloning is creating a local copy of a repository on your own hard drive.

      -

      Jamie: Right, so if I clone my fork of the Accessibility Agents repository, I have all the code, but I also have all the documentation we have been using.

      -

      Alex: Precisely. Every guide, every cheat sheet, every appendix from this workshop lives in a folder called docs inside that repository. Once you clone it, that documentation works completely offline. Think of it like downloading a comprehensive survival guide before you go off the grid into the wilderness. Even if you have no internet connection, you can open the folder in VS Code, use your screen reader to navigate the markdown files, and read up on how to resolve a merge conflict or how to write an issue template.

      -

      Jamie: That is incredibly useful. I fly a lot, and having offline access to reference material when I am stuck on an airplane without Wi-Fi is a lifesaver. So the first resource is literally the project we just built. What is next?

      -

      Alex: Next, we need to talk about the official GitHub documentation. But not just the general documentation. I want to highlight the screen reader-specific GitHub guides created by the GitHub Accessibility team.

      -

      Jamie: Oh, I love these. The general GitHub documentation is great, but it is massive. It covers every edge case for enterprise administrators and security teams. But sometimes I just want to know the most efficient way to read a diff with NVDA or JAWS.

      -

      Alex: Exactly. Reading generic documentation as a screen reader user can sometimes feel like asking for directions and being handed a topographical map of the entire state. What you actually want is a local tour guide who uses a white cane, someone who can tell you exactly how many steps to take and where the curbs are. That is what the GitHub Accessibility guides are.

      -

      Jamie: What kind of topics do they cover?

      -

      Alex: They have specific guides for navigating repositories, working with issues, managing pull requests, and using GitHub Copilot in VS Code. And what makes them brilliant is that they do not just tell you what a feature does. They tell you the exact keyboard shortcuts to use. Instead of saying, move your mouse to the top right corner and look for the green button, they will tell you to press the letter G then the letter I to navigate to the Issues tab, or to press the letter C to create a new issue.

      -

      Jamie: That is so much better. They also explain the heading structure, right? Like, they will tell you that the main content starts at a heading level 1, and the comments are all heading level 3s.

      -

      Alex: Yes, they map out the digital architecture for you. If you are reviewing a pull request, which, as a quick refresher, is when you are requesting that someone pull your code changes into their project, the screen reader guide will tell you exactly how the code changes are presented. It explains how to use your screen reader's browse mode to jump between the added lines and the removed lines without getting lost in the layout tables.

      -

      Jamie: I wish I had known about those guides when I started. I spent a lot of time just pressing the Tab key and hoping for the best.

      -

      Alex: Let us move on to how you can continue practicing these skills. Reading documentation is one thing, but muscle memory comes from doing. That brings us to GitHub Skills.

      -

      Jamie: GitHub Skills! I am so excited to talk about this. This is completely different from a normal online course, right?

      -

      Alex: It is entirely different. GitHub Skills is GitHub's free, self-paced interactive learning platform. But here is the brilliant part. There are no videos to watch. There is no separate website to log into. Every course runs entirely inside GitHub itself. It uses something called the template-copy pattern.

      -

      Jamie: Can you explain the template-copy pattern? Because that sounds like enterprise jargon.

      -

      Alex: Fair point. Think of it like one of those interactive escape rooms, but for code. When you start a course on GitHub Skills, you press a button to use their template. This copies an entire pre-built repository into your own personal GitHub account. As soon as that repository is created, a bot named Mona automatically wakes up and opens a new Issue in your repository.

      -

      Jamie: Mona is the GitHub mascot, right? The little octopus with cat ears?

      -

      Alex: Yes, the octocat. So Mona opens an issue, and inside that issue are your instructions for step one. Let us say the course is about resolving merge conflicts. The issue will say, welcome to the course, your first task is to create a new branch and change a specific file.

      -

      Jamie: And you actually do that right there in the repository? You do not go to a simulated environment?

      -

      Alex: Exactly. You do the real task in the real environment. You edit the file, you commit the change. And when you do, GitHub Actions workflows are running in the background. Within about twenty seconds, Mona detects what you did. She checks if you did it correctly. If you did, she closes the issue and opens step two. If you made a mistake, she leaves a comment explaining what went wrong and asks you to try again.

      -

      Jamie: That is so cool. It is like having a digital mentor sitting over your shoulder, but it is completely asynchronous. And from an accessibility standpoint, it means you are using the exact same interface you will use for real work. You are practicing navigating issues, reading comments, and creating pull requests using your screen reader in the actual GitHub web interface.

      -

      Alex: Exactly. To navigate a course, you just use the skills we learned in the workshop. You press G then I to navigate to your Issues tab. You press the letter H or the number 3 to find the issue heading, press Enter to open it, and use your down arrow in Browse Mode to read Mona's instructions. When you complete the task, you just wait a moment, and your screen reader will announce when Mona posts a new comment.

      -

      Jamie: What courses do they have? Where should someone start after this workshop?

      -

      Alex: If you want to reinforce what we learned here, start with the Introduction to GitHub course. It takes less than an hour and covers branches, commits, and pull requests. Then, take the Review Pull Requests course. It teaches you how to leave comments, suggest changes, and approve code. And finally, I highly recommend the Resolve Merge Conflicts course. Merge conflicts are usually the scariest part for beginners, but practicing them in a safe, automated environment takes all the fear away.

      -

      Jamie: Okay, so GitHub Skills covers the GitHub side of things. But what about Git itself? Git is the underlying version control system that powers all of this, right? I still get confused sometimes between Git and GitHub.

      -

      Alex: That is a very common confusion. Here is the analogy I like to use. Git is the engine, and GitHub is the garage. Git is the actual software running on your computer that tracks the history of your files. GitHub is the collaborative platform on the internet where you store that history and work with other people. You can use Git without GitHub, but you cannot use GitHub without Git.

      -

      Jamie: That makes sense. So if I want to understand the engine better, where do I go?

      -

      Alex: The gold standard reference is the Pro Git Book. It is completely free and available online. It is the full engineering schematic of how Git works. Now, I will warn you, it is incredibly dense. You do not need to read it cover to cover like a novel. Use it like a dictionary or an encyclopedia. If you want to deeply understand how a specific command works, like git rebase, that is where you look.

      -

      Jamie: Is there anything more interactive for learning Git?

      -

      Alex: Yes, there is a fantastic resource called Learn Git Branching. It is an interactive tutorial that walks you through how branches work. As a reminder, branching is when you create a parallel universe of your code so you can experiment safely without breaking the main project.

      -

      Jamie: Wait, I have seen Learn Git Branching. It is highly visual. It draws little nodes and trees on the screen. Is that accessible for a screen reader user?

      -

      Alex: It is a mixed bag. They do have a command-line interface that you can interact with, which is readable, but the visual tree diagram is the main selling point, and that part is not conveyed well to screen readers. For our blind and low-vision listeners, I actually recommend leaning heavily on the official GitHub Git Cheat Sheet. It is a text-based PDF that lists every major Git command and explains exactly what it does in plain English. Keep that PDF open in a separate window, and practice the commands in your own VS Code terminal.

      -

      Alex: Speaking of VS Code, we need to talk about your local development environment. VS Code is like your personal physical workshop. When you walk into a physical workshop, you want your tools arranged exactly how you like them, so you can reach out and grab a screwdriver or a wrench without even looking.

      -

      Jamie: Right, and in VS Code, arranging your tools means setting up your keyboard shortcuts and configuring the accessibility settings.

      -

      Alex: Exactly. The first resource you need here is the official VS Code Accessibility documentation. Microsoft has done an incredible job building screen reader mode into VS Code. The documentation explains how to use features like the Accessible View, which lets you inspect hover text and error messages in a clean, screen-reader-friendly buffer.

      -

      Jamie: Oh, and Audio Cues! We talked about those in a previous episode, but the documentation lists all of them. Audio cues are those little sounds VS Code plays to tell you if a line has an error, or if a line was added or deleted in a diff, without you having to read the text.

      -

      Alex: Yes, the audio cues are fantastic. The documentation also provides a complete list of keyboard shortcuts for Windows and Mac. The most important shortcut to remember, the one that unlocks everything else, is the Command Palette. You open it by pressing Control plus Shift plus P on Windows, or Command plus Shift plus P on Mac. From there, you can type any command you want, like open accessibility settings, and press Enter.

      -

      Jamie: So if the GitHub Accessibility guides are the tour guide for the website, the VS Code Accessibility documentation is the blueprint for organizing your digital workshop.

      -

      Jamie: Alex, what if someone wants to go beyond just learning Git and GitHub? What if they are a screen reader user who wants to learn how to code from scratch, or pick up a new programming language? Where should they go?

      -

      Alex: That is a great question. There are two incredibly strong, completely free, open-source learning paths that I always recommend. The first is freeCodeCamp, and the second is The Odin Project.

      -

      Jamie: I have heard of freeCodeCamp. It is massive.

      -

      Alex: It is. If GitHub Skills is where you learn how to use the kitchen tools, freeCodeCamp and The Odin Project are the culinary schools where you learn how to cook. They teach you HTML, CSS, JavaScript, Python, and more.

      -

      Jamie: Are they accessible? A lot of coding platforms rely on drag-and-drop exercises or visual puzzles that are completely broken with a screen reader.

      -

      Alex: Both of these platforms are heavily text-based and very screen-reader friendly. freeCodeCamp has an integrated editor on their website, and they have worked hard on its accessibility. The Odin Project takes a different approach. They do not use an in-browser editor at all. Instead, their curriculum guides you through setting up your own local environment using VS Code and the terminal, and you build real projects on your own computer.

      -

      Jamie: I actually love that approach. It forces you to learn the real tools from day one, rather than relying on a training wheels environment. And since you are using VS Code, you can use all the accessibility features we just talked about.

      -

      Alex: Exactly. Both of these platforms are also entirely open source, hosted on GitHub. If you ever find an accessibility bug in their curriculum, you can open an issue or even submit a pull request to fix it.

      -

      Jamie: That is a perfect transition. Let us talk about contributing. Once someone finishes this workshop, and maybe does a few GitHub Skills courses, how do they find real open source projects to contribute to? It feels like standing at the edge of the ocean. There are millions of repositories. Where do you even start?

      -

      Alex: You do not start by swimming into the deep end. You start at the bunny hill. Just like a ski resort has a gentle slope for beginners, the open source community has curated lists of beginner-friendly tasks.

      -

      Jamie: Like the Good First Issue label! We talked about that earlier in the workshop.

      -

      Alex: Yes. Maintainers use the Good First Issue label to mark tasks that are isolated, well-documented, and perfect for someone new to the project. But searching for them across all of GitHub can be tricky. So, I recommend using a website called goodfirstissue.dev, or another site called Up For Grabs. These websites aggregate issues from across the internet that are specifically tagged for beginners. They expect you to be new, and the maintainers are ready to help you learn.

      -

      Jamie: That is brilliant. But what if I specifically want to work on accessibility? Like, what if I want to use my lived experience as a screen reader user to make projects better?

      -

      Alex: Your lived experience is a superpower in open source. Many sighted developers genuinely want to make their projects accessible, but they do not know how to test them properly. You are the domain expert.

      -

      Jamie: So how do I find those projects?

      -

      Alex: You use GitHub Advanced Search. You can search for specific topics. Topics are tags that maintainers add to their repositories to describe what the project is about. If you go to the GitHub search bar and type topic colon accessibility, or topic colon assistive dash technology, you will find thousands of public repositories focused exactly on those areas.

      -

      Jamie: Oh, that is clever. So I could search for topic colon accessibility, and then filter by the label Good First Issue.

      -

      Alex: Exactly. You can combine search terms. You could search for is colon open, is colon issue, label colon help dash wanted, and topic colon screen dash reader. That query will give you a list of open issues where maintainers are explicitly asking for help with screen reader compatibility. It is a fantastic way to find projects where your specific skills are desperately needed.

      -

      Alex: Finally, we need to talk about community. Learning all of this can sometimes feel isolating. When you hit a wall, or when a tool updates and suddenly your screen reader is not reading a specific menu correctly, you need a place to ask questions.

      -

      Jamie: The digital water cooler. Where do we go to swap stories and get unstuck?

      -

      Alex: There are two main communities you should join. The first is the A11y Slack community. A11y is numeronym for accessibility, spelled A, the number 11, and Y. This Slack workspace is filled with thousands of accessibility professionals, developers, and users. There are specific channels for screen reader questions, web standards, and developer tools. It is incredibly welcoming.

      -

      Jamie: And the second one?

      -

      Alex: The second is the GitHub Community Accessibility Discussions. This is an official discussion forum hosted on GitHub itself. It is monitored by the GitHub Accessibility team. If you find a bug on GitHub, or if you have an idea for how to make the platform more accessible, that is where you post it. It is also a great place to connect with other blind and low-vision developers who are using the exact same tools you are.

      -

      Jamie: That is really comforting to know. It means I am not just shouting into the void when something breaks. There are actual people, and actual teams, listening and ready to help.

      -

      Alex: You are absolutely not alone. There is a massive, vibrant community of blind and low-vision developers out there writing incredible code and shaping the future of open source. You are just taking your first steps to join them.

      -

      Alex: Alright, let us wrap up this episode with a few concrete takeaways. Jamie, what should our listeners remember?

      -

      Jamie: First, your permanent offline reference is the Accessibility Agents repository that you forked. Clone it to your computer, and you will have the entire workshop documentation available even without internet. Second, do not just read generic documentation. Search for the official GitHub Accessibility guides for screen-reader-optimized instructions and exact keyboard shortcuts.

      -

      Alex: Perfect. Third, when you are ready to practice, use GitHub Skills. It uses the template-copy pattern to give you real, hands-on practice inside the actual GitHub interface, guided by Mona the bot. And finally, remember your superpower. Use GitHub Advanced Search with topic colon accessibility to find projects that desperately need your lived experience.

      -

      Jamie: This has been incredibly helpful. I feel like I finally have a map to the library. What is next?

      -

      Alex: In our next episode, we are going to dive deep into the GitHub Concepts Glossary. We will be demystifying all the jargon and technical terms you will encounter in the wild, from upstream to cherry-picking to rebasing. You will not want to miss it. Until then, keep practicing, keep exploring, and keep Gitt Going.

      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      - +

      Episode 39: Accessibility Agents - Complete Reference

      -

      All six agents, all 28 slash commands, customization, and troubleshooting.

      -

      Based on: Appendix V: Accessibility Agents - Complete Reference

      - - -

      Download Episode 39 (MP3)

      +

      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 Gitt Going with GitHub. This is episode 39, Accessibility Agents Complete Reference. I am Alex, and I am thrilled to be here with you as we near the end of our two-day workshop material.

      -

      Jamie: And I am Jamie! I am so ready for this. We have been hinting at this massive ecosystem of agents for a while. Back in episode 17, we did a high-level overview of what an agent even is. But today, we are opening up the whole reference manual.

      -

      Alex: Exactly. Today is about scale and customization. We are going to cover the complete documentation for all 55 agents across three specialized teams. We will walk through the 54 plus slash commands and how to use them. We will break down exactly how these agents format their inputs and outputs. And most importantly, we will teach you how to customize them, configure your workspace, build your own domain-specific agents, handle version updates, and troubleshoot when things go wrong.

      -

      Jamie: Okay, just hearing you list all that out makes my brain feel a little full. Fifty-five agents? Fifty-four slash commands? That sounds like a lot of steps and a lot to memorize.

      -

      Alex: It does sound intimidating! But here is the thing. You have already done most of this on Day 1 of the workshop. You already know the workflow. The only difference now is that Visual Studio Code and GitHub Copilot are handling the heavy lifting. You do not have to memorize 55 agents. Think of it like walking into a massive digital agency. You do not need to know what every single employee does, you just need to know which department to walk into when you have a specific problem.

      -

      Alex: Let us start with that digital agency analogy. The accessibility agents ecosystem is divided into three teams, or departments. The first is the Accessibility Team, which is the largest, with 26 agents.

      -

      Jamie: So if I need help specifically with making my code work for screen readers or keyboard users, this is the department I go to.

      -

      Alex: Spot on. To talk to an agent, you open Copilot Chat by pressing Control plus Shift plus I. Then you type the at symbol, followed by the agent name. For example, you have task agents like at aria specialist, which helps you build complex widgets like comboboxes or modals. You have at contrast master for visual presentation, and at keyboard navigator for focus management.

      -

      Jamie: I remember struggling so much with live regions when I first learned accessibility. Is there an agent for that?

      -

      Alex: There is. It is literally called at live region controller. And what is brilliant about this team is that they have orchestrator agents. An orchestrator is like a project manager. If you call at web accessibility wizard, that agent will actually delegate tasks to the other specialized agents to perform a full, guided audit of your work. It gathers all their findings and gives you a single, prioritized action plan.

      -

      Jamie: That is incredible. So I do not have to talk to five different agents if I do not want to. I just talk to the wizard, and it talks to the team. What are the other two departments?

      -

      Alex: The second department is the GitHub Workflow Team. This one has 12 agents, and they automate your repository operations. You have at daily briefing, which gives you a morning situation report of issues and pull requests. You have at issue tracker to find and prioritize tickets. And my personal favorite, at pr review.

      -

      Jamie: Oh, pull requests! A pull request is when you are asking someone to review your code and pull it into the main project. I used to be terrified of reviewing them because I was worried I would miss something important.

      -

      Alex: And that is exactly why at pr review is so powerful. You give it a pull request number, and it reads the code, assesses the risk level, and even suggests inline comments. But remember the critical rule of the workflow team. The agent produces a starting point. It drafts the reply. You are the human. You read it, you edit it, and you post it under your own name.

      -

      Jamie: Got it. The agent is the assistant, not the boss. And what is the third team?

      -

      Alex: The Developer Tools Team. This has 6 agents focused on specific environments. For example, at python specialist for Python accessibility patterns, or at desktop a 11 y specialist for Windows, Mac, and Linux native app accessibility.

      -

      Alex: Now, alongside those 55 conversational agents, we have over 54 slash commands.

      -

      Jamie: Okay, so what is the difference? Why would I use a slash command instead of just talking to an agent with the at symbol?

      -

      Alex: Great question. Let us use an analogy. Talking to an agent with the at symbol is like hiring a contractor. You sit down, you have a conversation, you discuss the nuance of the project, and you go back and forth. A slash command is like a vending machine button. You press it, and you get exactly the specific snack you wanted, immediately, following a strict, repeatable process.

      -

      Jamie: Oh, I like that. So a slash command is for a single, focused task. How do I use one?

      -

      Alex: In that same Copilot Chat window, you just type a forward slash. That opens up a menu of commands. Let us talk about some of the most useful ones for this workshop.

      -

      Jamie: Hit me. What is on the speed dial?

      -

      Alex: If you type slash my dash issues, it immediately pulls up all your open issues with priority signals. If you type slash review dash pr followed by a number, like slash review dash pr 14, it generates that AI review with inline suggestions.

      -

      Jamie: What if I am looking at a brand new bug report and I do not know how to categorize it?

      -

      Alex: You type slash triage. It will read the issue and suggest labels and priority levels. If you need to respond to an issue, type slash issue dash reply. There is also slash daily dash briefing, which does the same thing as the daily briefing agent but in one quick command. And if you are getting ready to publish a new version of your software, slash draft dash release will automatically read all your merged code and generate the release notes for you.

      -

      Jamie: That is a massive time saver. I used to spend hours reading old commits just to write a changelog. But wait, how do these commands know what to do? You mentioned input and output formats earlier.

      -

      Alex: Yes. Let us talk about input formats first. Think of a prompt file like giving a recipe to a chef. When you type a slash command, Visual Studio Code looks at a specific file in your project that defines that command. Inside that file, we use input parameters. The syntax is a dollar sign, followed by an opening curly brace, the word input, a colon, the name of the variable, another colon, and then a helpful hint for the user, closing with a curly brace.

      -

      Jamie: So if I use slash review dash pr, the input parameter is asking me for the pull request number?

      -

      Alex: Exactly. The prompt file says, hey Copilot, please review the pull request provided in this input variable.

      -

      Jamie: And what about the output? When the agent replies, is it just a giant wall of text? Because as a screen reader user, a giant wall of text with no structure is my worst nightmare.

      -

      Alex: That is where the output format constraints come in. These agents are strictly instructed on how to structure their replies. We use an analogy of a well-organized filing cabinet. The agents are told to always use strict heading levels. They use heading level 2 for major sections, and heading level 3 for sub-sections. They are explicitly told never to skip heading levels, because jumping from an H1 straight to an H3 is a huge accessibility violation and breaks screen reader navigation.

      -

      Jamie: Oh, I love that. I navigate almost entirely by pressing the letter H to jump between headings. If the structure is predictable, I can skim an agent's response in seconds.

      -

      Alex: Exactly. Another strict output rule is the empty state rule. If you ask the daily briefing agent for your security alerts, and you have zero security alerts, the agent is not allowed to just skip that section. It must print the heading for Security Alerts, and underneath it, write All Clear.

      -

      Jamie: Yes! Silent failures are the worst. If a section is just missing, I always wonder if the agent broke, or if my screen reader skipped it, or if there really was nothing there. Explicitly saying All Clear removes so much cognitive load.

      -

      Alex: So, we know how the agents work out of the box. But every developer, every team, and every project is different. That brings us to customization. How do we teach the agents our specific rules?

      -

      Jamie: Like an employee handbook! You have to tell the new hire how your company does things.

      -

      Alex: Exactly. We do this through instruction files and settings. There are two main ways to provide always-on instructions. These are rules that the agent follows for every single request, without you ever having to ask.

      -

      Jamie: Where do we put this employee handbook?

      -

      Alex: The recommended approach for most projects is a file called copilot dash instructions dot m d. It lives inside a folder named dot github at the root of your project. It is just a plain text file. You can put your accessibility standards in there, your coding conventions, and even rules about tone. For example, you can write, Write for screen reader users first. Use active voice. Never use color as the only indicator of meaning.

      -

      Jamie: And if I am working on a massive project with different tools, like maybe I am using Claude Code in the terminal alongside Copilot?

      -

      Alex: Then you use the alternative option, a file simply called A G E N T S dot m d, right at the root of your workspace. It is an open standard that multiple artificial intelligence tools recognize. You use one or the other, not both.

      -

      Jamie: Okay, so that covers the project rules. But what about my personal preferences? Like, my team might not care what screen reader I use, but I want the agent to know.

      -

      Alex: That is where the preferences dot m d file comes in. You create this inside the dot github slash agents folder. This file is ignored by the version control system, meaning it stays completely private on your local machine. It never gets uploaded to the public team repository.

      -

      Jamie: Oh, that is neat. What kind of things do I put in my private preferences?

      -

      Alex: You can set your GitHub username, your timezone, and your notification priorities. If you want accessibility issues at the top of your daily briefing, you write that here. You can also define your review comment tone. You might say, Be direct but constructive, and be extra warm to first-time contributors.

      -

      Jamie: And my screen reader context goes here too?

      -

      Alex: Yes. You literally just write, I use N V D A with Chrome on Windows 11. The agents read this, and suddenly, they stop giving you instructions for VoiceOver on a Mac. They tailor their output specifically to your technology stack.

      -

      Alex: Now, Jamie, we just talked about project rules versus personal rules. This is a perfect transition to our next concept, which is workspace configuration and scope.

      -

      Jamie: Scope always confuses me a little. It sounds like a mouthwash.

      -

      Alex: Think of scope like a hierarchy of laws. You have city laws, state laws, and federal laws. In Visual Studio Code, we have three levels of scope. User level, Workspace level, and Organization level.

      -

      Jamie: Okay, break those down for me.

      -

      Alex: User scope, or personal scope, lives in your Visual Studio Code profile. These rules follow you to any project you open on your computer. Workspace scope lives in the repository folder, like that dot github directory we mentioned. Those rules apply to anyone who downloads that specific project. Organization scope is set by your company administrators on GitHub, and applies to every repository your company owns.

      -

      Jamie: So what happens when these laws conflict? Let us say my company Organization rules say, always write extremely formal code comments. But my User profile says, write casual, friendly code comments. Who wins?

      -

      Alex: The most specific, local scope always wins. Your Personal User profile has the highest priority. It overrides the Workspace, and the Workspace overrides the Organization. So your comments will be casual and friendly. Visual Studio Code collects all the instruction files from all three scopes, combines them, and sends them to the agent. Priority only matters when there is a direct contradiction.

      -

      Alex: So far, we have been consumers. We are using the 55 agents that already exist, and we are tweaking their instructions. But what if you want to build your own custom, domain-specific agent?

      -

      Jamie: Like writing a job description to hire a brand new specialist for my agency.

      -

      Alex: Exactly. It is surprisingly easy. An agent is just a file ending in dot agent dot m d. You save it in the dot github slash agents folder. The most important part of this file is at the very top, in a section called the frontmatter.

      -

      Jamie: Frontmatter. I have heard that term. That is the configuration block at the top of a file, usually surrounded by three dashes, right?

      -

      Alex: Yes. It uses a format called Y A M L, or YAML. In this frontmatter, you define the name of the agent. This is what you will type after the at symbol. You also write a description.

      -

      Jamie: Is the description just for me to read?

      -

      Alex: No, and this is crucial. The description is how the orchestrator agents decide whether to delegate work to your custom agent. If you name an agent at cool helper, and the description is just, A helpful agent, it will never get any delegated work. But if the description says, Use when auditing Markdown files for missing alt text and heading skips, the orchestrator knows exactly when to call it.

      -

      Jamie: Oh, that is clever! It is like a search engine optimization game, but for artificial intelligence delegation.

      -

      Alex: Exactly. The other critical thing you put in the frontmatter is the tools array. This dictates what your agent is allowed to do.

      -

      Jamie: Like giving the new hire a security badge.

      -

      Alex: Perfect analogy. If you give the agent the read tool, it has a visitor badge. It can look at your files but cannot change them. If you give it the edit tool, it can modify code. If you give it the execute tool, it has the master key. It can run shell commands in your terminal. You should be very careful with the execute tool.

      -

      Jamie: I can imagine. I do not want an agent deciding to format my hard drive because it misunderstood a prompt. Are there any other settings in that frontmatter?

      -

      Alex: Yes, you can set a flag called user dash invocable to false. This hides the agent from the chat menu. It becomes a background worker that only other agents can talk to.

      -

      Alex: Let us talk about version compatibility and update patterns. AI models are changing constantly. What happens if you build a custom agent that relies on a specific model, like Claude Sonnet, but then you share your project with a friend whose company only licenses GPT 4?

      -

      Jamie: Does the agent just crash?

      -

      Alex: It would, unless you use a fallback array. In your agent frontmatter, instead of listing one model, you can provide a list in brackets. You can say, try Claude Sonnet first, but if that is not available, fall back to GPT 4. Think of it like carrying a spare tire. If your primary model is unavailable, the agent gracefully switches to the backup without throwing an error.

      -

      Jamie: That is a great practice. What about when we want to enforce rules, rather than just guide the agent? Earlier you said instructions are just guidance.

      -

      Alex: Yes. Instructions are like a speed limit sign. You are asking the agent nicely to follow the rules. But sometimes you need a physical speed bump. That is where hooks come in. Hooks are JSON files, which is just another configuration format. They execute real shell commands at specific points in the agent's lifecycle.

      -

      Jamie: Like a security guard checking your bag before you leave the building.

      -

      Alex: Exactly. You can set a Pre Tool Use hook. Before the agent is allowed to use a tool to edit a file, the hook can run a script to validate the request. You can set a Post Tool Use hook to automatically run a code formatter every time the agent finishes writing a file. Hooks are deterministic. They run every single time, regardless of what the user typed in the chat.

      -

      Alex: Alright Jamie, we have covered a massive amount of ground. We are at the final concept. Troubleshooting. What happens when you type at daily briefing, and Visual Studio Code just says, Agent not found?

      -

      Jamie: I usually panic and restart my computer. Let me guess, there is a better way?

      -

      Alex: There is a slightly faster way. Visual Studio Code has a built-in Diagnostics view for Copilot Chat. You navigate to the Configure Chat gear icon, and select Diagnostics. This opens a panel that shows you every single instruction file, agent, and prompt that is currently loaded.

      -

      Jamie: Oh, so I can see if my custom agent file actually got loaded into the system.

      -

      Alex: Exactly. It will tell you if the file was found, if it loaded successfully, or if there is a syntax error in your YAML frontmatter, like a missing quote. If everything looks correct but the agent is still not showing up, you can reload the window.

      -

      Jamie: How do I do that without closing the whole program?

      -

      Alex: Press Control plus Shift plus P to open the Command Palette, type Reload Window, and press Enter. It takes about two seconds, and it completely refreshes the agent's brain, picking up any new files you just created.

      -

      Alex: And that brings us to the end of our complete reference guide for Accessibility Agents. Jamie, what are your top takeaways from today?

      -

      Jamie: Okay, first, the ecosystem is huge but manageable. We have 55 agents across three teams, and 54 slash commands. But I do not have to memorize them. I just use the orchestrator agents or the slash menu to find what I need. Second, scope and priority. My personal user settings win over the workspace rules, so I can always customize the tone and screen reader context for my own needs. Third, I can build my own agents using a simple markdown file, and I control exactly what they are allowed to do by giving them specific tools. And fourth, if I need to enforce a hard rule, I use a JSON hook. If I just want to guide the agent, I use an instructions file.

      -

      Alex: That is a perfect summary. You now have the keys to the entire customization engine. In our next episode, Episode 40, we are shifting gears. We will be looking at GitHub Actions and CI CD pipelines, and how we can integrate accessibility testing directly into the continuous integration process.

      -

      Jamie: I cannot wait. I am going to go write a custom agent to fetch my coffee. See you all next time!

      -

      Alex: Thanks for listening to Gitt Going with GitHub. Keep exploring, and keep building accessible software.

      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      - +

      Episode 40: GitHub Copilot - Complete Reference

      All Copilot features, chat participants, slash commands, and MCP servers.

      -

      Based on: Appendix W: GitHub Copilot - Complete Reference

      - - -

      Download Episode 40 (MP3)

      +

      Based on: Appendix K: GitHub Copilot - Complete Reference

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 40: GitHub Copilot - Complete Reference

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub, the audio learning series designed for blind and low-vision developers who are mastering GitHub and open source collaboration. I am Alex, and I am thrilled to be here with you.

      -

      Jamie: And I am Jamie! This is episode 40, which means we are getting close to the end of our journey, but we still have some incredibly powerful tools to cover. Today, we are doing a complete reference guide for GitHub Copilot.

      -

      Alex: That is right. Back in episode 14, we covered the absolute basics of Copilot. We talked about how it acts as an AI pair programmer, and we touched on inline suggestions. But today, we are zooming out to look at the entire Copilot ecosystem. We are going to cover the complete feature inventory, chat participants, slash commands, custom instructions, prompt files, model selection, the command line interface, and even Model Context Protocol servers.

      -

      Jamie: Okay, that sounds like a lot of steps. And honestly, a lot of jargon. I remember when I first learned GitHub a couple of years ago, hearing all those terms at once would have made me want to close my laptop and walk away.

      -

      Alex: It does sound like a lot! But here is the thing, Jamie. You have already done most of this on day one of your programming journey. You already know how to ask questions, how to search your codebase, and how to write terminal commands. This is just the exact same workflow, but with VS Code handling the heavy lifting and fetching the context for you. We are going to break every single piece down and explain not just how it works, but why it matters.

      -

      Jamie: I love that. So where do we start with the complete feature inventory? When we say GitHub Copilot today, what exactly are we talking about?

      -

      Alex: Copilot has grown far beyond just auto-completing your code. The complete feature inventory really consists of four main pillars. First, there are inline suggestions, which happen right inside your editor as you type. Second, there is Copilot Chat, which is a dedicated conversational interface inside VS Code. Third, there is Copilot in the command line interface, which brings AI assistance to your terminal. And fourth, there is Copilot for Pull Requests, which integrates directly into GitHub dot com to help you summarize and review code changes.

      -

      Jamie: Let us start with those inline suggestions, because that is where most people first encounter Copilot. When I am typing, Copilot will suggest code, which we often call ghost text. For a screen reader user, this can be a bit chaotic because the screen reader might try to announce things while you are still thinking.

      -

      Alex: Exactly. And this is a great time to review the most important accessibility workflow for Copilot. When you are typing and a suggestion appears, your screen reader might announce that an inline suggestion is available, especially if you have your accessibility signals turned on in VS Code settings. The instinct is to just press Tab to accept it, or Escape to reject it. But if the suggestion is multiple lines long, you really need to read it first.

      -

      Jamie: And reading it word by word using Control plus Right Arrow is one way to do it. On a Mac, that would be Command plus Right Arrow. That lets you accept the suggestion one word at a time, which is great for short completions. But for a whole function, that gets tedious.

      -

      Alex: Right. Which is why the Accessible View is your best friend. Whenever a suggestion appears, do not press Tab immediately. Instead, press Alt plus F 2. On a Mac, that is Option plus F 2. This opens the Accessible View.

      -

      Jamie: I wish I had known about Alt plus F 2 when I started. Can you explain exactly what the Accessible View does?

      -

      Alex: Absolutely. Think of the Accessible View like taking a photograph of a moving object. When Copilot generates text, it streams it in token by token, piece by piece. If your screen reader tries to read that live stream, it sounds broken and fragmented, like someone shouting words at you one by one as they think of them. The Accessible View captures the complete, static response and puts it into a structured, read-only text pane. You can navigate it with your up and down arrow keys at your own pace.

      -

      Jamie: And the best part is, you do not even have to wait for the response to finish generating anymore. You can press Alt plus F 2 immediately after sending a prompt, and the Accessible View will dynamically update in a screen-reader-friendly way. Once you read the suggestion and decide you want it, you just press Control plus Slash, or Command plus Slash on Mac, and it inserts the code right at your cursor. You do not even have to close the panel first.

      -

      Alex: Now let us move to the second pillar: Copilot Chat. You open this panel by pressing Control plus Shift plus I, or Command plus Shift plus I on Mac. This is where you can ask open-ended questions. But the real power comes from Chat Participants.

      -

      Jamie: Chat participants. I use these all the time, but I always explain them to people as inviting experts into a conference room. If I am in an empty room and I ask, why is this broken, nobody knows what I am talking about. But if I invite the database expert and the frontend expert into the room and ask the same question, they can look at my work and give me a specific answer.

      -

      Alex: That is a perfect analogy. In Copilot Chat, you invite these experts by typing the at symbol, followed by their name. The most common one is at workspace. When you type at workspace before your question, Copilot searches your entire VS Code project for relevant context. It looks at your open files, your file structure, and the code itself.

      -

      Jamie: So if I want to know where we define our heading hierarchy for accessibility, I would type at workspace, followed by, find all places where heading hierarchy is documented.

      -

      Alex: Exactly. Another great participant is at terminal. If you run a command and it spits out a huge, confusing error message, you can open Copilot Chat and type at terminal, what did that last command output mean? Copilot will read the buffer from your integrated terminal and explain the error. There is also at github, which lets you search issues, pull requests, and code across all of GitHub dot com right from your editor.

      -

      Jamie: And alongside those at symbol participants, we have the hash symbol variables, right? Like hash file or hash selection.

      -

      Alex: Yes. If participants are the experts in the room, the hash variables are the specific documents you slide across the table for them to look at. If you type hash file, a file picker opens, allowing you to attach any specific file to your prompt. If you type hash selection, it attaches whatever text you currently have highlighted in your editor.

      -

      Jamie: So I could highlight a really messy block of code, open chat, and type, at workspace, please review hash selection for accessibility violations.

      -

      Alex: You absolutely could. And that actually leads us perfectly into our next topic: Slash Commands.

      -

      Alex: Slash commands are built-in shortcuts for the most common tasks you might want Copilot to do. Instead of typing out a long prompt, you just type a forward slash and a specific keyword.

      -

      Jamie: I love slash commands. I think of them like the quick-dial buttons on a microwave. You could type out exactly how many minutes and seconds you want to heat up your popcorn, or you can just press the popcorn button. Slash commands are the popcorn buttons of Copilot.

      -

      Alex: That is exactly what they are. Let us go through the essential ones. First is slash explain. If you navigate to a complex block of code, select it, and type slash explain in the chat, Copilot will break down exactly what that code does in plain language. This is incredible when you are reading a new codebase.

      -

      Jamie: Then there is slash fix. If you have code with a bug or a syntax error, you select it, type slash fix, and Copilot will propose a correction.

      -

      Alex: Next is slash tests. Selecting a function and typing slash tests will generate unit tests for that specific logic. And similarly, slash doc will generate documentation comments, like JS Doc strings, for your selected code.

      -

      Jamie: There is also slash new, which is fantastic for scaffolding. If I type slash new React component for notifications, Copilot will generate the file structure and the boilerplate code for me. It saves so much repetitive typing.

      -

      Alex: And if you ever forget these, just type slash help. It will list all the available commands and participants.

      -

      Jamie: Okay, so built-in slash commands are great. But what if I want my own custom popcorn buttons? What if my team has very specific ways we write tests, or very specific accessibility rules we follow? I do not want to type those rules out every single time I ask Copilot to generate code.

      -

      Alex: This is where Custom Instructions and Prompt Files come in, and they are total game changers. Let us talk about Custom Instructions first. You can create a file in your repository at the exact path dot github slash copilot dash instructions dot md.

      -

      Jamie: And just to clarify, that is a folder named dot github, and inside it, a markdown file named copilot dash instructions.

      -

      Alex: Correct. This file is basically the employee handbook for Copilot. Whatever you write in this plain text markdown file will be quietly attached to every single request you make to Copilot in that workspace. You never have to invoke it manually.

      -

      Jamie: So what kind of things should go in the employee handbook?

      -

      Alex: Project-wide conventions. You might write things like: Include semantic HTML elements in generated markup. Never use color as the only indicator of meaning. Write commit messages using the conventional commits format. Always use active voice in documentation. Once you save that file, Copilot just knows to follow those rules.

      -

      Jamie: That is brilliant. And you can actually have VS Code generate a starting point for this file automatically, right?

      -

      Alex: Yes! If you open Copilot Chat and type slash init, it will analyze your workspace and create a tailored copilot dash instructions file for you. You can review it, tweak it, and commit it to your repository so everyone on your team gets the same consistent AI behavior.

      -

      Jamie: Now, what if I have instructions that should only apply to specific files? Like, I only want my testing rules to apply when I am looking at test files.

      -

      Alex: For that, you use Scoped Instructions. You create files with the extension dot instructions dot md. Inside these files, you can use a bit of configuration at the top called frontmatter to define when the file should activate. For example, you can set an applyTo property that tells Copilot, only use these instructions if the current file ends in dot test dot js.

      -

      Jamie: That is so smart. It keeps the context window clean. The AI does not need to read the testing rules if I am just asking it to fix a CSS bug. And what about those custom popcorn buttons we mentioned? The reusable prompt files?

      -

      Alex: Those are called Prompt Files. They live in a folder named dot github slash prompts, and they have the extension dot prompt dot md. If you create a file in there called review dot prompt dot md, you instantly get a new slash command in your chat called slash review.

      -

      Jamie: So I could write a prompt file that says, check the selected code against the Web Content Accessibility Guidelines level AA, and suggest fixes for any keyboard navigation issues. Then, anytime I want that check, I just type slash review.

      -

      Alex: Exactly. And there is a priority system here that is important to understand. You can have instructions at the Organization level, the Workspace level, and the User level. The User level refers to files stored in your personal VS Code profile folder. If there is ever a conflict, your personal User instructions always win. They override the Workspace, and the Workspace overrides the Organization. But mostly, they are additive. VS Code combines all the relevant instructions and sends them together.

      -

      Jamie: Let us talk about Model Selection. I noticed a dropdown menu at the bottom of the Copilot Chat input area. It lets me change the AI model. Why would I want to change it?

      -

      Alex: Because different models have different strengths. Think of it like hiring different types of contractors. Sometimes you need a very fast junior developer to write a quick script or format some JSON. Other times, you need a deliberate, meticulous senior architect to design a complex system from scratch.

      -

      Jamie: So if I just need a quick explanation of a terminal command, I might use a smaller, faster model. But if I am asking Copilot to refactor an entire module and ensure it handles edge cases, I want to select the most powerful model available in that dropdown.

      -

      Alex: Exactly. The interface lets you switch models on the fly depending on the complexity of the task. Keep in mind that as a screen reader user, you can navigate to this dropdown by tabbing through the bottom toolbar of the Chat view. Pressing Space or Enter will open the list of available models.

      -

      Jamie: Okay, so we have covered the editor extensively. But I spend a lot of time in the command line. Does Copilot exist outside of VS Code?

      -

      Alex: It absolutely does. If you have the GitHub CLI installed, which is the command line tool you run by typing g h, you can install the Copilot extension for it. Once you do, you get access to a feature that is like having a universal translator for your terminal.

      -

      Jamie: I definitely need a translator for some of those complex Git commands or obscure shell scripts. How does it work?

      -

      Alex: There are two main commands. The first is g h copilot suggest. You type that, followed by what you want to do in plain English. For example, g h copilot suggest find all markdown files modified in the last three days. Copilot will generate the exact terminal command you need, and even offer to run it for you.

      -

      Jamie: That is incredible. No more digging through manual pages to remember which flags to use for the find command.

      -

      Alex: Exactly. And the second command is the reverse: g h copilot explain. If you come across a command in documentation that looks like alphabet soup, you can copy it, paste it after g h copilot explain, and it will break down exactly what every single flag and argument does.

      -

      Jamie: Alright, let us tackle the jargon I mentioned earlier. MCP Servers. I see this acronym everywhere now. Model Context Protocol. What is it, and why should I care?

      -

      Alex: MCP is a breakthrough in how AI agents interact with the world. Think about it this way. By default, Copilot lives in a box. It can read your code, and it can write text. But it cannot directly browse the live internet, or query your company database, or run a Docker container. It does not have hands.

      -

      Jamie: So an MCP server gives it hands?

      -

      Alex: Yes. An MCP server is like giving Copilot a secure API badge to access specific external tools. It is an open standard protocol. If your team builds an MCP server that connects to your internal bug tracker, you can plug that server into VS Code. Suddenly, Copilot can actually look up live ticket statuses when you ask it questions.

      -

      Jamie: That makes so much sense. It is a standardized way to plug tools into the AI. I know GitHub has a community repository called awesome dash copilot, where people share these tools. You can actually install an MCP server from there that gives Copilot even more capabilities.

      -

      Alex: That is right. Awesome dash copilot is a curated ecosystem of plugins, prompts, and MCP servers. You can explore it right from your chat by typing slash plugin. It acts as a marketplace browser for community-built tools.

      -

      Jamie: We have one last pillar to cover from our feature inventory: Copilot for Pull Requests. This happens on GitHub dot com, not in VS Code, right?

      -

      Alex: Mostly, yes. When you are on GitHub dot com and you open a pull request, Copilot can help in two major ways. First, it can generate a PR summary. Instead of manually typing out a description of the twenty files you changed, Copilot reads the differences and generates a structured summary of the feature, the changes, and the impact.

      -

      Jamie: I think of that like having a proofreader write an executive summary for your report. It saves the reviewer so much time because they get a high-level overview before they dive into the code.

      -

      Alex: Exactly. And the second feature is PR reviews. Reviewers can ask Copilot to explain specific changes in the pull request, or even ask it to generate review comments checking for common bugs. It is an incredible time saver for maintainers.

      -

      Jamie: And speaking of automation on GitHub dot com, I read something in the reference material about GitHub Agentic Workflows. What is that?

      -

      Alex: That is a technical preview feature that takes AI automation to the next level. Instead of interacting with an agent in your editor, you write a markdown file describing a goal, like, create a daily status report of all open issues. You push that file to your repository, and a cloud-based AI agent runs on a schedule, reads your repository, and completes the task automatically. It is like having a tireless project manager running in your GitHub Actions pipeline.

      -

      Jamie: Wow. We have covered a massive amount of ground today. From ghost text to cloud agents. How do we summarize all of this?

      -

      Alex: Let us narrow it down to three concrete takeaways for our listeners to practice. First, make Alt plus F 2 your default reflex. Whenever Copilot suggests inline code or responds in chat, open the Accessible View. It removes the streaming noise and gives your screen reader a clean, navigable structure.

      -

      Jamie: Second, leverage chat participants and slash commands. Do not just ask generic questions. Invite the experts by using at workspace or at terminal, and use slash explain or slash fix to skip the repetitive typing.

      -

      Alex: And third, start building your project's employee handbook. Create a dot github slash copilot dash instructions dot md file in your workspace. Write down your accessibility standards and coding conventions in plain English. You will be amazed at how much better Copilot's suggestions become when it knows the rules of your specific house.

      -

      Jamie: I am definitely going to set up an instructions file today. This has been such a helpful reference guide. What are we covering in the next episode?

      -

      Alex: In episode 41, we are going to dive deep into a specific community toolset: Accessibility Agents. We will look at how to build and use custom agents specifically designed to catch accessibility violations before they ever leave your editor. It is going to be incredibly practical.

      -

      Jamie: I cannot wait for that one. Thank you all for listening to Gitt Going with GitHub.

      -

      Alex: Keep exploring, keep coding, and we will see you in the next episode.

      +

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      - +

      Episode 41: Copilot AI Models

      Model comparison, strengths, plan availability, and selection guidance.

      -

      Based on: Appendix X: Copilot AI Models

      - - -

      Download Episode 41 (MP3)

      +

      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 to Gitt Going with GitHub, the audio series where we build your open source skills from the ground up. I am Alex, and today we are diving into Episode 41, titled Copilot AI Models.

      -

      Jamie: And I am Jamie. I am so excited for this one. We have been using GitHub Copilot in the last few episodes, asking it to explain code and help us write functions. But today we are looking under the hood.

      -

      Alex: Exactly. If you are just joining us, you might want to review Episode 13 where we installed Copilot in Visual Studio Code, and Episode 40 where we covered the basics of interacting with the chat panel. Today, we are talking about the actual brains powering those interactions. Because Copilot is not just one single artificial intelligence. It is actually a collection of many different AI models that you can choose from.

      -

      Jamie: That was a huge aha moment for me when I first started learning GitHub a couple of years ago. I thought Copilot was just one big brain sitting on a server somewhere. But it is more like a whole team of developers with different specialties, right?

      -

      Alex: That is a perfect analogy. And GitHub has built something really unique here. Instead of forcing you to use just one provider, they have partnered with several of the biggest names in artificial intelligence. Inside Copilot, you have access to models from OpenAI, which makes the GPT and Codex models. You also have Anthropic, which makes the Claude models. Google is here with their Gemini models. And xAI is available with their Grok models.

      -

      Jamie: It is like having a workshop where you can call over a master carpenter, an electrician, or an architect depending on what you need to build. But with so many options, how do you even begin to understand the differences between them?

      -

      Alex: We can break it down by looking at three main characteristics. Speed, quality, and context window size. Let us define that last term first, because it is crucial. A context window is the amount of text, code, and conversation history that the AI can hold in its short-term memory at one single time.

      -

      Jamie: I love talking about context windows. The way it finally clicked for me was thinking about my physical physical desk. If I have a tiny desk, I can only have one or two reference books open while I am working. If I need to look at a third book, I have to close one and put it away. That is a small context window. But a massive context window is like having a giant conference table where I can spread out fifty documents, my entire project codebase, and all my error logs, and look at them all at once.

      -

      Alex: That is exactly right. A larger context window means the AI can understand how a function in your database file connects to a variable in your user interface file, because both files fit on its mental conference table at the same time. But here is the trade-off. Models with giant context windows, or models that are built for extremely high quality and deep reasoning, are usually slower. And they require more computing power.

      -

      Jamie: Which brings us to the speed versus quality trade-off. It is like choosing between a quick spell-check and a deep structural edit of a novel. If I just want to know the keyboard shortcut to save a file, I want the answer instantly. I do not need the AI to ponder the philosophical implications of saving data. I just want a fast answer.

      -

      Alex: Precisely. So let us talk about how to match the right model to the right task, starting with general purpose coding and writing. For everyday tasks, like simple code completions, writing documentation, or explaining a standard function, you want a reliable, fast default. Right now, as of February 2026, the standard workhorses are OpenAI models called GPT 4.1 and GPT 5 mini. They are incredibly fast, very accurate, and they handle most everyday tasks effortlessly.

      -

      Jamie: And they are free to use, right? We will get into the pricing plans in a minute, but I know I use GPT 5 mini for almost everything. It is just so snappy. But what if I have a really repetitive task, like I need to rename twenty variables, or I need boilerplate code for a basic HTML page?

      -

      Alex: For tasks where speed is your absolute top priority, you can switch to models specifically optimized for fast help. Anthropic has a model called Claude Haiku 4.5. Google has Gemini 3 Flash. And OpenAI has Grok Code Fast 1 and a Codex Mini variant. These models are lightweight. They do not do well if you ask them to architect a complex database, but if you ask them to write a quick regular expression to validate an email address, they will give you the answer before you even finish taking a breath.

      -

      Jamie: Okay, so we have the everyday models and the super fast models. But what about when things get really complicated? Like last week, I had a bug where my screen reader was not announcing a status update on a web page, and the problem was buried somewhere between three different JavaScript files and an ARIA live region. A fast model would probably just guess and get it wrong.

      -

      Alex: Exactly. That is when you need to bring in the heavy hitters for deep reasoning and debugging. This is where you want to use Anthropic models like Claude Sonnet 4.6, or Claude Opus 4.6. Or OpenAI models like GPT 5.2. These models are designed to stop, think, and analyze complex multi-file problems.

      -

      Jamie: Bringing in Claude Opus is like escalating a bug to the senior staff engineer. You know it might take them a few extra seconds to reply, but they are going to give you a deeply considered, architectural answer.

      -

      Alex: Yes, and they excel at understanding unfamiliar codebases. If you join a new open source project and you need someone to explain how their authentication flow works across ten different files, Claude Opus or Gemini 3 Pro are the models you want reading those files.

      -

      Jamie: We should also talk about a term that has been popping up a lot lately. Agentic software development. I hear people saying Copilot has an Agent mode now. What does agentic actually mean in this context?

      -

      Alex: Agentic simply means the AI acts as an autonomous agent. In a standard chat, you ask a question, the AI gives you an answer, and you have to go copy and paste the code yourself. In Agent mode, you give Copilot a goal, like, set up a new testing framework for this project. The AI will then independently write the code, open your terminal, run the installation commands, read the error messages if something fails, fix its own mistakes, and keep iterating without you needing to guide it step by step.

      -

      Jamie: That sounds slightly terrifying but mostly amazing. Does it use a specific model for that? Because I imagine you need a very smart model to let it run its own terminal commands.

      -

      Alex: You do. And for agentic tasks, OpenAI has created specialized models under the Codex name. Right now, the recommended model for this is GPT 5.1 Codex Max, or GPT 5.2 Codex. These are explicitly trained for autonomous reasoning and multi-step execution.

      -

      Jamie: What about visuals? As a totally blind developer, I obviously do not work with visual mockups. But occasionally, a sighted designer will hand me an image file of a user interface and ask me to build it. Can these models help with that?

      -

      Alex: They absolutely can, and this is a fantastic accessibility use case. Several models support image input, meaning you can paste an image directly into the Copilot chat. GPT 5 mini, Claude Sonnet, and Gemini 3 Pro all understand images. You could paste that design mockup into the chat and type, please describe the structural layout of this image and generate the semantic HTML to build it. The AI will analyze the visual layout and translate it into code for you.

      -

      Jamie: That is brilliant. I wish I had known that when I started. It completely removes the barrier of needing a sighted colleague to describe a screenshot to me.

      -

      Alex: Now that we know about all these different models, we need to talk about how you actually get access to them. GitHub Copilot has several different subscription plans. There is Copilot Free, Copilot Pro, Copilot Pro Plus, Business, and Enterprise.

      -

      Jamie: And this is where the concept of premium requests comes in, right? Because not all models cost the same amount of resources to run.

      -

      Alex: Exactly. Let us use an arcade token analogy. Imagine your Copilot subscription gives you a certain number of tokens every month. The fast, everyday models like GPT 4.1 and GPT 5 mini have a cost multiplier of zero. They are free games. You can play them all day long and they never use up your premium tokens.

      -

      Jamie: So if I am on the completely free tier of Copilot, I can still use those zero-multiplier models as much as I want?

      -

      Alex: Well, on the Free tier, you have a hard limit of 50 total requests per month. But if you are on any paid plan, like Pro or Business, you can use the zero-multiplier models infinitely.

      -

      Jamie: Got it. But what if I want to play the really fancy arcade game? The deep reasoning models like Claude Opus?

      -

      Alex: Those models have a higher cost multiplier. For example, Claude Opus 4.6 has a multiplier of three. That means every single message you send to Claude Opus consumes three of your premium requests. The mid-tier models, like Claude Sonnet or GPT 5.2, have a multiplier of one. They consume one premium request per message.

      -

      Jamie: Okay, so if I am on the standard Copilot Pro plan, which gives me 300 premium requests a month, I need to budget them. I should not use Claude Opus to ask how to center a text element, because that is wasting three tokens on a problem that the free GPT 5 mini model could solve for zero tokens.

      -

      Alex: Exactly. You want to save those premium requests for the truly demanding tasks. Now, if you are on Copilot Pro Plus or Copilot Enterprise, you have unlimited premium requests, so you do not have to worry about quotas. But for everyone else, managing that multiplier is an important part of your workflow.

      -

      Jamie: Alright, let us get practical. I am in Visual Studio Code right now. How do I actually switch between these models?

      -

      Alex: Let us start with the Chat panel. First, you press Control plus Shift plus I to open the chat view. Your focus will naturally land in the text input area where you type your messages.

      -

      Jamie: Okay, I am there.

      -

      Alex: Now, the model picker is a button located in the toolbar that sits right below that text input area. If you press the Tab key to navigate through the chat input toolbar, you will move past the attach button, and the next item your screen reader announces should be the name of the currently active model. It might say something like Auto, or Claude Sonnet 4.6, button.

      -

      Jamie: I just pressed Tab, and my screen reader said, Auto, model picker button.

      -

      Alex: Perfect. Press Space or Enter to activate that button. It opens a dropdown menu listing all the available models on your plan. You can just use your Up and Down Arrow keys to move through the list. When you hear the one you want, press Enter to select it. Your screen reader will then announce the newly selected model, and your focus returns to the chat input area so you can start typing.

      -

      Jamie: That is really straightforward. And what about Inline Chat? We talked about that a few episodes ago, where you press Control plus I to open a quick chat directly inside your code editor instead of opening the side panel. Can I switch models there too?

      -

      Alex: You can. When you press Control plus I to open Inline Chat, a small toolbar appears in your editor. The model picker button is right there in that toolbar. The interaction is exactly the same. You navigate to the button, open the dropdown, and select your model.

      -

      Jamie: But wait, does changing the model in the chat panel also change the model that gives me those automatic ghost text suggestions while I am typing? You know, the inline completions that just appear as I type?

      -

      Alex: That is a fantastic question, and the answer is no. This is a really important distinction. Model selection only affects your conversational chats. The automatic inline suggestions that appear as you type are handled completely separately.

      -

      Jamie: Why is that?

      -

      Alex: Because inline suggestions have to be instantaneous. If you are typing a function, you cannot wait five seconds for Claude Opus to ponder the meaning of your code. You need a suggestion in milliseconds. So GitHub exclusively uses highly specialized, hyper-fast models for inline completions. Right now, those are fine-tuned OpenAI models called Raptor mini and Goldeneye. You cannot manually switch those. GitHub manages them in the background to guarantee speed. You only choose models for the Chat and Agent interactions.

      -

      Jamie: Earlier, my screen reader announced that my selected model was Auto. What exactly does Auto do?

      -

      Alex: Auto mode is the default setting, and honestly, it is what most developers should use most of the time. Think of it like an automatic transmission in a car. You do not have to manually shift gears. Copilot analyzes your prompt and automatically routes it to the best model.

      -

      Jamie: So if I ask a simple question, it automatically routes to a fast, zero-multiplier model. But if I ask it to debug a massive architectural issue, it automatically shifts into a higher gear and routes to a deep reasoning model?

      -

      Alex: Exactly. And if you give it an agentic task, it automatically selects a Codex model. It manages your premium requests intelligently. You can always check which model it decided to use by navigating to the response details after it replies.

      -

      Jamie: If Auto is so smart, why would I ever manually override it and pick a specific model?

      -

      Alex: A few reasons. Sometimes you might be running low on premium requests for the month, so you manually lock it to GPT 5 mini to ensure you do not spend any more tokens. Or, you might find that for your specific programming language, say you write a lot of obscure Haskell code, you find that Claude Sonnet consistently gives you better answers than the model Auto chooses. Finally, if you want to use the vision capabilities to analyze an image, you might manually select a model that you know supports images, just to be safe.

      -

      Jamie: That makes sense. If I manually select a model, how do I get back to Auto mode?

      -

      Alex: You just open the model picker dropdown again using the steps we discussed, arrow to the very top of the list, and select Auto. It is just another option in the menu.

      -

      Jamie: One thing I have noticed over the last two years is that the models keep changing. I remember when everyone was talking about GPT 4, and now we are talking about GPT 5.2. It feels hard to keep up.

      -

      Alex: It is a fast-moving landscape. GitHub regularly updates the roster. They bring in newer, smarter models and they retire the older ones. It is just like getting software updates on your phone. Eventually, the old version is no longer supported.

      -

      Jamie: What happens if my favorite model gets retired? Like, what if I manually set my chat to use Claude Sonnet 3.5, and then GitHub retires it? Will my Copilot just break?

      -

      Alex: No, Copilot handles it gracefully. When a model is officially retired, Copilot simply stops sending requests to it and automatically falls back to the nearest equivalent newer model. So you would just be upgraded to Claude Sonnet 4.

      -

      Jamie: That is a relief. Is there a way to know when models are being added or retired so I am not caught off guard?

      -

      Alex: Yes, the best place to track this is the official GitHub Copilot changelog on the GitHub blog. They announce all model additions and retirements there. It is a great resource to check once a month just to see what new tools have been added to your workshop.

      -

      Jamie: This has been incredibly enlightening. I feel like I finally understand what is happening behind the scenes. What are our key takeaways for today?

      -

      Alex: First, remember that Copilot gives you access to multiple AI providers, including OpenAI, Anthropic, Google, and xAI. Second, match the model to the task. Use fast, free models like GPT 5 mini for everyday questions, and save the powerful models like Claude Opus for complex debugging to conserve your premium requests.

      -

      Jamie: Third, you can easily switch models in Visual Studio Code by pressing Control plus Shift plus I to open the chat panel, and tabbing to the model picker button. And fourth, when in doubt, just leave it on Auto mode and let Copilot do the driving for you.

      -

      Alex: Perfectly summarized. Now that you know how to choose the right brain for the job, you need to know how to talk to it effectively. In our next episode, Episode 42, we are going to cover Writing Effective Copilot Prompts. We will learn how to structure your questions to get the highest quality code out of whichever model you choose.

      -

      Jamie: I definitely need that. Half the time I feel like I am arguing with the AI because I did not explain myself clearly. I cannot wait.

      -

      Alex: It is going to be a great discussion. Until then, keep experimenting with those different models, and happy coding.

      +

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

      +
      +

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

      +
      +

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

      +
      +

      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 41. Next in the series is episode 42, where we keep building the same contributor muscles.

      - +

      Episode 42: Accessing Workshop Materials

      Downloading the repository, reading offline, keeping updated, audio format.

      Based on: Appendix Y: Accessing Workshop Materials

      - - -

      Download Episode 42 (MP3)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 42: Accessing Workshop Materials

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub, the audio learning series designed specifically for blind and low-vision developers who are navigating the world of open source. I am Alex, and as always, I am thrilled to be here with you.

      -

      Jamie: And I am Jamie! I am a developer who learned GitHub about two years ago, and I am here to ask all the questions that you are probably thinking as you listen.

      -

      Alex: Today we are diving into Episode 42, which is all about Accessing Workshop Materials. We have covered so much ground in this series. We have talked about branches, commits, pull requests, and navigating the GitHub interface. But today, we are taking a step back to talk about the materials themselves.

      -

      Jamie: Yes, and I am so glad we are doing this. When I attended my first developer workshop, I was so overwhelmed. The instructor sent out a link to a GitHub repository, and I navigated to it, and there were just dozens of files. There was a docs folder, an HTML folder, a scripts folder, markdown files everywhere. I spent the first hour just trying to figure out where the actual reading material was, while everyone else was already starting the exercises.

      -

      Alex: That is incredibly common, and it is exactly why we dedicated an entire appendix in the written guide, and this entire podcast episode, to this topic. A repository for a workshop is essentially a giant filing cabinet. If you do not know how the cabinet is organized, or how to take the files out of it, you are going to feel lost.

      -

      Jamie: Exactly. So, I know we have a few prerequisites for today. Listeners should already be familiar with what a repository is, and they should know the basic concept of Git, which we covered way back in our first few episodes.

      -

      Alex: Spot on. If you know what a repository is, you are ready for this episode. Today, we are going to talk about how to get the workshop materials, how to read them offline, how to keep your copy updated when the instructor adds new content, and the different formats we offer, including HTML, Markdown, and the very audio format you are listening to right now.

      -

      Jamie: I love it. Where should we start?

      -

      Alex: Let us start by talking about the formats. We provide the workshop materials in multiple ways because different developers have different accessibility needs and learning preferences. The first format is the one we are using right now. The podcast audio series.

      -

      Jamie: Which is so meta! We are in the podcast, talking about the podcast.

      -

      Alex: We are! But the audio format serves a very specific purpose. Listening to someone explain a technical concept is completely different from reading a technical document with your screen reader. When you are reading code or step-by-step instructions, your brain is doing a lot of work parsing the syntax, the keystrokes, and the formatting.

      -

      Jamie: Oh, absolutely. When my screen reader is reading a markdown file, I am listening to every heading level, every list item, every piece of punctuation in a code block. It is a high cognitive load.

      -

      Alex: Exactly. So the podcast format is designed to be your conceptual introduction. Think of it like having a study buddy sitting in the passenger seat of your car. You can listen to us while you commute, or while you are doing the dishes. We explain the why, the overarching concepts, and the analogies. Then, when you actually sit down at your computer to read the written materials, you already have the mental model. The written materials are for the exact keystrokes and the technical reference.

      -

      Jamie: That makes so much sense. I wish I had this audio series when I started. Okay, so aside from the podcast, the written materials come in two main formats. Markdown and HTML. Can you break down the difference for someone who might be new to those terms?

      -

      Alex: I would love to. Markdown is a plain text format. It uses very simple punctuation to indicate formatting. For example, a single number sign before a word makes it a heading. We use Markdown because it is the standard language of GitHub. Every repository has a README file written in Markdown. It is lightweight, and you can write it in any simple text editor.

      -

      Jamie: And screen readers handle plain text really well.

      -

      Alex: They do. But plain text does not have the rich navigational structure that a fully built website has. That is where HTML comes in. HTML stands for HyperText Markup Language. It is the code that powers web pages. We have an automated script that takes all our simple Markdown files and transforms them into beautifully structured HTML pages.

      -

      Jamie: I think an analogy would help here. How should I picture the relationship between Markdown and HTML?

      -

      Alex: Think of Markdown as the script for a play. It has the raw dialogue and the basic stage directions. It gets the point across perfectly. But HTML is the final stage production. It has the lighting, the sets, the costumes, and the ushers guiding you to your seat. The content is exactly the same, but the presentation and the navigation are much more polished.

      -

      Jamie: Oh, I love that. The ushers guiding you to your seat is a great way to describe ARIA landmarks and skip links.

      -

      Alex: Exactly. Our HTML files include breadcrumb navigation, skip-to-content links, and ARIA landmarks. ARIA stands for Accessible Rich Internet Applications, and landmarks are invisible signposts that tell your screen reader where the main content begins, where the navigation menu is, and so on.

      -

      Jamie: So let us say I am attending the workshop, and I want the fully produced stage play. I want the HTML version with all those navigational signposts. How do I get to it? Do I have to download something?

      -

      Alex: You do not have to download anything if you do not want to. The absolute easiest way to read the materials during the workshop is by browsing online using GitHub Pages.

      -

      Jamie: GitHub Pages. We have mentioned that before, but what is it exactly?

      -

      Alex: GitHub Pages is a free service provided by GitHub that takes the HTML files in your repository and publishes them as a live website. For our workshop, your facilitator will give you a specific web address. Usually, it looks something like community hyphen access dot org slash Learning hyphen Room.

      -

      Jamie: So it is just a regular website. I open my browser, I navigate to that URL, and I am there.

      -

      Alex: Exactly. It is like walking into a well-organized public library. Everything is already on the shelves. When you load the page, you will be on the index dot html file, which serves as the homepage. From there, you can use standard screen reader commands to move around.

      -

      Jamie: Let us talk about those commands, because navigation is everything. When I land on that GitHub Pages site, what is the fastest way to get to the actual reading material?

      -

      Alex: The fastest way is to use your landmark jump key. In NVDA, you press the D key. In JAWS, you press the R key. That will jump you straight to the main landmark, bypassing all the top-level navigation and the headers.

      -

      Jamie: That saves so much time. I used to just press the down arrow fifty times until I heard something that sounded like a paragraph.

      -

      Alex: We have all been there. Once you are in the main landmark, use your heading key, which is the H key, to move through the sections. All the chapters and appendices are linked. If the text references Appendix A, you can just press Enter on that link, and it will take you right to Appendix A. It is a completely seamless online reading experience.

      -

      Jamie: Okay, so GitHub Pages is the polished library. But what if the facilitator has not set up GitHub Pages, or what if I just want to read the raw Markdown files directly on the GitHub website? Can I do that?

      -

      Alex: You absolutely can. You can read every single file directly on GitHub dot com without downloading a thing. You just navigate to the repository link that your facilitator shares.

      -

      Jamie: But this is where I used to get stuck. I would get to the repository page, and my screen reader would just read a massive table of files and folders. How do I actually find chapter one?

      -

      Alex: Great question. When you load a repository page on GitHub, the main content area contains a grid or a table of all the files. You can press the T key on your keyboard to jump straight to the file table, and then use your arrow keys to move through the rows. You will find a folder called docs. That is where all the written chapters live.

      -

      Jamie: Wait, did you just say I can press T to jump to the table?

      -

      Alex: Actually, I should clarify. If you are in browse mode, T jumps to the table. But GitHub has a built-in keyboard shortcut that is even better. If you turn your screen reader's browse mode off, or pass the key through, and you press the letter T anywhere on the repository homepage, it opens the file finder.

      -

      Jamie: The file finder? I do not think I know what that is.

      -

      Alex: It is a dynamic search field. When you press T, an edit box pops up. You can just type a word, like pull requests, or chapter five. GitHub instantly filters the entire repository and shows you only the files that match. You arrow down to the one you want, press Enter, and you are inside the file.

      -

      Jamie: Mind blown. That is so much faster than digging through folders manually. It is like having a digital assistant where you just say the name of the file and it hands it to you.

      -

      Alex: Exactly. And once you open a Markdown file on GitHub dot com, GitHub automatically renders it. It turns the number signs into actual headings, and it formats the code blocks. So you can still use your H key to navigate by headings, even though it is technically a Markdown file.

      -

      Jamie: Okay, so reading online is great. But what if I am going to be on a train with no internet, or what if I just want all the files on my own computer so I can open them in my own editor? That sounds like a lot of steps.

      -

      Alex: It does sound like a lot, but here is the thing. You have already done most of this on Day 1 of the workshop. It is the exact same workflow you use for any code project. To get the files onto your computer, you need to download everything. And you have two options for this. Option A is cloning the repository with Git. Option B is downloading a ZIP file.

      -

      Jamie: Let us start with Option A, cloning. What does that mean, and how do I do it?

      -

      Alex: Cloning means using the Git command line tool to create a complete, fully functioning copy of the repository on your local computer. You open your terminal, and you type git, space, clone, space, and then you paste the web address of the repository. So it would be git clone https colon slash slash github dot com slash community hyphen access slash Learning hyphen Room dot git.

      -

      Jamie: And when I press enter on that command, what happens?

      -

      Alex: Git reaches out to GitHub, gathers every single folder, every file, every image, and every bit of history, and pulls it down into a new folder on your computer.

      -

      Jamie: That sounds powerful. But what if I am not comfortable with the command line yet? What is Option B?

      -

      Alex: Option B is downloading a ZIP file. You do not need Git installed for this. You just go to the repository page on GitHub dot com. You navigate to a button called the Code button. It is a green button near the top of the file listing, right after the branch selector.

      -

      Jamie: How do I find the Code button with my screen reader?

      -

      Alex: If you are at the top of the page, you can press the letter B to jump from button to button. You will hear things like Watch, Fork, Star, and eventually, you will hear Code collapsed button. You press Space or Enter to expand it, and a dropdown menu appears. You just arrow down through that menu until you hear Download ZIP, and you activate it.

      -

      Jamie: And then it just downloads a standard ZIP folder to my downloads directory, and I can extract it like any other file.

      -

      Alex: Exactly right. You extract it, and you have all the exact same files as if you had cloned it.

      -

      Jamie: Okay, so I have to ask. If downloading a ZIP is so easy, and I do not have to use the terminal, why do you recommend cloning instead?

      -

      Alex: That is a brilliant question. I want to use an analogy here. Think about getting your news. Downloading a ZIP file is like walking to the newsstand and buying a printed newspaper. You have all the information that existed at the exact moment you bought it. But tomorrow, when new things happen, your printed newspaper will not update. It is static. A snapshot in time.

      -

      Jamie: Right. If the workshop facilitator adds a new chapter on day two, my ZIP file from day one will not have it.

      -

      Alex: Exactly. But cloning with Git is like signing up for a smart digital subscription. You get all the current news today. And tomorrow, you can just ask the service for any updates, and it will only send you the new articles, slotting them perfectly into your existing app. Cloning keeps your local folder connected to the original source on GitHub.

      -

      Jamie: That makes perfect sense. Okay, so I have used Git clone, and now I have a folder on my computer called Learning hyphen Room. It is full of stuff. I want to read chapter one offline. How do I do that?

      -

      Alex: The best way to read the materials offline is to open the entire folder in a text editor like Visual Studio Code, which we call VS Code. You open your terminal, you type cd space Learning hyphen Room to move into the folder, and then you type code space dot. That is the word code, a space, and a period.

      -

      Jamie: I use that command all the time. It opens VS Code and loads the current folder into the workspace.

      -

      Alex: Yes. And once VS Code is open, you can use the Explorer pane to browse the files. The keyboard shortcut to focus the Explorer is Control plus Shift plus E.

      -

      Jamie: Let us break down what is actually in this folder, because the structure can be intimidating. When I open the Explorer, what folders am I going to find?

      -

      Alex: You will see a few main folders. First is the docs folder. This is where all the Markdown files live. Chapters zero through sixteen, and all the appendices. If you want to read the raw text, you open these files.

      -

      Jamie: And what if I want the pretty, formatted version? The stage play?

      -

      Alex: Then you navigate to the html folder. This folder contains the exact same content, but pre-built into HTML files. You can actually open the index dot html file directly in your web browser. Just locate it in your computer's file explorer, press Enter, and it will open in Chrome or Edge or Firefox. It works exactly like the online GitHub Pages site, but it is running entirely off your hard drive. No internet required.

      -

      Jamie: That is so cool. It is like pitching your tent in the woods and having all your supplies with you. You are completely self-sufficient.

      -

      Alex: Exactly. And there is one more folder you will see, called the learning hyphen room folder. This is where the actual practice exercises live. When the facilitator tells you to complete a challenge, you will find the instructions and the starting code in that folder.

      -

      Jamie: Okay, so if I decide to read the Markdown files in VS Code, instead of the HTML files in the browser, is there a way to make the Markdown look a bit nicer? Like, instead of my screen reader saying number sign number sign Chapter One, can it just read it as a heading level two?

      -

      Alex: Yes! VS Code has a fantastic built-in feature called Markdown Preview. If you open a Markdown file in the editor, you can press Control plus Shift plus V. That is V as in Victor.

      -

      Jamie: What does that shortcut do?

      -

      Alex: It opens a new pane that renders the Markdown as rich text. Your screen reader will interact with it almost exactly like a web page. You can use your H key to jump by headings, your list commands to read bullet points, and it hides all the raw punctuation. It is a wonderful way to read offline if you prefer to stay inside VS Code rather than opening a browser.

      -

      Jamie: I am learning so many shortcuts today. Control plus Shift plus E for the Explorer, Control plus Shift plus V for the Markdown preview. This is great. But let us go back to that smart subscription analogy. You said if I clone the repository, I can easily get updates. Let us say it is day two of the workshop. The instructor says, I just fixed a typo in chapter four and added a new cheat sheet. How do I get those updates into my local folder?

      -

      Alex: This is where the magic of Git comes in. All you have to do is open your terminal, make sure you are inside the Learning hyphen Room folder, and type a two-word command. Git pull. That is G I T, space, P U L L.

      -

      Jamie: Git pull. I love that name because you are literally pulling the changes down from the internet into your computer.

      -

      Alex: Exactly. It is like refreshing your podcast app to see if a new episode has dropped. When you run git pull, Git checks the original repository on GitHub, sees what has changed since your last visit, and seamlessly merges those changes into your local files.

      -

      Jamie: What if I made a change to a file? Like, what if I was taking my own notes inside chapter four, and then I run git pull. Will it overwrite my notes?

      -

      Alex: Git is very safe. It will not overwrite your local changes without asking. If you modified the exact same line that the instructor modified, Git will pause and say, wait a minute, we have a merge conflict. It will ask you to decide which version to keep. We actually have an entire chapter dedicated to merge conflicts, because they sound scary, but they are just Git's way of being cautious.

      -

      Jamie: That is reassuring. Now, if I run git pull, does it update both the Markdown files and the HTML files?

      -

      Alex: Usually, yes, because we commit the updated HTML files to the repository. But if for some reason the HTML files are out of sync, we include a simple script you can run. In your terminal, you just type npm space run space build colon html.

      -

      Jamie: Wait, spell that out for me.

      -

      Alex: Sure. N P M, space, run, space, build, colon, html. That command runs a small program on your computer that reads all the Markdown files and generates fresh HTML files. So if you ever edit the materials yourself and want to see the changes in the browser, you just run that command.

      -

      Jamie: Okay, we have covered reading online, downloading everything, reading offline, and staying updated. I have one last scenario. What if I do not want the whole repository? What if I literally just want the keyboard shortcut cheat sheet so I can print it out or emboss it in Braille? Can I download just one file?

      -

      Alex: You absolutely can, and I highly recommend doing this for reference sheets. If you are on the GitHub dot com website, and you have navigated to a specific file, let us say the cheat sheet markdown file. You open it, and right above the content of the file, there is a small toolbar of buttons.

      -

      Jamie: What buttons are in that toolbar?

      -

      Alex: You will hear things like Preview, Code, Blame, and Raw. You want to navigate to the Raw button and activate it.

      +

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

      +

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

      +

      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.

      +
      +

      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.

      - +

      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

      - - -

      Download Episode 43 (MP3)

      +

      Audio and transcript are being regenerated for this episode.

      Read Transcript - Episode 43: GitHub Skills - Complete Course Catalog

      Transcript

      -

      Alex: Welcome to Gitt Going with GitHub, the audio learning series for blind and low-vision developers. I am Alex, and today we are diving into Episode 43, GitHub Skills and the Complete Course Catalog.

      -

      Jamie: And I am Jamie! We are getting so close to the end of our series, which matches up with the end of Day 2 of the workshop. Today is all about what happens next. How do you keep learning once the workshop is over?

      -

      Alex: Exactly. During the workshop, you have a lot of support. You have facilitators, you have the learning room, you have us in your ears. But when you go back to your desk on Monday, you might feel a little stranded. That is where GitHub Skills comes in.

      -

      Jamie: I remember when I was learning GitHub about two years ago. I would read these long, static tutorials, and I would try to follow along in my own repository, but I was never quite sure if I did it right. There was no feedback loop. I wished I had someone looking over my shoulder saying, yes, you created that branch correctly.

      -

      Alex: That is the exact problem GitHub Skills solves. GitHub Skills is a free, interactive, self-paced learning platform. But what makes it truly special for our community is that there is no separate website, no external video portal, and no custom interface to learn. Every single course runs entirely inside GitHub itself.

      -

      Jamie: Which is huge for accessibility. You do not have to learn a whole new set of keyboard shortcuts or figure out how a completely different website is structured. You just use the heading navigation and landmark jumping skills you have already been practicing.

      -

      Alex: Right. The way it works is brilliant. It is like an interactive flight simulator. You are not watching someone else fly; you are at the controls. When you start a course, GitHub copies a template repository directly into your own account. It is your repository, completely private to you unless you choose to make it public.

      -

      Jamie: And then you meet Mona.

      -

      Alex: Yes, Mona! Mona is GitHub's automated learning bot. Once the repository is copied to your account, Mona uses GitHub Actions in the background to act as your personal instructor. Within about twenty seconds of starting a course, Mona will open an issue in your new repository.

      -

      Jamie: And just as a quick refresher, an issue is essentially a discussion thread used to track tasks, bugs, or feature requests. So Mona opens this issue, and the first comment will be your instructions for Step 1. It might say something like, welcome to the course, your first task is to create a new branch.

      -

      Alex: You read the instructions, and then you just do the task right there in your repository. You create the branch, or you edit a file, or you open a pull request. A pull request, of course, being the formal way you ask to merge your code changes into the main project.

      -

      Jamie: So you do the work, and then what? How does Mona know you did it?

      -

      Alex: Because Mona is listening for those events. When you open that pull request, the bot detects your action, validates that you did it correctly, and then immediately posts the next step. It might leave a comment on your pull request saying, great job, now let us try leaving a code review comment. You just keep following the prompts until Mona closes the final issue with a congratulatory completion message.

      -

      Jamie: It is so satisfying to get that final message. OK, that sounds like a lot of automated steps, but I want to normalize this for a second. It might sound intimidating to have a bot watching your repository, but you have already done this. The workflow is exactly what you practiced on Day 1. You are just reading issues, making commits, and managing pull requests.

      -

      Alex: Absolutely. Now, before we get into the massive catalog of courses, let us talk about how to start a course and track your progress. To start, you simply navigate to the specific course URL, which we list in Appendix Z of the workshop materials, and activate the Start course button.

      -

      Jamie: But tracking progress is a little quirky, right? Because there is no central dashboard that says, Jamie has completed five out of thirty-six courses.

      -

      Alex: That is correct. GitHub Skills does not have a central profile dashboard. But there are a few practical ways to track your learning. First, all of these courses create repositories in your account that start with the prefix skills hyphen. So, you can just navigate to your repositories page and filter by the word skills to see everything you have started.

      -

      Jamie: Oh, that is clever! I also like to bookmark Mona's final completion message in my browser, just as a little digital trophy.

      -

      Alex: That works too! You can also pin your favorite completed course repositories to your main GitHub profile. And finally, Appendix Z has a personal completion checklist. You can literally just copy that markdown list into a private issue or a local text file and check off the boxes as you go.

      -

      Jamie: Alright, let us talk about the courses themselves. There are thirty-six modules in total, organized into different learning paths. But before we hit the advanced stuff, there are three courses that are actually woven into Day 1 of the workshop.

      -

      Alex: Yes, the beginner path, or the workshop courses. These are Introduction to GitHub, Communicate Using Markdown, and Review Pull Requests.

      -

      Jamie: Introduction to GitHub is the classic starting point. It teaches you the core flow: how to create branches, make commits, open pull requests, and merge them. A commit is basically saving a snapshot of your work, and a branch is a safe parallel universe where you can make those commits without affecting the main project.

      -

      Alex: Then you have Communicate Using Markdown. Markdown is the lightweight formatting language used everywhere on GitHub. This course teaches you how to format headings, add emphasis, create links, format code blocks, and build task lists and tables, all using plain text characters.

      -

      Jamie: And the third one is Review Pull Requests. This is where you practice assigning reviewers, leaving comments on specific lines of code, suggesting changes, and finally approving and merging.

      -

      Alex: If you are listening to this and you did not finish those three modules during Day 1, that is your very first prerequisite. Go finish those before you attempt anything else. They are the foundation of everything we do on GitHub.

      -

      Jamie: Once those are done, we have six distinct learning paths to choose from. You do not have to do all of them, right? You just pick the path that matches your goals.

      -

      Alex: Exactly. Let us start with Path 1, Git Fundamentals. This path is for deepening your understanding of the underlying version control system. It includes three courses: Introduction to Git, Resolve Merge Conflicts, and Change Commit History.

      -

      Jamie: Resolve Merge Conflicts used to terrify me. A merge conflict happens when two people edit the exact same line of code in different ways, and Git essentially throws its hands up and says, I do not know which version to keep, you figure it out.

      -

      Alex: It is a great analogy. Imagine two authors collaborating on a book. If you both rewrite the exact same paragraph in chapter two, the publisher cannot just mash them together. Someone has to read both versions and write a final, combined paragraph. That is all a merge conflict is. This course teaches you why they happen, how to read the text markers that Git inserts to show you the two versions, and how to resolve them safely using the web editor.

      -

      Jamie: And what about Change Commit History? That sounds like time travel.

      -

      Alex: It is time travel! Sometimes you make a typo in a commit message, or you want to combine five messy commits into one clean one before you share your work. This course teaches you how to amend commits, squash them together, and reorder your history using a tool called interactive rebase. It requires the Introduction to Git course as a prerequisite, but it is incredibly powerful once you learn it.

      -

      Jamie: Path 2 is GitHub Collaboration. This feels like the path for people who want to become open source maintainers or run projects for their team.

      -

      Alex: Spot on. This path extends the labels and milestones you learned in Day 1 into full repository management. The recommended order starts with Introduction to Repository Management.

      -

      Jamie: This is where you learn about branch protection, right? Like setting rules that say, nobody is allowed to merge code into the main branch unless it has been reviewed by at least two people.

      -

      Alex: Exactly. You also learn how to create issue templates, so when someone reports a bug, they get a predefined form asking for reproduction steps and screen reader versions, rather than just a blank text box. It is like running a community center. You need rules, you need clear signs, and you need structure so everyone can collaborate safely.

      -

      Jamie: The next course in this path is Connect the Dots.

      -

      Alex: Yes, this teaches you how to cross-reference work. How to mention an issue inside a pull request so that when the pull request merges, the issue automatically closes.

      -

      Jamie: I love that feature. It feels like magic. Then we have GitHub Pages, which teaches you how to host a website directly from your repository for free. And finally, Release-Based Workflow, where you learn how to tag specific points in your history as official version releases, like version 1 point 0.

      -

      Alex: Moving on to Path 3, GitHub Actions and Automation. This is for the DevOps folks, or really anyone who is tired of doing repetitive tasks manually.

      -

      Jamie: Automation is the best. If I have to do something more than twice, I want a robot to do it for me.

      -

      Alex: That is the spirit of GitHub Actions. Actions are essentially a digital Rube Goldberg machine. You define a trigger, like when someone opens a pull request, and that trigger knocks over a domino that starts a sequence of automated tasks.

      -

      Jamie: The first course here is Hello GitHub Actions, which is your prerequisite for the rest of the path. It teaches you the vocabulary. What is a workflow file? What is a trigger? What are jobs and steps?

      -

      Alex: Once you have that vocabulary, the path opens up. You can take Test with Actions, which teaches Continuous Integration. That means automatically running your automated tests every time someone pushes new code, to make sure nothing broke.

      -

      Jamie: Then there is Reusable Workflows, so you do not have to copy and paste the same automation across fifty different repositories. And Write JavaScript Actions, where you actually build your own custom automation tools from scratch.

      -

      Alex: The path also covers deployment. There is Publish Docker Images, which teaches you how to build software containers and publish them. And Deploy to Azure, for pushing your web applications to the cloud.

      -

      Jamie: And they recently added AI to this path too, right?

      -

      Alex: Yes, the newest courses are AI in Actions and Create AI-Powered Actions. These teach you how to integrate artificial intelligence models directly into your automation pipelines. So your automated workflows can actually summarize pull requests, or categorize issues based on their text content, without human intervention.

      -

      Jamie: Speaking of AI, that brings us to Path 4, GitHub Copilot. This is the biggest path in the catalog, with ten different courses.

      -

      Alex: It is massive because Copilot has grown from a simple code completion tool into an entire ecosystem. Copilot is an AI assistant trained on public code. The analogy I use is that it is like pair programming with an incredibly fast typist who has memorized all the documentation on the internet, but who still needs you to be the head chef and tell them what to cook.

      -

      Jamie: You start with Getting Started with GitHub Copilot. This covers the basics of code completion, using Copilot Chat to ask questions, and getting help with debugging.

      -

      Alex: From there, you move into Build Applications with Copilot Agent Mode. Agent mode is fascinating. Instead of just suggesting one line of code at a time, you can give Copilot a complex natural language prompt, and it will plan and generate changes across multiple different files at once.

      -

      Jamie: Then there is Copilot Code Review, where the AI helps you catch quality issues before you merge. And Customize Your GitHub Copilot Experience, which teaches you how to set up custom instructions. So you can tell Copilot, hey, I use a screen reader, always ensure the HTML you generate includes proper ARIA labels.

      -

      Alex: Exactly. The path gets quite advanced from there. There is Expand Your Team with Copilot, where you learn to assign issues directly to the Copilot agent on the GitHub website, no editor required. And Integrate MCP with Copilot. MCP stands for Model Context Protocol. It is a way to give the AI secure access to external tools and data, so it can read your database schema or check your error logs.

      -

      Jamie: There is also Scale Institutional Knowledge Using Copilot Spaces, which helps share context across a whole team. And Create Applications with the Copilot CLI. CLI stands for Command Line Interface. I know the terminal can be intimidating, but Copilot can actually explain shell commands to you before you run them, which is a huge confidence booster.

      -

      Alex: The final two courses in the Copilot path are Your First Extension for GitHub Copilot, where you build custom capabilities for the AI, and Modernize Your Legacy Code. That last one is a two-hour deep dive where you use Copilot to translate an old COBOL accounting system into modern Node dot js.

      -

      Jamie: Wow. From basic chat all the way to translating COBOL. That is quite a journey.

      -

      Alex: Let us shift gears to Path 5, Security. Security is everyone's job, but it can feel overwhelming. This path breaks it down perfectly.

      -

      Jamie: It starts with the Secure Code Game, which sounds fun. It is a gamified course where you hunt for real security vulnerabilities in sample code and learn how to patch them.

      -

      Alex: Then you have Introduction to Secret Scanning. Secret scanning is like having a bouncer check your pockets before you leave the house to make sure you are not accidentally dropping your house keys on the public sidewalk. It scans your repository to ensure you have not accidentally committed passwords, API keys, or security tokens into your public code.

      -

      Jamie: And Secure Repository Supply Chain. This is all about dependencies. A dependency is external code written by someone else that your project relies on. This course teaches you how to use Dependabot to find out if those external projects have known vulnerabilities, and how to automatically update them.

      -

      Alex: Finally, we have Introduction to CodeQL and Configure CodeQL Language Matrix. CodeQL is GitHub's semantic code analysis engine. Think of it as a building inspector. It reads your code, understands the flow of data, and flags structural weaknesses, like a place where a hacker could inject malicious SQL commands into your database. These courses teach you how to enable and configure that inspector.

      -

      Jamie: Alright, the final path. Path 6, Cloud and Migration.

      -

      Alex: This path is all about moving your development environment and your existing projects into the modern cloud. It starts with Code with Codespaces.

      -

      Jamie: We talked about Codespaces in Appendix N. A Codespace is a complete developer environment hosted in the cloud. You do not have to install Node, or Python, or Docker on your local laptop. You just connect to the cloud environment through VS Code or your browser.

      -

      Alex: The analogy here is renting a fully furnished apartment instead of building a house from scratch. When you start the Code with Codespaces course, you will practice spinning up these environments, configuring them, and accessing them using your local screen reader via the command palette. Just remember to press Control plus Shift plus P to open that command palette.

      -

      Jamie: The second course is Migrate ADO Repository. ADO stands for Azure DevOps. If your company is moving from Azure DevOps to GitHub, this course gives you a safe sandbox to practice migrating the code and history using the command line.

      -

      Alex: And the final course in the entire catalog is Idea to App with Spark. GitHub Spark is an AI tool that lets you build small web applications entirely through natural language, without writing the code yourself. It is a fantastic way to rapidly prototype ideas.

      -

      Jamie: Okay, that is thirty-six courses across six paths. It is a lot to take in. How should someone actually approach this after the workshop?

      -

      Alex: My biggest piece of advice: do not try to do everything at once. Pick just one path that aligns with your immediate goals. If you want to contribute to open source, start with Path 2, Collaboration. If you want to code faster, start with Path 4, Copilot.

      -

      Jamie: And work through them one at a time. Each course only takes about thirty to sixty minutes. If you do one a week, you give yourself time to actually absorb the concepts and try them out in your real projects.

      -

      Alex: Exactly. And keep your workshop materials handy. When a GitHub Skills course asks you to create a branch or resolve a merge conflict, Mona will not give you the specific screen reader keystrokes. You will need to refer back to the chapter guides from this workshop for those specific accessibility instructions.

      -

      Jamie: So, to summarize our key takeaways. First, GitHub Skills is free, self-paced, and runs entirely in the standard GitHub interface, making it highly accessible. Second, a bot named Mona will guide you through issues and pull requests in your own private template repository.

      -

      Alex: Third, track your progress by searching your repositories for the prefix skills hyphen, and by using the checklist in Appendix Z. And fourth, always finish the introductory workshop courses before branching out into the specialized paths like Actions, Security, or Copilot.

      -

      Jamie: This has been such a great roadmap. What is coming up in our next episode, Alex?

      -

      Alex: In Episode 44, which is our final episode of the series, we are going to talk about community. We will cover how to find accessible open source projects, how to disclose your access needs to maintainers if you choose to, and how to take your very first steps into the wider GitHub community.

      -

      Jamie: I cannot wait. Thank you so much for listening, everyone. Happy learning, and we will catch you in the final episode!

      -

      Alex: Take care, and keep Git going.

      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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?

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      + +
      +

      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.

      +
      +Read Transcript - Episode 45: VS Code Accessibility Deep Dive + +

      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.

      +

      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.

      +

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

      +
      +

      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.

      +
      +

      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 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: 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 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. 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 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. 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 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: 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 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 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 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 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 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. 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 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. 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 45. Next in the series is episode 46, where we keep building the same contributor muscles.

      +
      + +
      +

      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?

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

      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: 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 46. Next in the series is episode 47, where we keep building the same contributor muscles.

      +
      + +
      +

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

      +
      +

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

      +
      +

      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: 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).

      +
      +

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

      +
      +

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

      +
      + +
      +

      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?

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      + +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      + +
      +

      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?

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      + +
      +

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

      +
      +

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

      +
      + +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      + +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      + +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

      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 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 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 [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 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: 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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      + +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      + +
      +

      Challenge 03: Join the Conversation

      +

      Comments, mentions, reactions, and constructive peer communication.

      +
      +Read Transcript - Challenge 03: Join the Conversation + +

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

      +

      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.

      +

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

      +
      +

      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.

      +

      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.

      +

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

      +

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

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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 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?

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      + +
      +

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

      +
      +

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

      +
      +

      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 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: 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 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: 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 [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. 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 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.

      +
      +

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

      +
      +

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

      +
      + +
      +

      Challenge 05: Make Your Mark

      +

      Editing a file, writing a useful commit message, and connecting a change to an issue.

      +
      +Read Transcript - Challenge 05: Make Your Mark + +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      + +
      +

      Challenge 06: Open Your First Pull Request

      +

      Opening a pull request, comparing branches, and using closing keywords.

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

      +
      +

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

      +
      + +
      +

      Challenge 07: Survive a Merge Conflict

      +

      Reading conflict markers, choosing content, deleting markers, and committing a resolution.

      +
      +Read Transcript - Challenge 07: Survive a Merge Conflict + +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      + +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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: 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.".

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      + +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +

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

      +
      + +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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.

      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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?

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

      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 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. 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 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 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: 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 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".

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      + +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      +

      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.

      +
      + +
      +

      Challenge 12: Review Like a Pro

      +

      Reviewing a classmate PR, leaving specific feedback, and owning review tone.

      +
      +Read Transcript - Challenge 12: Review Like a Pro + +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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: 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 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 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 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: 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 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 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? 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 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. 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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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 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!

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      + +
      +

      Challenge 13: AI as Your Copilot

      +

      Using Copilot as a reviewed writing partner while keeping human judgment in charge.

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      + +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      + +
      +

      Challenge 15: Meet the Agents

      +

      Exploring agent files, running agents carefully, and verifying AI output against manual skill.

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +

      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.

      +
      + +
      +

      Challenge 16: Build Your Agent (Capstone)

      +

      Designing an agent, writing responsibilities and guardrails, and preparing a contribution.

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +

      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.

      +
      + +
      +

      Challenge bonus-a: Improve an Agent

      +

      Extending or improving an existing agent with a clear accessibility purpose.

      +
      +Read Transcript - Challenge bonus-a: Improve an Agent + +

      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: 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: 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. 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: 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 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 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 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: 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 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: 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 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: 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 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?).

      +
      +

      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: 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 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: 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 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 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).

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

      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: 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. 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: 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: 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: 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. 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 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 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 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. 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 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. 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 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.".

      +
      +

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

      +
      +

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

      +
      +

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

      +
      + +
      +

      Challenge bonus-b: Document Your Journey

      +

      Reflective documentation, portfolio language, and accessible Markdown.

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

      +
      +

      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.

      +
      +

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

      +
      +

      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 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. 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 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. 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 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?".

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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?

      +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

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

      +
      + +
      +

      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.

      +
      +

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

      +
      +

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

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

      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: 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.".

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

      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.

      +
      +

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

      +
      +

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

      +

      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.

      +
      + +
      +

      Challenge bonus-d: Notifications

      +

      Notification hygiene, mentions, subscriptions, and avoiding overload.

      +
      +Read Transcript - Challenge bonus-d: Notifications + +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      + +
      +

      Challenge bonus-e: Git History

      +

      Reading history, understanding commits over time, and using history as a learning tool.

      +
      +Read Transcript - Challenge bonus-e: Git History + +

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

      +

      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?

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      +

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

      +
      + +

      Production

      -

      These episodes are generated using Google NotebookLM Audio Overviews. Each episode is produced from the workshop chapter content combined with episode-specific production prompts that ensure concept coverage, accessible language, and screen reader-friendly descriptions.

      +

      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.

      Source bundles and production documentation are in the podcasts/ directory.

      @@ -4577,5 +22622,6 @@

      Production

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/admin/PROGRESS_TRACKER.html b/html/admin/PROGRESS_TRACKER.html index 60f466d..85d687d 100644 --- a/html/admin/PROGRESS_TRACKER.html +++ b/html/admin/PROGRESS_TRACKER.html @@ -69,236 +69,256 @@

      How to Use This Tracker

    Pre-Workshop Setup

      -
    • Created GitHub account (free tier is fine)
      • -
    • Installed Git (https://git-scm.com/download/)
      • -
    • Installed/configured VS Code or preferred editor
      • -
    • Installed GitHub CLI (gh) - optional but recommended
      • -
    • Set up SSH key or HTTPS authentication
      • -
    • Verified: git --version shows v2.20+
      • -
    • Verified: gh auth status shows you're logged in
      • +
    • Created GitHub account (free tier is fine)
      • +
    • Installed Git (https://git-scm.com/download/)
      • +
    • Installed/configured VS Code or preferred editor
      • +
    • Installed GitHub CLI (gh) - optional but recommended
      • +
    • Set up SSH key or HTTPS authentication
      • +
    • Verified: git --version shows v2.20+
      • +
    • Verified: gh auth status shows you're logged in

    Status: Not started In progress Complete

    Chapter 0: Pre-Workshop Setup

    Time: 30 minutes | What You'll Do: Get your computer ready

      -
    • Read docs/00-pre-workshop-setup.md
      • -
    • Complete all prerequisite installations
      • -
    • Verify all tools work (git, VS Code, GitHub)
      • -
    • Set up SSH key (optional but recommended)
      • -
    • Test: Can you clone a repository? (git clone ...)
      • +
    • Read docs/00-pre-workshop-setup.md
      • +
    • Complete all prerequisite installations
      • +
    • Verify all tools work (git, VS Code, GitHub)
      • +
    • Set up SSH key (optional but recommended)
      • +
    • Test: Can you clone a repository? (git clone ...)

    Status: Not started In progress Complete

    Chapter 1: Understanding GitHub Web Structure

    Time: 1 hour | What You'll Do: Learn GitHub's layout and terminology

      -
    • Read docs/02-understanding-github.md
      • -
    • Understand: Repositories, Branches, Commits, PRs, Issues
      • -
    • Identify on any GitHub repo: Code tab, Issues tab, PR tab, Settings
      • -
    • Know the difference: Fork vs. Branch
      • -
    • Can explain: What is a pull request?
      • +
    • Read docs/02-understanding-github.md
      • +
    • Understand: Repositories, Branches, Commits, PRs, Issues
      • +
    • Identify on any GitHub repo: Code tab, Issues tab, PR tab, Settings
      • +
    • Know the difference: Fork vs. Branch
      • +
    • Can explain: What is a pull request?

    Status: Not started In progress Complete

    Chapter 2: Navigating Repositories

    Time: 45 minutes | What You'll Do: Practice exploring real repositories

      -
    • Read docs/03-navigating-repositories.md
      • -
    • Navigate to 3 different repos and identify key files
      • -
    • Use keyboard navigation (accessibility focus)
      • -
    • Found: README, CONTRIBUTING, License, Issues template
      • -
    • Understand the code structure and file tree
      • +
    • Read docs/03-navigating-repositories.md
      • +
    • Navigate to 3 different repos and identify key files
      • +
    • Use keyboard navigation (accessibility focus)
      • +
    • Found: README, CONTRIBUTING, License, Issues template
      • +
    • Understand the code structure and file tree

    Status: Not started In progress Complete

    Chapter 3: The Learning Room

    Time: 30 minutes | What You'll Do: Understand the shared practice environment

      -
    • Read docs/04-the-learning-room.md
      • -
    • Understand: How the Learning Room automation works
      • -
    • Know: Where to find your first contribution challenge
      • -
    • Reviewed: Available practice challenges
      • -
    • Understand: How bot feedback and peer review work
      • +
    • Read docs/04-the-learning-room.md
      • +
    • Understand: How the Learning Room automation works
      • +
    • Know: Where to find your first contribution challenge
      • +
    • Reviewed: Available practice challenges
      • +
    • Understand: How bot feedback and peer review work

    Status: Not started In progress Complete

    Chapter 4: Working with Issues

    Time: 1 hour | What You'll Do: Create, read, and comment on issues

      -
    • Read docs/05-working-with-issues.md
      • -
    • Create an issue in a practice repo
      • -
    • Comment on someone else's issue
      • -
    • Add a label and assignment to an issue
      • -
    • Know how to: Search issues, filter by label, use issue templates
      • -
    • Understand: Issue lifecycle (Open → In Progress → Done)
      • +
    • Read docs/05-working-with-issues.md
      • +
    • Create an issue in a practice repo
      • +
    • Comment on someone else's issue
      • +
    • Add a label and assignment to an issue
      • +
    • Know how to: Search issues, filter by label, use issue templates
      • +
    • Understand: Issue lifecycle (Open → In Progress → Done)

    Status: Not started In progress Complete

    Chapter 5: VS Code Accessibility

    Time: 45 minutes | What You'll Do: Set up VS Code for accessible development

      -
    • Read docs/11-vscode-interface.md
      • -
    • Installed: VS Code with accessibility settings configured
      • -
    • Enabled: Screen reader mode and keyboard navigation
      • -
    • Know how to: Use the Command Palette (Ctrl+Shift+P)
      • -
    • Configured: Accessibility signals and editor preferences for your workflow
      • +
    • Read docs/11-vscode-interface.md
      • +
    • Installed: VS Code with accessibility settings configured
      • +
    • Enabled: Screen reader mode and keyboard navigation
      • +
    • Know how to: Use the Command Palette (Ctrl+Shift+P)
      • +
    • Configured: Accessibility signals and editor preferences for your workflow

    Status: Not started In progress Complete

    Chapter 6: Working with Pull Requests

    Time: 1 hour | What You'll Do: Submit, review, and merge PRs

      -
    • Read docs/06-working-with-pull-requests.md
      • -
    • Create a pull request
      • -
    • Review a PR and add comments
      • -
    • Respond to PR feedback
      • -
    • Know how to: See diff, leave suggestions, approve
      • -
    • Understand: PR merge strategies (Merge, Squash, Rebase)
      • +
    • Read docs/06-working-with-pull-requests.md
      • +
    • Create a pull request
      • +
    • Review a PR and add comments
      • +
    • Respond to PR feedback
      • +
    • Know how to: See diff, leave suggestions, approve
      • +
    • Understand: PR merge strategies (Merge, Squash, Rebase)

    Status: Not started In progress Complete

    Chapter 7: Merge Conflicts

    Time: 1 hour | What You'll Do: Resolve conflicts between branches

      -
    • Read docs/07-merge-conflicts.md
      • -
    • Understand: Why conflicts happen
      • -
    • Know how to: Identify conflict markers (<<<< ==== >>>>)
      • -
    • Successfully resolved: 1+ real merge conflict
      • -
    • Know the "abort" option: git merge --abort
      • +
    • Read docs/07-merge-conflicts.md
      • +
    • Understand: Why conflicts happen
      • +
    • Know how to: Identify conflict markers (<<<< ==== >>>>)
      • +
    • Successfully resolved: 1+ real merge conflict
      • +
    • Know the "abort" option: git merge --abort

    Status: Not started In progress Complete

    Chapter 8: Culture & Etiquette

    Time: 30 minutes | What You'll Do: Learn collaborative best practices

      -
    • Read docs/08-open-source-culture.md
      • -
    • Understand: Respectful code review
      • -
    • Know the difference: Suggestion vs. Requirement
      • -
    • Can give constructive feedback on code
      • -
    • Understand: Inclusive language in issues/PRs
      • +
    • Read docs/08-open-source-culture.md
      • +
    • Understand: Respectful code review
      • +
    • Know the difference: Suggestion vs. Requirement
      • +
    • Can give constructive feedback on code
      • +
    • Understand: Inclusive language in issues/PRs

    Status: Not started In progress Complete

    Chapter 9: Labels, Milestones & Projects

    Time: 45 minutes | What You'll Do: Use GitHub's organizational tools

      -
    • Read docs/09-labels-milestones-projects.md
      • -
    • Created: 3+ labels for a repo or issue
      • -
    • Created: 1+ milestone (release or sprint)
      • -
    • Used project board to organize work (optional: add columns and cards)
      • -
    • Filtered issues using: Labels + Milestones
      • +
    • Read docs/09-labels-milestones-projects.md
      • +
    • Created: 3+ labels for a repo or issue
      • +
    • Created: 1+ milestone (release or sprint)
      • +
    • Used project board to organize work (optional: add columns and cards)
      • +
    • Filtered issues using: Labels + Milestones

    Status: Not started In progress Complete

    Chapter 10: Notifications

    Time: 30 minutes | What You'll Do: Master GitHub notifications

      -
    • Read docs/10-notifications-and-day-1-close.md
      • -
    • Set up notifications: Email or in-app
      • -
    • Understand: @mentions, subscriptions, digest settings
      • -
    • Configured: Notifications for your projects
      • -
    • Know how to: Unsubscribe from threads you don't need
      • +
    • Read docs/10-notifications-and-day-1-close.md
      • +
    • Set up notifications: Email or in-app
      • +
    • Understand: @mentions, subscriptions, digest settings
      • +
    • Configured: Notifications for your projects
      • +
    • Know how to: Unsubscribe from threads you don't need

    Status: Not started In progress Complete

    -

    Chapter 11: Git & Source Control in VS Code

    -

    Time: 1 hour | What You'll Do: Master Git operations within VS Code

    +

    Chapter 11: VS Code Interface and Setup

    +

    Time: 45 minutes | What You'll Do: Launch VS Code, sign in, enable screen reader mode, and orient to core surfaces

      -
    • Read docs/14-git-in-practice.md
      • -
    • Know how to: Clone, branch, commit, push from VS Code
      • -
    • Used: Source Control panel (Ctrl+Shift+G)
      • -
    • Understand: Staging, committing, and syncing changes
      • -
    • Configured: Git credentials and remote tracking
      • +
    • Read docs/11-vscode-interface.md
      • +
    • Know how to: Open github.dev or desktop VS Code from a repository
      • +
    • Used: Explorer, Command Palette, Outline, and Status Bar
      • +
    • Verified: GitHub sign-in and Copilot status
      • +
    • Configured: Screen reader mode and basic navigation preferences

    Status: Not started In progress Complete

    -

    Chapter 12: GitHub Pull Requests Extension

    -

    Time: 45 minutes | What You'll Do: Review and create PRs from VS Code

    +

    Chapter 12: VS Code Accessibility Deep Dive

    +

    Time: 45 minutes | What You'll Do: Configure VS Code accessibility features for daily contribution work

      -
    • Read docs/15-code-review.md
      • -
    • Installed: GitHub Pull Requests and Issues extension
      • -
    • Know how to: View, review, and create PRs in VS Code
      • -
    • Understand: Inline code review workflow
      • -
    • Practice: Commented on a PR from within VS Code
      • +
    • Read docs/12-vscode-accessibility.md
      • +
    • Know how to: Use Accessible View, Accessible Help, and Accessible Diff Viewer
      • +
    • Configured: Audio cues or accessibility signals as needed
      • +
    • Understand: Problems panel, Terminal, and Markdown authoring accessibility
      • +
    • Practice: Navigated a diff or diagnostic output with the keyboard

    Status: Not started In progress Complete

    -

    Chapter 13: GitHub Copilot

    -

    Time: 1 hour | What You'll Do: Use AI-assisted coding and chat

    +

    Chapter 13: How Git Works

    +

    Time: 30 minutes | What You'll Do: Build the mental model for commits, branches, remotes, and conflicts

    +
      +
    • Read docs/13-how-git-works.md
      • +
    • Understand: Working tree, staging area, local repository, and remote repository
      • +
    • Know how to: Explain branch, commit, push, pull, fetch, and merge
      • +
    • Understand: Why merge conflicts happen
      • +
    +

    Status: Not started In progress Complete

    +

    Chapter 14: Git in Practice

    +

    Time: 1 hour | What You'll Do: Master Git operations within VS Code

      -
    • Read docs/16-github-copilot.md
      • -
    • Installed: GitHub Copilot and Copilot Chat extensions
      • -
    • Verified: Copilot Chat works (Ctrl+Shift+I)
      • -
    • Know how to: Use inline suggestions, chat, and custom instructions
      • -
    • Understand: Chat participants, agents, and model selection
      • +
    • Read docs/14-git-in-practice.md
      • +
    • Know how to: Clone, branch, commit, push from VS Code
      • +
    • Used: Source Control panel (Ctrl+Shift+G)
      • +
    • Understand: Staging, committing, and syncing changes
      • +
    • Configured: Git credentials and remote tracking

    Status: Not started In progress Complete

    -

    Chapter 14: Accessible Code Review

    -

    Time: 1.5 hours + Exercises | What You'll Do: Review code accessibly

    +

    Chapter 15: Code Review

    +

    Time: 1.5 hours + Exercises | What You'll Do: Review pull requests accessibly and constructively

    Reading & Concepts

      -
    • Read docs/15-code-review.md
      • -
    • Understand: Accessible code review principles
      • -
    • Know the difference: Manual review vs. Copilot review
      • -
    • Familiar with: VS Code Accessible Diff Viewer (F7)
      • +
    • Read docs/15-code-review.md
      • +
    • Installed: GitHub Pull Requests and Issues extension
      • +
    • Know how to: View, review, and create PRs in VS Code
      • +
    • Understand: Accessible code review principles
      • +
    • Familiar with: VS Code Accessible Diff Viewer (F7)

    Exercises

      -
    • Exercise A: Review issue accessibility using web reader
      • -
    • Exercise B: Use VS Code Accessible Diff Viewer
      • -
    • Exercise C: Comment on PR accessibility
      • +
    • Exercise A: Review issue accessibility using web reader
      • +
    • Exercise B: Use VS Code Accessible Diff Viewer
      • +
    • Exercise C: Comment on PR accessibility

    Status: Not started In progress Complete
    Exercises Completed: A B C All

    -

    Chapter 15: Issue Templates

    +

    Chapter 16: GitHub Copilot

    +

    Time: 1 hour | What You'll Do: Use AI-assisted coding and chat

    +
      +
    • Read docs/16-github-copilot.md
      • +
    • Installed: GitHub Copilot and Copilot Chat extensions
      • +
    • Verified: Copilot Chat works (Ctrl+Shift+I)
      • +
    • Know how to: Use inline suggestions, chat, and custom instructions
      • +
    • Understand: Chat participants, agents, and model selection
      • +
    +

    Status: Not started In progress Complete

    +

    Chapter 17: Issue Templates

    Time: 1.5 hours + Exercises | What You'll Do: Create accessible issue templates

    Reading & Concepts

      -
    • Read docs/17-issue-templates.md
      • -
    • Understand: YAML syntax for templates
      • -
    • Know how to: Create and test custom templates
      • -
    • Understand: Form accessibility in templates
      • +
    • Read docs/17-issue-templates.md
      • +
    • Understand: YAML syntax for templates
      • +
    • Know how to: Create and test custom templates
      • +
    • Understand: Form accessibility in templates

    Exercises

      -
    • Exercise A: Create template using GitHub web UI
      • -
    • Exercise B: Create template locally in VS Code
      • -
    • Exercise C: Create PR for accessibility template
      • -
    • Exercise D: Design custom template for your project
      • +
    • Exercise A: Create template using GitHub web UI
      • +
    • Exercise B: Create template locally in VS Code
      • +
    • Exercise C: Create PR for accessibility template
      • +
    • Exercise D: Design custom template for your project

    Status: Not started In progress Complete
    Exercises Completed: A B C D All

    -

    Chapter 16: Accessibility Agents

    +

    Chapter 19: Accessibility Agents

    Time: 1.5 hours + Exercises | What You'll Do: Automate with Copilot agents

    Agents to Explore

    -

    Browse the ecosystem and try agents that match your skills (read Chapter 16 for the full landscape):

    +

    Browse the ecosystem and try agents that match your skills (read Chapter 19 for the full landscape):

      -
    • GitHub Workflow agents - @daily-briefing, @issue-tracker, @pr-review, @analytics, @insiders-a11y-tracker, @template-builder
      • -
    • Accessibility agents - @web-accessibility-wizard, @contrast-master, @keyboard-navigator, @markdown-a11y-assistant
      • -
    • Developer Tools agents - @python-specialist, @desktop-a11y-specialist, @a11y-tool-builder
      • +
    • GitHub Workflow agents - @daily-briefing, @issue-tracker, @pr-review, @analytics, @insiders-a11y-tracker, @template-builder
      • +
    • Accessibility agents - @web-accessibility-wizard, @contrast-master, @keyboard-navigator, @markdown-a11y-assistant
      • +
    • Developer Tools agents - @python-specialist, @desktop-a11y-specialist, @a11y-tool-builder

    Exercises

      -
    • Exercise 1: Generate a template with @template-builder
        -
      • Follow all 8 steps
        • -
      • Ask Questions workflow guided tour
        • -
      • Save generated template
        • -
      • Test locally or on GitHub
        • +
      • Exercise 1: Generate a template with @template-builder
          +
        • Follow all 8 steps
          • +
        • Ask Questions workflow guided tour
          • +
        • Save generated template
          • +
        • Test locally or on GitHub
        • -
      • Exercise 2: Extend the @template-builder agent
          -
        • Follow all 6 steps
          • -
        • Edit .github/agents/template-builder.agent.md
          • -
        • Add new Pre-Built Workflow
          • -
        • Test agent with new workflow
          • +
        • Exercise 2: Extend the @template-builder agent
            +
          • Follow all 6 steps
            • +
          • Edit .github/agents/template-builder.agent.md
            • +
          • Add new Pre-Built Workflow
            • +
          • Test agent with new workflow
          • -
        • Exercise 3: Iterative refinement with agents
            -
          • Follow all 4 steps
            • -
          • Ask agent to modify/extend template
            • -
          • Observe pattern of interaction
            • -
          • Reflection: How does iteration work with agents?
            • +
          • Exercise 3: Iterative refinement with agents
              +
            • Follow all 4 steps
              • +
            • Ask agent to modify/extend template
              • +
            • Observe pattern of interaction
              • +
            • Reflection: How does iteration work with agents?

          Status: Not started In progress Complete
          Exercises Completed: 1 2 3 All

          Appendices (Reference)

            -
          • Appendix A: Glossary - Read as needed for term definitions
              -
            • Saved link or printed for reference
              • +
            • Appendix A: Glossary - Read as needed for term definitions
                +
              • Saved link or printed for reference
              • -
            • Appendix B: Screen Reader Cheatsheet - Bookmark this!
              • -
            • Appendix Y: Accessing Workshop Materials - How to download, read offline, and keep updated
              • -
            • Appendix Z: GitHub Skills Catalog - All 36 modules organized into six learning paths
                -
              • NVDA commands bookmarked
                • -
              • JAWS commands bookmarked
                • -
              • VoiceOver commands bookmarked
                • +
              • Appendix B: Screen Reader Cheatsheet - Bookmark this!
                • +
              • Appendix Y: Accessing Workshop Materials - How to download, read offline, and keep updated
                • +
              • Appendix Z: GitHub Skills Catalog - All 36 modules organized into six learning paths
                  +
                • NVDA commands bookmarked
                  • +
                • JAWS commands bookmarked
                  • +
                • VoiceOver commands bookmarked
              @@ -536,23 +556,23 @@

              If You're a Facili

              Next Steps After Completing This Curriculum

              Keep Learning

                -
              • Work on real open-source projects
                • -
              • Practice code review on real PRs
                • -
              • Create templates for your own repositories
                • -
              • Experiment with agents on your own code
                • +
              • Work on real open-source projects
                • +
              • Practice code review on real PRs
                • +
              • Create templates for your own repositories
                • +
              • Experiment with agents on your own code

              Share Your Knowledge

                -
              • Lead a workshop for your team
                • -
              • Contribute improvements to this guide
                • -
              • Help others in GitHub discussions/issues
                • +
              • Lead a workshop for your team
                • +
              • Contribute improvements to this guide
                • +
              • Help others in GitHub discussions/issues

              Advanced Topics (Not in This Guide)

                -
              • GitHub Advanced Security features
                • -
              • Custom GitHub Actions
                • -
              • Codespaces for efficient development
                • -
              • GitHub Enterprise features
                • +
              • GitHub Advanced Security features
                • +
              • Custom GitHub Actions
                • +
              • Codespaces for efficient development
                • +
              • GitHub Enterprise features

              Questions or Stuck?

                @@ -569,5 +589,6 @@

                Questions or Stuck?

                GIT Going with GitHub - A workshop by Community Access

                View on GitHub · community-access.org

                + - \ No newline at end of file + diff --git a/html/admin/QUICK_REFERENCE.html b/html/admin/QUICK_REFERENCE.html index bf8b6fa..8401e68 100644 --- a/html/admin/QUICK_REFERENCE.html +++ b/html/admin/QUICK_REFERENCE.html @@ -405,13 +405,13 @@

                YAML Template Structure (Quick T required: true

                Accessibility Testing Checklist (Quick)

                  -
                • All form labels announced by screen reader
                  • -
                • Required fields marked and announced as required
                  • -
                • Dropdown options readable and selectable
                  • -
                • No labels skipped (heading hierarchy: 1→2→3, not 1→3)
                  • -
                • Link text is descriptive (not "click here")
                  • -
                • Color not the only way to convey information
                  • -
                • Tested on: NVDA JAWS VoiceOver
                  • +
                • All form labels announced by screen reader
                  • +
                • Required fields marked and announced as required
                  • +
                • Dropdown options readable and selectable
                  • +
                • No labels skipped (heading hierarchy: 1→2→3, not 1→3)
                  • +
                • Link text is descriptive (not "click here")
                  • +
                • Color not the only way to convey information
                  • +
                • Tested on: NVDA JAWS VoiceOver

                Common YAML Errors & Fixes

                @@ -482,5 +482,6 @@

                Accessibility Hotkeys Summary

                GIT Going with GitHub - A workshop by Community Access

                View on GitHub · community-access.org

                + - \ No newline at end of file + diff --git a/html/admin/REGISTER.html b/html/admin/REGISTER.html index 8b6b2c3..4e1dee2 100644 --- a/html/admin/REGISTER.html +++ b/html/admin/REGISTER.html @@ -4,7 +4,7 @@ - Registration Closed - GIT Going with GitHub + Student Opt-In - GIT Going with GitHub @@ -28,7 +28,7 @@
                -

                Registration Closed

                +

                Student Opt-In

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

                -

                Registration for GIT Going with GitHub is now closed.

                -

                Thank you to everyone who registered! We are excited to learn together.

                +

                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.

                @@ -70,65 +70,65 @@

                Registration for G

                - - + + - - - - - - + + - - + +
                DatesMay 21, 2026 and May 22, 2026StatusOpen for student opt-in
                Time12:00 PM - 8:00 PM Eastern (both days)
                LocationOnline via ZoomCurrent confirmed registrationsLoading...
                Cost Free
                FacilitatorsJeff Bishop and Michael BabcockFormatCurrent workshop is in person; future cohorts may include remote participation
                -

                Already registered? Complete the Pre-Workshop Setup Guide before the workshop. It walks you through GitHub account setup, screen reader configuration, VS Code, and GitHub Copilot - with instructions for NVDA, JAWS, and VoiceOver.

                -

                Questions?

                -

                Need help? File an issue in the workshop repository or join the Discussion Forum.

                -

                A Community Access initiative.

                -

                Important: You must be signed into your GitHub account before clicking the link below. If you are not signed in, go to GitHub and sign in first.

                +

                Quick opt-in workflow

                +
                  +
                1. Sign in to your GitHub account.
                  2. +
                2. Open the registration issue form:
                  3. +
                -

                Start Step 2 - File your registration issue

                +

                Start Student Opt-In Form

                -

                Note: The issue title is pre-filled and required by GitHub. You do not need to change it - just fill out the form fields below it and submit.

                -

                The form asks for:

                +
                  +
                1. Submit the form with your details.
                  2. +
                +

                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

                  -
                • First Name (required) - your first name as you would like to be addressed during the workshop
                  • -
                • Last Name (required)
                  • -
                • Email Address (required) - we will use this to send you Zoom links and workshop materials before the event
                  • -
                • GitHub Proficiency Level (required) - a dropdown from "Brand new" to "Experienced" so we can prepare the right level of support
                  • -
                • Primary Screen Reader (optional) - which screen reader you primarily use (NVDA, JAWS, VoiceOver, or other)
                  • -
                • Questions or Accommodations (optional) - anything we should know or arrange before the workshop
                  • +
                • 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 submit, you will receive an automated confirmation comment on your issue. Your GitHub username is captured automatically - you do not need to enter it.

                -

                What Happens Next

                -

                Once you have completed both steps:

                +

                After you opt in

                  -
                1. You will receive a Zoom confirmation email (Step 1)
                  2. -
                2. You will see a confirmation comment on your GitHub issue (Step 2)
                  3. -
                3. Complete the Pre-Workshop Setup Guide before the workshop - it covers GitHub account setup, screen reader configuration, VS Code, and GitHub Copilot
                  4. -
                4. Questions? File an issue in the workshop repository
                  5. +
                5. Check your issue for the automated confirmation or waitlist comment.
                  6. +
                6. Complete the Pre-Workshop Setup Guide.
                  7. +
                7. Introduce yourself in the Discussion Forum.
                -

                While You Wait

                +

                Need help?

                +

                Questions or access issues are welcome.

                +

                A Community Access initiative.

                + - \ No newline at end of file + diff --git a/html/admin/REGISTRATION-ADMIN.html b/html/admin/REGISTRATION-ADMIN.html index c2d0a46..d2369ff 100644 --- a/html/admin/REGISTRATION-ADMIN.html +++ b/html/admin/REGISTRATION-ADMIN.html @@ -59,12 +59,80 @@

                Registration Administration Guide

                -

                This document explains how the registration system works and how to manage it. This file is not committed to the repository.

                +

                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.

                @@ -93,6 +161,8 @@

                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

                @@ -139,6 +209,7 @@

                Privacy Notes

              • 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
              @@ -146,5 +217,6 @@

              Privacy Notes

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/admin/REGISTRATION-QUICKSTART.html b/html/admin/REGISTRATION-QUICKSTART.html new file mode 100644 index 0000000..f81d5b6 --- /dev/null +++ b/html/admin/REGISTRATION-QUICKSTART.html @@ -0,0 +1,165 @@ + + + + + + + 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.

              +

              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/STUDENT_MANAGEMENT.html b/html/admin/STUDENT_MANAGEMENT.html index 487102f..7f3fbf8 100644 --- a/html/admin/STUDENT_MANAGEMENT.html +++ b/html/admin/STUDENT_MANAGEMENT.html @@ -130,5 +130,6 @@

              Student needs to restart

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/admin/STUDENT_ONBOARDING_EMAIL.html b/html/admin/STUDENT_ONBOARDING_EMAIL.html index 49175a7..84236c6 100644 --- a/html/admin/STUDENT_ONBOARDING_EMAIL.html +++ b/html/admin/STUDENT_ONBOARDING_EMAIL.html @@ -82,5 +82,6 @@

              Student Onboarding Email

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/admin/TROUBLESHOOTING.html b/html/admin/TROUBLESHOOTING.html index 5b1701c..7020e4d 100644 --- a/html/admin/TROUBLESHOOTING.html +++ b/html/admin/TROUBLESHOOTING.html @@ -1035,5 +1035,6 @@

              Getting More Help

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/admin/VALIDATION_AUDIT.html b/html/admin/VALIDATION_AUDIT.html index c43aff4..b681d90 100644 --- a/html/admin/VALIDATION_AUDIT.html +++ b/html/admin/VALIDATION_AUDIT.html @@ -64,6 +64,9 @@

              Compreh original curriculum content. Challenge templates and documentation have been updated since this audit. Use this as a reference for the types of issues to look for, not as a current status report.

              +

              Current status: Historical reference only. The May 2026 curriculum uses the +Challenge Hub, classroom assignments, and Learning Room templates as the +current source of truth.

              Date: March 5, 2026 Scope: Chapters 4-16 challenge definitions, documentation, templates, and associated files @@ -825,7 +828,7 @@

              Recommendations

              Authentication setup and discovering the PR list in VS Code are learning experiences.

              • -

              Chapter 13: GitHub Copilot

              +

              Original Chapter 13: GitHub Copilot

              [WARN] — Subscription prerequisite not clearly flagged; sci-fi theme is engaging but adds scope.

              Prerequisites Check

              ISSUE FOUND - Subscription requirement buried:

              @@ -1498,48 +1501,48 @@

              Before Students Begin (o

              Files Requiring Updates

              CHALLENGES.md (learning-room/docs/)

                -
              • Chapter 8: Add evaluation criteria and time estimate
                • -
              • Chapter 9: Add time estimate
                • -
              • Chapter 10: Add completion evidence requirement
                • -
              • Chapter 5: Clarify Mac/VoiceOver; add realistic time range
                • -
              • Chapter 11: Emphasize prerequisites in hub summary
                • -
              • Chapter 12: Add write-access assumption note
                • -
              • Chapter 13: ADD SUBSCRIPTION WARNING (URGENT)
                • -
              • Chapter 15: Consolidate and expand prerequisites (URGENT)
                • -
              • Chapter 16: Add discovery framework and scope reduction (URGENT)
                • +
              • Chapter 8: Add evaluation criteria and time estimate
                • +
              • Chapter 9: Add time estimate
                • +
              • Chapter 10: Add completion evidence requirement
                • +
              • Chapter 5: Clarify Mac/VoiceOver; add realistic time range
                • +
              • Chapter 11: Emphasize prerequisites in hub summary
                • +
              • Chapter 12: Add write-access assumption note
                • +
              • Chapter 13: ADD SUBSCRIPTION WARNING (URGENT)
                • +
              • Chapter 15: Consolidate and expand prerequisites (URGENT)
                • +
              • Chapter 16: Add discovery framework and scope reduction (URGENT)

              Chapter-specific docs (docs/NN-*.md)

                -
              • 11-vscode-interface.md: Clarify Mac/VoiceOver; github.dev vs desktop distinction
                • -
              • 16-github-copilot.md: Add JSON editing guidance and real-world time expectations
                • -
              • 17-issue-templates.md: Add YAML validation section; show before/after remix example
                • -
              • 19-accessibility-agents.md: Add local exploration alternative; agent discovery framework
                • +
              • 11-vscode-interface.md: Clarify Mac/VoiceOver; github.dev vs desktop distinction
                • +
              • 16-github-copilot.md: Add JSON editing guidance and real-world time expectations
                • +
              • 17-issue-templates.md: Add YAML validation section; show before/after remix example
                • +
              • 19-accessibility-agents.md: Add local exploration alternative; agent discovery framework

              Issue Template

                -
              • .github/ISSUE_TEMPLATE/challenge-hub.md: May need template variables for Chapter 13 subscription callout
                • +
              • .github/ISSUE_TEMPLATE/challenge-hub.md: May need template variables for Chapter 13 subscription callout

              Testing &Validation Checklist

              Before deploying challenges to students:

              Screen Reader Testing (NVDA, JAWS, VoiceOver)

                -
              • Ch 10: Notification inbox navigation and shortcuts
                • -
              • Ch 5: VS Code screen reader mode (Windows + Mac) and feature discovery
                • -
              • Ch 12: GitHub PR Extension UI accessibility
                • -
              • Ch 13: Copilot Chat response reading with Accessible View
                • +
              • Ch 10: Notification inbox navigation and shortcuts
                • +
              • Ch 5: VS Code screen reader mode (Windows + Mac) and feature discovery
                • +
              • Ch 12: GitHub PR Extension UI accessibility
                • +
              • Ch 13: Copilot Chat response reading with Accessible View

              Hands-on Flow Testing (Windows + Mac)

                -
              • Ch 4: Issue creation and claim workflow (end-to-end)
                • -
              • Ch 6: PR opening with Closes #XX template
                • -
              • Ch 7: Conflict marker resolution workflow
                • -
              • Ch 11: git clone → commit → push (on both platforms)
                • -
              • Ch 13: Copilot Chat without subscription (confirm error message is clear)
                • +
              • Ch 4: Issue creation and claim workflow (end-to-end)
                • +
              • Ch 6: PR opening with Closes #XX template
                • +
              • Ch 7: Conflict marker resolution workflow
                • +
              • Ch 11: git clone → commit → push (on both platforms)
                • +
              • Ch 13: Copilot Chat without subscription (confirm error message is clear)

              Prerequisite Verification

                -
              • Students can complete Chapter N without having completed Chapter N-1 (if claimed as standalone)
                • -
              • Time estimates hold true for 3-5 real students of varying backgrounds
                • +
              • Students can complete Chapter N without having completed Chapter N-1 (if claimed as standalone)
                • +
              • Time estimates hold true for 3-5 real students of varying backgrounds

              Conclusion

              The challenges are well-intentioned and generally well-designed, with strong pedagogical progression and accessibility-focused documentation. However, four chapters (10, 12, 13, 15, 16) require significant revisions before student deployment to avoid frustration and blockers.

              @@ -1553,5 +1556,6 @@

              Conclusion

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/admin/classroom admin access.html b/html/admin/classroom admin access.html new file mode 100644 index 0000000..0de820a --- /dev/null +++ b/html/admin/classroom admin access.html @@ -0,0 +1,70 @@ + + + + + + + classroom admin access - GIT Going with GitHub + + + + + + + + +
              +

              https://classroom.github.com/classrooms/263509777-git-going-with-github

              + +
              + + + + diff --git a/html/admin/classroom/autograding-setup.html b/html/admin/classroom/autograding-setup.html new file mode 100644 index 0000000..5a228f3 --- /dev/null +++ b/html/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/classroom/day1-assignment-copy-paste.html b/html/admin/classroom/day1-assignment-copy-paste.html new file mode 100644 index 0000000..b3cf606 --- /dev/null +++ b/html/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/classroom/day2-assignment-copy-paste.html b/html/admin/classroom/day2-assignment-copy-paste.html new file mode 100644 index 0000000..410ac3e --- /dev/null +++ b/html/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/classroom/index.html b/html/admin/classroom/index.html new file mode 100644 index 0000000..50f4841 --- /dev/null +++ b/html/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/classroom/live-facilitation-flow.html b/html/admin/classroom/live-facilitation-flow.html new file mode 100644 index 0000000..3758d01 --- /dev/null +++ b/html/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/classroom/seeding-ops.html b/html/admin/classroom/seeding-ops.html new file mode 100644 index 0000000..59045ca --- /dev/null +++ b/html/admin/classroom/seeding-ops.html @@ -0,0 +1,107 @@ + + + + + + + Seeding Operations Cheat Sheet - GIT Going with GitHub + + + + + + + + +
              +

              Seeding Operations Cheat Sheet

              +

              Run these commands after a student accepts an assignment so challenge flow starts correctly.

              +

              Prerequisites

              +
                +
              • GitHub CLI (gh) is installed and authenticated
                • +
              • You have access to the student repository
                • +
              • Repository naming follows classroom output, for example:
                  +
                • Community-Access-Classroom/learning-room-studentname
                  • +
                +
                • +
              +

              Seed Day 1 First Challenge

              +
              scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-studentname -Challenge 1 -Assignee studentname
              +

              Seed Day 2 First Challenge

              +
              scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-studentname -Challenge 10 -Assignee studentname
              +

              Seed Peer Simulation Artifacts

              +
              scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom/learning-room-studentname -StudentUsername studentname
              +

              Verify Seeding Worked

              +
                +
              1. Open repository Actions and confirm student-progression.yml run started.
                2. +
              2. Confirm issue list contains the expected challenge issue.
                3. +
              3. If peer simulation was seeded, confirm two issues and one PR were created.
                4. +
              +

              Optional CLI check:

              +
              gh issue list -R Community-Access-Classroom/learning-room-studentname --state all
              +

              Common Failure Cases

              +

              Workflow run command fails

              +
                +
              • Confirm repo name is correct.
                • +
              • Confirm facilitator has write access.
                • +
              • Confirm student-progression.yml exists in the target repository.
                • +
              +

              Challenge issue not created

              +
                +
              • Check workflow logs in Actions.
                • +
              • Re-run the same seeding command.
                • +
              • If still blocked, create challenge issue manually from the matching template.
                • +
              + +
              + + + + diff --git a/html/admin/index.html b/html/admin/index.html new file mode 100644 index 0000000..46a50f7 --- /dev/null +++ b/html/admin/index.html @@ -0,0 +1,307 @@ + + + + + + + Admin & Facilitator Resources - GIT Going with GitHub + + + + + + + + +
              +

              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

              + +

              Supporting Guides

              + +
              +

              Student And Enrollment Management

              + +
              +

              Workshop Planning And Organization

              + +
              +

              Setup And Deployment

              + +
              +

              Communications

              + +
              +

              Reference And Support

              + +
              +

              Typical Workflow

              +

              Planning Phase (Weeks 1-2 Before)

              +
                +
              1. COHORT_PROVISIONING.md - Set up the cohort
                2. +
              2. FACILITATOR_GUIDE.md - GitHub Classroom setup
                3. +
              3. ANNOUNCEMENT.md - Create student announcements
                4. +
              4. STUDENT_MANAGEMENT.md - Prepare roster
                5. +
              +

              Pre-Workshop (48 Hours Before)

              +
                +
              1. FACILITATOR_GUIDE.md - Complete checklist
                2. +
              2. ACCESSIBILITY_TESTING.md - Test with screen readers
                3. +
              3. FACILITATOR_OPERATIONS.md - Setup workstation
                4. +
              +

              During Workshop

              +
                +
              1. FACILITATOR_OPERATIONS.md - Follow hour-by-hour procedures
                2. +
              2. FACILITATOR_CLASSROOM_TROUBLESHOOTING.md - Reference when needed
                3. +
              3. PROGRESS_TRACKER.md - Track student progress
                4. +
              +

              Post-Workshop

              +
                +
              1. FACILITATOR_GUIDE.md - Follow-up tasks
                2. +
              2. Update this documentation with lessons learned
                3. +
              +
              +

              Reading Order Recommendations

              +

              For First-Time Facilitators

              +
                +
              1. Start: FACILITATOR_RESOURCES.md
                2. +
              2. Then: FACILITATOR_GUIDE.md (full read)
                3. +
              3. Then: FACILITATOR_OPERATIONS.md (full read)
                4. +
              4. Reference: FACILITATOR_CLASSROOM_TROUBLESHOOTING.md
                5. +
              +

              For Returning Facilitators

              +
                +
              1. Quick reference: QUICK_REFERENCE.md
                2. +
              2. Review: FACILITATOR_GUIDE.md checklist
                3. +
              3. Keep open: FACILITATOR_OPERATIONS.md during workshop
                4. +
              +

              For Admin/Coordinators

              +
                +
              1. COHORT_PROVISIONING.md - Setup cohorts
                2. +
              2. STUDENT_MANAGEMENT.md - Manage rosters
                3. +
              3. PROGRESS_TRACKER.md - Monitor progress
                4. +
              4. ACCESSIBILITY_TESTING.md - Ensure quality
                5. +
              +
              +

              Key Resources By Topic

              +

              GitHub Classroom

              + +

              Accessibility

              + +

              Student Communication

              + +

              Troubleshooting

              + +

              Assessment

              + +
              +

              Document Index

              + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
              DocumentPurposeFor Whom
              FACILITATOR_RESOURCES.mdNavigation hubFacilitators (start here!)
              FACILITATOR_GUIDE.mdComplete workshop guideNew facilitators
              FACILITATOR_OPERATIONS.mdHour-by-hour proceduresActive facilitators
              FACILITATOR_CLASSROOM_TROUBLESHOOTING.mdProblem-solvingAll facilitators
              FACILITATOR_CHALLENGES.mdChallenge managementExperienced facilitators
              FACILITATOR_ASSESSMENT.mdGrading rubricFacilitators doing assessment
              COHORT_PROVISIONING.mdSetup checklistAdmin/coordinators
              STUDENT_MANAGEMENT.mdRoster managementAdmin/coordinators
              PROGRESS_TRACKER.mdStudent trackingFacilitators, coordinators
              ACCESSIBILITY_TESTING.mdA11y testingQA/admin
              DAY1_AGENDA.mdDay 1 scheduleEveryone
              DAY2_AGENDA.mdDay 2 scheduleEveryone
              QUICK_REFERENCE.mdQuick reference cardFacilitators (print this)
              FAQ.mdFrequently asked questionsStudents (and facilitators)
              ANNOUNCEMENT.mdAnnouncement templatesAdmin
              TROUBLESHOOTING.mdGeneral troubleshootingEveryone
              +
              + +
                +
              • ../classroom/ - GitHub Classroom deployment and configuration
                • +
              • ../docs/ - Student-facing guides and learning materials
                • +
              • ../scripts/ - Automation and utility scripts
                • +
              +
              +

              Questions Or Feedback?

              +

              Found something unclear or outdated? Update this documentation to help the next facilitator. Your experience makes this better for everyone.

              +
              +

              Last Updated: May 2026 | Maintained by: Jeff Bishop | Version: 2.0

              + +
              + + + + diff --git a/html/agents/image alt text agent/IMAGE-ALT-TEXT-DOCS.html b/html/agents/image alt text agent/IMAGE-ALT-TEXT-DOCS.html index f18242e..c57c01c 100644 --- a/html/agents/image alt text agent/IMAGE-ALT-TEXT-DOCS.html +++ b/html/agents/image alt text agent/IMAGE-ALT-TEXT-DOCS.html @@ -1484,5 +1484,6 @@

              Combined Workflows

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/agents/image alt text agent/agents/image-alt-text.agent.html b/html/agents/image alt text agent/agents/image-alt-text.agent.html index 2aabd9e..894f832 100644 --- a/html/agents/image alt text agent/agents/image-alt-text.agent.html +++ b/html/agents/image alt text agent/agents/image-alt-text.agent.html @@ -241,5 +241,6 @@

              Error Handling

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/agents/image alt text agent/agents/image-analyzer.agent.html b/html/agents/image alt text agent/agents/image-analyzer.agent.html index e47231a..80cfb28 100644 --- a/html/agents/image alt text agent/agents/image-analyzer.agent.html +++ b/html/agents/image alt text agent/agents/image-analyzer.agent.html @@ -285,5 +285,6 @@

              Examples

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/agents/image alt text agent/agents/image-cataloger.agent.html b/html/agents/image alt text agent/agents/image-cataloger.agent.html index aa4f3a6..43307ed 100644 --- a/html/agents/image alt text agent/agents/image-cataloger.agent.html +++ b/html/agents/image alt text agent/agents/image-cataloger.agent.html @@ -257,5 +257,6 @@

              Output Format

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/agents/image alt text agent/agents/tag-builder.agent.html b/html/agents/image alt text agent/agents/tag-builder.agent.html index 86c26db..a83cde7 100644 --- a/html/agents/image alt text agent/agents/tag-builder.agent.html +++ b/html/agents/image alt text agent/agents/tag-builder.agent.html @@ -182,5 +182,6 @@

              Output Format

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/agents/image alt text agent/instructions/image-dimensions.instructions.html b/html/agents/image alt text agent/instructions/image-dimensions.instructions.html index 51414ea..c7f1c01 100644 --- a/html/agents/image alt text agent/instructions/image-dimensions.instructions.html +++ b/html/agents/image alt text agent/instructions/image-dimensions.instructions.html @@ -113,5 +113,6 @@

              Dimension extraction

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/agents/image alt text agent/prompts/image-analyzer.prompt.html b/html/agents/image alt text agent/prompts/image-analyzer.prompt.html index 625d02e..e7affdc 100644 --- a/html/agents/image alt text agent/prompts/image-analyzer.prompt.html +++ b/html/agents/image alt text agent/prompts/image-analyzer.prompt.html @@ -71,5 +71,6 @@

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/agents/image alt text agent/prompts/image-cataloger.prompt.html b/html/agents/image alt text agent/prompts/image-cataloger.prompt.html index 1d0d866..768b8a3 100644 --- a/html/agents/image alt text agent/prompts/image-cataloger.prompt.html +++ b/html/agents/image alt text agent/prompts/image-cataloger.prompt.html @@ -71,5 +71,6 @@

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/agents/image alt text agent/prompts/tag-builder.prompt.html b/html/agents/image alt text agent/prompts/tag-builder.prompt.html index c554545..cf58310 100644 --- a/html/agents/image alt text agent/prompts/tag-builder.prompt.html +++ b/html/agents/image alt text agent/prompts/tag-builder.prompt.html @@ -71,5 +71,6 @@

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/classroom/HUMAN_TEST_MATRIX.html b/html/classroom/HUMAN_TEST_MATRIX.html index c8f85a2..4277c85 100644 --- a/html/classroom/HUMAN_TEST_MATRIX.html +++ b/html/classroom/HUMAN_TEST_MATRIX.html @@ -307,5 +307,6 @@

              Pass Criteria

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/classroom/assignment-day1-you-belong-here.html b/html/classroom/assignment-day1-you-belong-here.html index e0b9c5e..b347dfa 100644 --- a/html/classroom/assignment-day1-you-belong-here.html +++ b/html/classroom/assignment-day1-you-belong-here.html @@ -73,20 +73,20 @@

              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

              -

              By the end of Day 1, you will have:

              +

              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.

                -
              • Navigated a real GitHub repository using your screen reader
                • -
              • Filed your first issue describing something you noticed
                • -
              • Communicated with teammates using @mentions and comments
                • -
              • Created a branch to work in safely
                • -
              • Made your first commit to a file
                • -
              • Opened a pull request linking your work to an issue
                • -
              • Resolved a merge conflict (or learned how)
                • -
              • Reflected on open source culture and communication
                • -
              • Merged a pull request into the main branch
                • +
              • 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.

              +

              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.

              @@ -121,17 +121,17 @@

              Challenges

              - + - + - + @@ -173,5 +173,6 @@

              Bonus Challenges

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/classroom/assignment-day2-you-can-build-this.html b/html/classroom/assignment-day2-you-can-build-this.html index fc9f12d..8576358 100644 --- a/html/classroom/assignment-day2-you-can-build-this.html +++ b/html/classroom/assignment-day2-you-can-build-this.html @@ -76,19 +76,19 @@

              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

              -

              By the end of Day 2, you will have:

              +

              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.

                -
              • Cloned a repository and worked with Git locally
                • -
              • Pushed a branch and opened a PR from your local machine
                • -
              • Reviewed a classmate's code and given constructive feedback
                • -
              • Used GitHub Copilot as a collaborative tool
                • -
              • Created a custom issue template
                • -
              • Forked a real repository and made a cross-repo contribution
                • -
              • Explored accessibility agents and how they work
                • -
              • Built your own agent from scratch (capstone)
                • +
              • 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.

              +

              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.

              Chapter 4
              6. Your First Pull Request6. Open Your First Pull Request Open a PR that references an issue with Closes #N Chapter 6
              7. Resolve a Merge Conflict7. Survive a Merge Conflict Understand and fix conflict markers Chapter 7
              8. Open Source Culture8. The Culture Layer Reflect on community norms and communication Chapter 8
              @@ -103,32 +103,32 @@

              Challenges

              - + - + - + - + - + - + @@ -142,7 +142,7 @@

              Autograded Challenges

              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.

              +

              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.

              @@ -163,5 +163,6 @@

              Bonus Challenges

              GIT Going with GitHub - A workshop by Community Access

              View on GitHub · community-access.org

              + - \ No newline at end of file + diff --git a/html/classroom/assignment-issue-template.html b/html/classroom/assignment-issue-template.html new file mode 100644 index 0000000..3254ace --- /dev/null +++ b/html/classroom/assignment-issue-template.html @@ -0,0 +1,185 @@ + + + + + + + Assignment Issue Template Reference - GIT Going with GitHub + + + + + + + + +
              +

              Assignment Issue Template Reference

              +

              Use this reference when pre-seeding issues for the Day 1 contribution sprint. Copy and modify it for each student participant. This file is not a GitHub issue template and should not be placed in .github/ISSUE_TEMPLATE/.

              +

              Title

              +

              Fix: [specific problem] in [filename]

              +

              Example: Fix: Heading hierarchy issue in keyboard-shortcuts.md

              +

              Description

              +
              ## What to Fix
+
+[Specific description of the problem - be precise enough that the student knows exactly what line or section to look at. Include the exact error if applicable.]
+
+Example: "In the keyboard-shortcuts.md file, the NVDA section heading jumps from h2 (##) directly to h4 (####). Section headings should be h2, and subsection headings should be h3. This makes the document harder to navigate with a screen reader."
+
+## File to Edit
+
+`learning-room/docs/[filename].md`
+
+## Acceptance Criteria
+
+- [ ] [Specific thing that should be true when the fix is complete]
+- [ ] No new heading-level skips introduced
+- [ ] Link text is descriptive (not "click here")
+- [ ] Changes respect the existing document structure
+
+Example:
+
+- [ ] NVDA section heading is now ## (h2)
+- [ ] All sub-section headings under NVDA are ### (h3)
+- [ ] No heading-level gaps exist in the NVDA section
+- [ ] Document still reads logically with a screen reader
+
+## How to Contribute
+
+See [Working with Issues](../docs/05-working-with-issues.md) and the [Day 1 Agenda](../admin/DAY1_AGENDA.md) for the full contribution workflow.
+
+## Resources
+
+- [Accessibility Standards Reference](../docs/appendix-m-accessibility-standards.md)
+- [Markdown Reference](../docs/appendix-c-markdown-reference.md)
              +

              Pre-Seeded Issues to Create

              +

              Use this table as a checklist. Create one issue per row per student, customizing the assigned student field.

              +
              Chapter 14
              11. Day 2 Pull Request11. Open a Day 2 PR Open a PR from your locally-pushed branch Chapter 15
              12. Code Review12. Review Like a Pro Review a classmate's PR with specific, constructive feedback Chapter 15
              13. Copilot as Collaborator13. AI as Your Copilot Use Copilot to improve documentation and evaluate its output Chapter 16
              14. Design an Issue Template14. Template Remix Create a custom YAML issue template Chapter 17
              15. Discover Accessibility Agents15. Meet the Agents Explore and run agents from the accessibility-agents repo Chapter 19
              16. Build Your Own Agent (Capstone)16. Build Your Agent (Capstone) Design and submit an original agent with responsibilities and guardrails Chapter 20
              + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
              FileProblemAcceptance CriteriaLabelsDifficulty
              keyboard-shortcuts.mdHeading jumps from h2 to h4 (NVDA section)Subheadings are h3, not h4accessibility, good-first-issueEasy
              keyboard-shortcuts.mdBroken link: htps://nvaccess.orgLink reads https://nvaccess.orgbug, good-first-issueEasy
              setup-guide.mdBroken link: htps://github.com/settings/accessibilityLink reads https://github.com/settings/accessibilitybug, good-first-issueEasy
              setup-guide.mdMissing workshop repo link in Step 6Step 6 has actual workshop repo URLdocumentation, good-first-issueEasy
              welcome.md[TODO] Who can contribute sectionParagraph explains diverse contributorsdocumentation, good-first-issueMedium
              welcome.md[TODO] How to read an issue section2-3 sentences about evaluating issuesdocumentation, good-first-issueMedium
              welcome.md[TODO] What merged PR means for profileSentence about GitHub profile/portfoliodocumentation, good-first-issueMedium
              welcome.mdMissing "Last reviewed" dateDate placeholder replaced with today's datedocumentation, good-first-issueEasy
              +

              Tips for Assigning Issues

              +
                +
              1. Ensure each student gets at least one issue, preferably assigned before the workshop starts.
                2. +
              2. Mix difficulty levels by combining one or two easy issues with medium ones per student.
                3. +
              3. Create extra issues for students who finish quickly.
                4. +
              4. Spread work across files so students see different parts of the repo.
                5. +
              5. Link to comprehensive resources in each issue so students can learn while fixing.
                6. +
              6. Set the milestone to "Day 1" so issues appear in the structured sprint view.
                7. +
              + + + + + + diff --git a/html/classroom/challenge-content-review.html b/html/classroom/challenge-content-review.html index 1501749..8245775 100644 --- a/html/classroom/challenge-content-review.html +++ b/html/classroom/challenge-content-review.html @@ -59,7 +59,7 @@

              Challenge Content Review

              -

              This document contains the complete set of instructions for all 9 challenges. +

              This document contains the complete set of instructions for all 9 challenges. It has been written to prioritize accessibility, inclusive language, and clear progression. Visual dependencies (like "green button"), sensory verbs (like "see" or "look at"), and mouse-specific actions (like "click") have been replaced with inclusive terminology ("activate", "select", "navigate", "verify").

              You can review, edit, and refine the content here. Once finalized, Challenge 1 should be pre-created in the template repository, and Challenges 2-9 will be updated in the student-progression.yml bot.

              @@ -67,11 +67,11 @@

              Challenge 1: Find Your W

              (Note: This issue will be pre-created in the learning-room-template repository so it is waiting for the student when they arrive).

              Title: Challenge 1: Find Your Way Around

              Body: - Welcome to Git Going with GitHub!

              +Welcome to Git Going with GitHub!

              We are thrilled to have you here. This repository is your safe, private learning environment for Day 1. Let's start by getting comfortable with your surroundings.

              -

              Your Goal: +

              Your Goal: Explore the main areas of a GitHub repository and locate where the files live.

              -

              Step-by-Step:

              +

              Step-by-Step:

              Web Browser @@ -106,24 +106,24 @@

              Challenge 1: Find Your W

              -

              Expected Outcome: +

              Expected Outcome: You have familiarized yourself with the repository layout and understand where to locate project files.

              -

              ️ Troubleshooting (If you get stuck):

              +

              Troubleshooting (If you get stuck):

                -
              • Feel lost? Use your browser's "Go Back" function or select the repository name at the top left to return to the main page.
                • -
              • Need more context? Review Chapter 2: Understanding GitHub.
                • +
              • Feel lost? Use your browser's "Go Back" function or select the repository name at the top left to return to the main page. +-Need more context? Review Chapter 2: Understanding GitHub.
              -

              To Unlock Challenge 2: +

              To Unlock Challenge 2: To complete this step, leave a comment below saying "Hello World!" and then activate the Close issue button at the bottom of this page. Our Student Progression Bot will instantly open your next challenge!

              Challenge 2: File Your First Issue

              Title: Challenge 2: File Your First Issue

              Body: - Magical! You have completed Challenge 1!

              +Magical! You have completed Challenge 1!

              Welcome to your next step in the journey. Now that you have navigated the repository, it is time to practice communicating with your team using GitHub Issues. Issues are like a shared to-do list where teams discuss ideas, bugs, and tasks.

              -

              Your Goal: +

              Your Goal: File a new issue describing something you noticed in the repository. It can be a typo, an idea for improvement, or just a friendly greeting!

              -

              Step-by-Step:

              +

              Step-by-Step:

              Web Browser @@ -141,7 +141,7 @@

              Challenge 2: File Your First Issue
            • Open the GitHub Pull Requests and Issues view (Ctrl+Shift+G or Cmd+Shift+G on Mac).
              • -
            • Open the Issues creation form: Use the arrow keys to focus the Issues header and select the Stage Changes button (plus icon), or use the command palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and search for "GitHub Issues: Create Issue...".
              • +
            • Open the Issues creation form: Use the arrow keys to focus the Issues header and select the **Stage Changes ** button (plus icon), or use the command palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and search for "GitHub Issues: Create Issue...".
            • Choose the current repository if prompted.
            • Enter a descriptive title in the prompt bar.
            • For the description, a scratchpad file will open. Type your thought there and save it to submit.
              • @@ -153,35 +153,33 @@

              Challenge 2: File Your First Issue
            • Run the interactive issue creator: gh issue create.
              • -
            • Follow the prompts:
                -
              • What would you like to do?: Choose "Create a new issue".
                • -
              • Title: Enter a clear title (e.g., "Idea: Add a welcome banner").
                • -
              • Body: Select "Write with editor" or "Input text" and type your sentence.
                • -
              • What's next?: Select "Submit".
                • -
              -
              • +
            • Follow the prompts: +-What would you like to do?: Choose "Create a new issue". +-**Title **: Enter a clear title (e.g., "Idea: Add a welcome banner"). +-**Body **: Select "Write with editor" or "Input text" and type your sentence. +-What's next?: Select "Submit".

              • -

              Expected Outcome: -The page will update to display your newly created issue with a unique number (like #2). Take a deep breath—you just started a conversation in open source!

              -

              ️ Troubleshooting (If you get stuck):

              +

              Expected Outcome: +The page will update to display your newly created issue with a unique number (like #2). Take a deep breath - you just started a conversation in open source!

              +

              Troubleshooting (If you get stuck):

                -
              • Cannot find the New Issue button? Ensure you are in the "Issues" tab, rather than Pull Requests or Actions.
                • -
              • Unsure what to write? Simply type "Hello World! This is my first issue."
                • -
              • Need more context? Review Chapter 5: Working with Issues.
                • +
              • Cannot find the New Issue button? Ensure you are in the "Issues" tab, rather than Pull Requests or Actions. +-Unsure what to write? Simply type "Hello World! This is my first issue." +-Need more context? Review Chapter 5: Working with Issues.
              -

              To Unlock Challenge 3: +

              To Unlock Challenge 3: When you are finished, return to this issue (Challenge 2) and activate the Close issue button at the bottom of the page. The bot will automatically unlock your next adventure!

              Challenge 3: Join the Conversation

              Title: Challenge 3: Join the Conversation

              Body: - Excellent work! Challenge 2 is complete.

              +Excellent work! Challenge 2 is complete.

              Communication in open source is all about collaboration. Sometimes you need to draw someone's attention to a specific issue. We accomplish this using @mentions.

              -

              Your Goal: +

              Your Goal: Mention Aria, your Workshop Agent, in a comment to ask for a workspace check.

              -

              Step-by-Step:

              +

              Step-by-Step:

              Web Browser @@ -216,30 +214,30 @@

              Challenge 3: Join the Conversation

              -

              Expected Outcome: +

              Expected Outcome: Your comment will appear in the issue history, and Aria will receive a notification to review your progress.

              -

              ️ Troubleshooting:

              +

              Troubleshooting:

                -
              • The menu did not appear? Aria might be busy! Just type @aria-bot manually and post the comment.
                • -
              • Want more details? Review Chapter 5: Working with Issues.
                • +
              • The menu did not appear? Aria might be busy! Just type @aria-bot manually and post the comment. +-Want more details? Review Chapter 5: Working with Issues.
              -

              To Unlock Challenge 4: +

              To Unlock Challenge 4: Post a link to your comment (or the issue you commented on) right here, and then activate Close issue. Your next task awaits!

              Challenge 4: Branch Out

              Title: Challenge 4: Branch Out

              Body: - You are a communication pro! Let us get into the code.

              +You are a communication pro! Let us get into the code.

              In Git, a "branch" is a safe space to work on your ideas without affecting the main project. Think of it as a parallel universe where you can experiment! Aria is watching for new branches to help you along.

              -

              Your Goal: +

              Your Goal: Create a feature branch where you can safely make changes.

              -

              Step-by-Step:

              +

              Step-by-Step:

              Web Browser
              1. Navigate to the Code tab.
                2. -
              2. Locate the branch selector button (it currently indicates main).
                3. +
              3. Locate the branch selector button (it currently indicatesmain).
              4. Access the dropdown and type a new name for your branch in the search box (e.g., feature/my-first-edit).
              5. Select the option that says Create branch: [your-branch-name] from 'main'.
              @@ -250,8 +248,8 @@

              Challenge 4: Branch Out

              1. Open the Source Control view (Ctrl+Shift+G or Cmd+Shift+G on Mac).
                2. -
              2. Use the arrow keys to focus the Branch Name indicator in the Status Bar (bottom left) or open the More Actions (...) menu.
                3. -
              3. Choose Branch → Create Branch....
                4. +
              4. Use the arrow keys to focus the **Branch Name ** indicator in the Status Bar (bottom left) or open the More Actions (...) menu.
                5. +
              5. Choose **Branch ** ->Create Branch....
              6. Type your branch name: feature/my-first-edit.
              @@ -266,25 +264,25 @@

              Challenge 4: Branch Out

    -

    Expected Outcome: +

    Expected Outcome: The page will refresh, and the branch selector will now display your new branch name instead of main. Aria will detect your new branch and is ready for your first commit!

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

      -
    • Forgot the name? Don't worry, Aria can see all your branches.
      • -
    • Branch name invalid? Branch names cannot contain spaces. Use hyphens or underscores instead!
      • -
    • Need more guidance? Review Chapter 4: The Learning Room.
      • +
    • Forgot the name? Don't worry, Aria can see all your branches. +-Branch name invalid? Branch names cannot contain spaces. Use hyphens or underscores instead! +-Need more guidance? Review Chapter 4: The Learning Room.
    -

    To Unlock Challenge 5: +

    To Unlock Challenge 5: Reply to this issue with your new branch name, and then activate Close issue!

    Challenge 5: Make Your Mark

    Title: Challenge 5: Make Your Mark

    Body: - Branch created! You are ready to make your mark.

    +Branch created! You are ready to make your mark.

    Now that you have a safe branch, it is time to edit a file and save your changes. Saving changes in Git is called making a "commit." Aria can help review your commit messages for clarity!

    -

    Your Goal: +

    Your Goal: Edit a file in your repository and make a commit with a clear message. Ask Aria what she thinks of your message!

    -

    Step-by-Step:

    +

    Step-by-Step:

    Web Browser @@ -292,7 +290,7 @@

    Challenge 5: Make Your Mark

  • Verify you are on the branch you just created (check the branch selector).
  • Select a file you wish to edit (for example, the README.md file).
  • Access the Edit this file button (pencil icon) to enter the editor.
    • -
  • Make a small text change—add your name, fix a typo, or add a greeting.
    • +
  • Make a small text change - add your name, fix a typo, or add a greeting.
  • Provide a short, descriptive commit message in the summary box (e.g., "Add my name to the README").
  • Save your changes by selecting the Commit changes button.
    • @@ -305,10 +303,10 @@

    Challenge 5: Make Your Mark

  • Verify you are on the new branch (check the Status Bar).
  • Open the README.md file (or another of your choice) from the Explorer.
  • Make a change in the editor and save the file (Ctrl+S or Cmd+S on Mac).
    • -
  • Stage your changes (this prepares them for your commit): Use the Source Control view (Ctrl+Shift+G or Cmd+Shift+G on Mac). Use the arrow keys to focus your file and select the Stage Changes icon (plus sign), or use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and search for "Git: Stage Changes".
    • +
  • Stage your changes (this prepares them for your commit): Use the **Source Control ** view (Ctrl+Shift+G or Cmd+Shift+G on Mac). Use the arrow keys to focus your file and select the **Stage Changes ** icon (plus sign), or use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and search for "Git: Stage Changes".
  • Type your commit message in the message field (e.g., "Add my name to the README").
    • -
  • Finalize your commit: Select the Commit button, use Ctrl+Enter (Cmd+Enter on Mac), or use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and search for "Git: Commit".
    • -
  • Send your work to GitHub: Select the Sync Changes or Publish Branch button in the Source Control view, or use the Command Palette and search for "Git: Push".
    • +
  • Finalize your commit: Select the **Commit ** button, use Ctrl+Enter (Cmd+Enter on Mac), or use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and search for "Git: Commit".
    • +
  • Send your work to GitHub: Select the **Sync Changes ** or **Publish Branch ** button in the Source Control view, or use the Command Palette and search for "Git: Push".
    • @@ -323,24 +321,24 @@

    Challenge 5: Make Your Mark

    -

    Expected Outcome: +

    Expected Outcome: Your changes are securely saved! If you want feedback on your message, mention @aria-bot in your next comment.

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

    -

    To Unlock Challenge 6: +

    To Unlock Challenge 6: Leave a comment here saying "Committed!" and then activate Close issue to move on!

    Challenge 6: Your First Pull Request

    Title: Challenge 6: Your First Pull Request

    Body: - Changes securely committed! Time to share them with the world.

    +Changes securely committed! Time to share them with the world.

    A Pull Request (PR) is how you ask to merge your work. Aria will perform an automated "Aria Review" as soon as you open it!

    -

    Your Goal: +

    Your Goal: Open a Pull Request and let Aria run her first set of automated accessibility checks.

    -

    Step-by-Step:

    +

    Step-by-Step:

    Web Browser @@ -359,7 +357,7 @@

    Challenge 6: Your First Pull Reques
    1. Open the GitHub Pull Requests and Issues view (Ctrl+Shift+G or Cmd+Shift+G on Mac).
    2. Use the arrow keys to focus the Pull Requests header and select the Stage Changes button (plus icon).
      3. -
    3. Choose the Compare Branch (e.g., feature/my-first-edit) and the Base Branch (main).
      4. +
    4. Choose the **Compare Branch ** (e.g., feature/my-first-edit) and the Base Branch (main).
    5. Type your PR title (e.g., "Add my name to the README").
    6. In the description field, include Closes #1 to link it to your issue.
    7. Select Create or use Ctrl+Enter (Cmd+Enter on Mac).
      8. @@ -371,34 +369,32 @@

      Challenge 6: Your First Pull Reques
      1. Run the interactive PR creator: gh pr create.
        2. -
      2. Follow the prompts:
          -
        • Title: Enter a clear title (e.g., "Add my name to the README").
          • -
        • Body: Select "Write with editor" and include Closes #1 in your description.
          • -
        • What's next?: Select "Submit".
          • -
        -
        3. +
      3. Follow the prompts: +-**Title **: Enter a clear title (e.g., "Add my name to the README"). +-**Body **: Select "Write with editor" and include Closes #1 in your description. +-What's next?: Select "Submit".

    -

    Expected Outcome: +

    Expected Outcome: Your PR is live! Within seconds, look for a comment from Aria the Workshop Agent. She will provide a "Validation Report" on your changes.

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

      -
    • Aria didn't respond? Check the "Checks" tab at the top of the PR to see if her automation is running.
      • -
    • Validation failed? Read Aria's report! She usually provides specific tips on how to fix accessibility issues.
      • -
    • Learn more about PRs: Chapter 6: Working with Pull Requests.
      • +
    • Aria didn't respond? Check the "Checks" tab at the top of the PR to see if her automation is running. +-Validation failed? Read Aria's report! She usually provides specific tips on how to fix accessibility issues. +-**Learn more about PRs: ** Chapter 6: Working with Pull Requests.
    -

    To Unlock Challenge 7: +

    To Unlock Challenge 7: Post a link to your Pull Request right here, then activate Close issue!

    Challenge 7: Resolve a Merge Conflict

    Title: Challenge 7: Resolve a Merge Conflict

    Body: - Pull Request successfully opened! You are doing amazing.

    -

    Sometimes, two people edit the same line. This is a "Merge Conflict." Aria is an expert at explaining these—just ask her if you get stuck!

    -

    Your Goal: +Pull Request successfully opened! You are doing amazing.

    +

    Sometimes, two people edit the same line. This is a "Merge Conflict." Aria is an expert at explaining these - just ask her if you get stuck!

    +

    Your Goal: Resolve a conflict if one appears, or ask Aria to explain how conflicts work.

    -

    Step-by-Step:

    +

    Step-by-Step:

    Web Browser @@ -406,7 +402,7 @@

    Challenge 7: Resolve a Merge Confl
  • If your PR has a conflict, select the Resolve conflicts button.
  • Look for the markers: <<<<<<<, =======, and >>>>>>>.
  • Edit the text to your preferred version and remove the markers.
    • -
  • Finalize the resolution by selecting Mark as resolved and Commit merge.
    • +
  • Finalize the resolution by selecting **Mark as resolved ** and Commit merge.

    • @@ -435,48 +431,48 @@

    Challenge 7: Resolve a Merge Confl -

    Not sure what to do? Drop a comment: @aria-bot I have a merge conflict, can you explain this?

    -

    Expected Outcome: +

    Not sure what to do? Drop a comment: @aria-bot I have a merge conflict, can you explain this?

    +

    Expected Outcome: The conflict warning will disappear. If you asked Aria for help, she'll reply with a step-by-step guide to conflict resolution.

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

      -
    • No conflict? You're lucky! But still ask Aria: @aria-bot explain merge conflict to learn for next time.
      • -
    • Need a deep dive? Read Chapter 7: Merge Conflicts.
      • +
    • No conflict? You're lucky! But still ask Aria: @aria-bot explain merge conflict to learn for next time. +-Need a deep dive? Read Chapter 7: Merge Conflicts.
    -

    To Unlock Challenge 8: +

    To Unlock Challenge 8: Leave a comment here explaining how Aria helped you understand conflicts, then activate Close issue!

    Challenge 8: Open Source Culture

    Title: Challenge 8: Open Source Culture

    Body: -️ Conflicts handled! You are unstoppable.

    +Conflicts handled! You are unstoppable.

    Writing code is only a small part of open source. The rest relies on communication, empathy, and culture. We want to build an environment where everyone feels they belong.

    -

    Your Goal: +

    Your Goal: Reflect on community norms, healthy collaboration, and inclusive contribution practices.

    -

    Step-by-Step:

    +

    Step-by-Step:

    1. Take a few minutes to review Chapter 8: Open Source Culture.
    2. Consider a time a project or group made you feel welcomed, or what you would do to make others feel welcome.
    3. Write a short reflection about how good communication impacts software development teams.
    -

    Expected Outcome: +

    Expected Outcome: A stronger appreciation for the humans behind the screens, and an understanding of how tone in PRs and reviews makes all the difference.

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

      -
    • Unsure what to write? Just share one sentence about what "assuming best intent" means to you.
      • -
    • Feeling stuck? Discuss it with your buddy!
      • +
    • Unsure what to write? Just share one sentence about what "assuming best intent" means to you. +-Feeling stuck? Discuss it with your buddy!
    -

    To Unlock Challenge 9: +

    To Unlock Challenge 9: Record your reflection as a comment right here, and then activate Close issue. The final step is next!

    Challenge 9: Merge Day

    Title: Challenge 9: Merge Day

    Body: - Thank you for taking the time to reflect! We are in the home stretch.

    +Thank you for taking the time to reflect! We are in the home stretch.

    You have communicated, branched, committed, and resolved. Now it is the moment of truth. It is time to merge your changes into the main project!

    -

    Your Goal: +

    Your Goal: Get your Pull Request reviewed, approved, and merged! Aria will be cheering you on at the finish line.

    -

    Step-by-Step:

    +

    Step-by-Step:

    Web Browser @@ -495,8 +491,8 @@

    Challenge 9: Merge Day

    1. Open the Pull Requests view.
    2. Use the arrow keys to choose your PR from the list.
      3. -
    3. Open the More Actions (...) menu or select the Merge button at the top of the PR overview.
      4. -
    4. Choose the merge strategy (e.g., Create Merge Commit or Squash and Merge).
      5. +
    5. Open the **More Actions (...) ** menu or select the Merge button at the top of the PR overview.
      6. +
    6. Choose the merge strategy (e.g.,Create Merge Commit or Squash and Merge).
    7. Finalize the merge by selecting Confirm Merge.
    8. Select Delete Branch if prompted to keep the repository clean.
    @@ -508,32 +504,32 @@

    Challenge 9: Merge Day

    1. Identify your PR number or use the current branch: gh pr list.
    2. Run the merge command: gh pr merge [pr-number].
      3. -
    3. Select your merge strategy when prompted (e.g., Merge commit).
      4. +
    4. Select your merge strategy when prompted (e.g.,Merge commit).
    5. Choose Yes when asked if you want to delete the local and remote branches.
    -

    Expected Outcome: +

    Expected Outcome: Your Pull Request will display a "Merged" status indicator. Aria might leave a final celebratory comment on your repository!

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

      -
    • The merge button is disabled? Aria or other automated checks might still be running. Wait for the green checkmarks!
      • -
    • Want to know more about wrapping up? Check out Chapter 10: Notifications and Day 1 Close.
      • +
    • The merge button is disabled? Aria or other automated checks might still be running. Wait for the green checkmarks! +-Want to know more about wrapping up? Check out Chapter 10: Notifications and Day 1 Close.
    -

    To Finish Day 1: +

    To Finish Day 1: Leave a comment here saying "MERGED!" and then activate Close issue.

    -

    Congratulations! Aria is proud of you. You have completely finished Day 1. Rest, hydrate, and prepare for a fantastic Day 2!

    +

    Congratulations! Aria is proud of you. You have completely finished Day 1. Rest, hydrate, and prepare for a fantastic Day 2!

    Day 2: You Can Build This

    Challenge 10: Go Local

    Title: Challenge 10: Go Local

    Body: - Welcome Back! Day 2 begins now.

    +Welcome Back! Day 2 begins now.

    Day 2 moves from the browser to your local machine. We are introducing real-world development workflows using Git!

    -

    Your Goal: +

    Your Goal: Clone your repository to your local machine, create a branch, make a change, and push it back up to GitHub.

    -

    Step-by-Step:

    +

    Step-by-Step:

    Visual Studio Code @@ -544,7 +540,7 @@

    Challenge 10: Go Local

  • Paste the URL and choose a folder on your computer. Select Open in the new window.
  • Create a new branch: Use the arrow keys to focus the branch name in the Status Bar (bottom left) or use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and search for "Git: Create Branch...".
  • Edit a file, save it (Ctrl+S or Cmd+S on Mac), and open the Source Control view (Ctrl+Shift+G or Cmd+Shift+G on Mac).
    • -
  • Stage your changes: Use the arrow keys to focus your file and select the Stage Changes icon (plus sign), type a message, and select Commit (Ctrl+Enter or Cmd+Enter on Mac).
    • +
  • Stage your changes: Use the arrow keys to focus your file and select the **Stage Changes ** icon (plus sign), type a message, and select Commit (Ctrl+Enter or Cmd+Enter on Mac).
  • Choose Publish Branch to send it to GitHub.
    • @@ -566,9 +562,9 @@

    Challenge 10: Go Local

    GitHub Desktop
      -
    1. Copy the repository URL and select File → Clone repository... in GitHub Desktop.
      2. -
    2. Select the URL tab, paste the link, and choose your local path. Select Clone.
      3. -
    3. Select the Current Branch menu and choose New Branch → name it feature/day2-local-edit.
      4. +
    4. Copy the repository URL and select **File ** ->Clone repository... in GitHub Desktop.
      5. +
    5. Select the **URL ** tab, paste the link, and choose your local path. Select Clone.
      6. +
    6. Select the **Current Branch ** menu and choose New Branch -> name it feature/day2-local-edit.
    7. Open the file in your preferred editor, make a change, and save.
    8. Return to GitHub Desktop. Your changes will be listed on the left.
    9. Provide a summary in the bottom-left box and select Commit to [branch-name].
      10. @@ -576,25 +572,25 @@

      Challenge 10: Go Local

    -

    Expected Outcome: +

    Expected Outcome: Your changes made on your computer are securely backed up on GitHub. You will be able to see your new branch listed in the repository's branch selector on the website.

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

      -
    • Having trouble cloning? Ensure you copied the correct HTTPS or SSH URL from the repository.
      • -
    • Push rejected? Make sure you committed your changes first.
      • -
    • Need a walkthrough? Review Chapter 14: Git in Practice.
      • +
    • Having trouble cloning? Ensure you copied the correct HTTPS or SSH URL from the repository. +-Push rejected? Make sure you committed your changes first. +-Need a walkthrough? Review Chapter 14: Git in Practice.
    -

    To Unlock Challenge 11: +

    To Unlock Challenge 11: Reply to this issue with a joyful message that you pushed your code, and then activate Close issue!

    Challenge 11: Day 2 Pull Request

    Title: Challenge 11: Day 2 Pull Request

    Body: - Excellent work connecting your local environment!

    +Excellent work connecting your local environment!

    Now that your local branch is safely on GitHub, it is time to propose merging those changes into the main project. Aria will be waiting to validate your work!

    -

    Your Goal: +

    Your Goal: Open a Pull Request from your local branch and wait for Aria's automated validation report.

    -

    Step-by-Step:

    +

    Step-by-Step:

    Web Browser @@ -611,8 +607,8 @@

    Challenge 11: Day 2 Pull Request

    1. Open the GitHub Pull Requests and Issues view (Ctrl+Shift+G or Cmd+Shift+G on Mac).
      2. -
    2. Select the Stage Changes button (plus icon) next to the Pull Requests header.
      3. -
    3. Choose the Compare Branch (e.g., feature/day2-local-edit) and the Base Branch (main).
      4. +
    4. Select the **Stage Changes ** button (plus icon) next to the Pull Requests header.
      5. +
    5. Choose the **Compare Branch ** (e.g., feature/day2-local-edit) and the Base Branch (main).
    6. Type your PR title (e.g., "Day 2 local edit").
    7. In the description field, type a sentence or two summarizing your change.
    8. Select Create or use Ctrl+Enter (Cmd+Enter on Mac).
      9. @@ -624,32 +620,30 @@

      Challenge 11: Day 2 Pull Request

      1. Run the interactive PR creator: gh pr create.
        2. -
      2. Follow the prompts:
          -
        • Title: Enter a clear title (e.g., "Day 2 local edit").
          • -
        • Body: Select "Write with editor" and summarize your changes.
          • -
        • What's next?: Select "Submit".
          • -
        -
        3. +
      3. Follow the prompts: +-**Title **: Enter a clear title (e.g., "Day 2 local edit"). +-**Body **: Select "Write with editor" and summarize your changes. +-What's next?: Select "Submit".
    -

    Expected Outcome: +

    Expected Outcome: Your Pull Request is live! Aria will run her automated checks and post a validation report right in the conversation.

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

      -
    • Cannot find your branch? Verify that the "push" command completed successfully locally.
      • -
    • Aria is silent? Check the "Checks" tab to see if the workflow is running. +
    • Cannot find your branch? Verify that the "push" command completed successfully locally. +-Aria is silent? Check the "Checks" tab to see if the workflow is running. Post a link to your new Pull Request right here, then activate Close issue!

    Challenge 12: Code Review

    Title: Challenge 12: Code Review

    Body: - You are doing fantastic! Let's examine peer feedback.

    +You are doing fantastic! Let's examine peer feedback.

    Reviewing code is where the most learning happens in open source. It is about asking questions, offering suggestions, and assuming best intent.

    -

    Your Goal: +

    Your Goal: Review a classmate's Pull Request and provide specific, constructive feedback. Aria will celebrate your collaborative spirit!

    -

    Step-by-Step:

    +

    Step-by-Step:

    Web Browser @@ -685,24 +679,24 @@

    Challenge 12: Code Review

    -

    Expected Outcome: +

    Expected Outcome: Your feedback appears on their PR! Aria will post a celebration message once your review is approved.

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

      -
    • No classmate PRs to review? Ask a facilitator for a sample PR to practice on.
      • -
    • Want to learn how to frame feedback? Review Chapter 15: Code Review.
      • +
    • No classmate PRs to review? Ask a facilitator for a sample PR to practice on. +-Want to learn how to frame feedback? Review Chapter 15: Code Review.
    -

    To Unlock Challenge 13: +

    To Unlock Challenge 13: Leave a comment here confirming you left a review, and then activate Close issue!

    Challenge 13: Copilot as Collaborator

    Title: Challenge 13: Copilot as Collaborator

    Body: - Time to introduce AI into your workflow!

    -

    GitHub Copilot is your AI pair programmer—much like Aria, it’s here to help you build great things. Today, we’ll use it to improve documentation.

    -

    Your Goal: +Time to introduce AI into your workflow!

    +

    GitHub Copilot is your AI pair programmer - much like Aria, it’s here to help you build great things. Today, we’ll use it to improve documentation.

    +

    Your Goal: Use GitHub Copilot to suggest improvements and have Aria review the result!

    -

    Step-by-Step:

    +

    Step-by-Step:

    Visual Studio Code (Primary Method) @@ -738,29 +732,29 @@

    Challenge 13: Copilot as Collabora

    -

    Expected Outcome: +

    Expected Outcome: You have successfully utilized AI to enhance your output while staying the "human-in-the-loop."

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

    -

    To Unlock Challenge 14: +

    To Unlock Challenge 14: Share what prompt you used here, then activate Close issue!

    Challenge 14: Design an Issue Template

    Title: Challenge 14: Design an Issue Template

    Body: - Templates make everyone's life easier!

    +Templates make everyone's life easier!

    Projects use Issue Templates to ensure contributors provide the right information from the start. Let's build a custom one using YAML.

    -

    Your Goal: +

    Your Goal: Create a custom YAML issue template in your repository.

    -

    Step-by-Step:

    +

    Step-by-Step:

    Web Browser
      -
    1. In your repository, navigate to the .github/ISSUE_TEMPLATE directory. (If it doesn't exist, create it by choosing Add file → Create new file and typing the full path).
      2. +
    2. In your repository, navigate to the .github/ISSUE_TEMPLATE directory. (If it doesn't exist, create it by choosing Add file ->Create new file and typing the full path).
    3. Name your new file custom-template.yml.
    4. Add the required YAML frontmatter (like name, description, and title).
    5. Commit your new file directly to a new branch and open a Pull Request.
      6. @@ -791,48 +785,48 @@

      Challenge 14: Design an Issue Tem

    -

    Expected Outcome: -An automated check will verify your template contains the required +

    Expected Outcome: +An automated check will verify your template contains the required ame and description fields. Once merged, future contributors will see this template as an option when creating a new issue!

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

      -
    • Autograder failed? Double check your YAML spacing and indentation.
      • -
    • Need a YAML template example? Review Chapter 17: Issue Templates.
      • +
    • Autograder failed? Double check your YAML spacing and indentation. +-Need a YAML template example? Review Chapter 17: Issue Templates.
    -

    To Unlock Challenge 15: +

    To Unlock Challenge 15: Post a link to your Issue Template PR here, then activate Close issue!

    Challenge 15: Discover Accessibility Agents

    Title: Challenge 15: Discover Accessibility Agents

    Body: - We are moving into our capstone project space!

    +We are moving into our capstone project space!

    Accessibility Agents like Aria are automated tools that assist visually impaired users or check for compliance. Today, you'll meet more of Aria's peers!

    -

    Your Goal: +

    Your Goal: Explore the main accessibility-agents repository. Ask Aria if you have questions about any particular agent!

    -

    Step-by-Step:

    +

    Step-by-Step:

    1. Navigate to the Community-Access/accessibility-agents repository.
    2. Read the README.md to understand how Aria and her colleagues work.
    3. Explore an existing agent folder to see its structure.
    -

    Expected Outcome: +

    Expected Outcome: You'll understand the agent architecture. If you're confused, mention @aria-bot with: "How does the agent schema work?"

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

    -

    To Unlock Challenge 16: +

    To Unlock Challenge 16: Type the name of the agent you explored right here, then activate Close issue!

    Challenge 16: Build Your Own Agent (Capstone)

    Title: Challenge 16: Build Your Own Agent (Capstone)

    Body: - Welcome to your Capstone Challenge!

    +Welcome to your Capstone Challenge!

    It is time to put everything you have learned together. You are going to build a new colleague for Aria!

    -

    Your Goal: +

    Your Goal: Fork the accessibility-agents repository, design an original agent, and submit your PR for Aria's final review.

    -

    Step-by-Step:

    +

    Step-by-Step:

    Web Browser + Codespaces (Quickest) @@ -870,21 +864,22 @@

    Challenge 16: Build Your Own

    -

    Expected Outcome: +

    Expected Outcome: Aria will validate your agent's structure. Once approved, your new agent will join the Community-Access collection!

    -

    ️ Troubleshooting:

    +

    Troubleshooting:

    -

    To Complete the Workshop: +

    To Complete the Workshop: Post the link to your Capstone PR here, then activate Close issue.

    -

    CONGRATULATIONS! Aria is thrilled to have a new teammate. You have completed the Git Going with GitHub workshop!

    +

    CONGRATULATIONS! Aria is thrilled to have a new teammate. You have completed the Git Going with GitHub workshop!

    + - \ No newline at end of file + diff --git a/html/classroom/grading-guide.html b/html/classroom/grading-guide.html index ef11fb0..24f9020 100644 --- a/html/classroom/grading-guide.html +++ b/html/classroom/grading-guide.html @@ -94,7 +94,7 @@

    Day 1 Challenges (01-09)

    01 -Scavenger Hunt +Find Your Way Around Issue comment listing findings Student explored multiple tabs and found key files @@ -288,5 +288,6 @@

    Edge Cases

    GIT Going with GitHub - A workshop by Community Access

    View on GitHub · community-access.org

    + - \ No newline at end of file + diff --git a/html/classroom/index.html b/html/classroom/index.html index 4df9cb0..0e23fed 100644 --- a/html/classroom/index.html +++ b/html/classroom/index.html @@ -62,6 +62,9 @@

    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:

      @@ -162,19 +165,31 @@

      What Is in This Directory

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

        @@ -366,19 +381,19 @@

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

        @@ -412,10 +427,10 @@

        Aria verification

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

        @@ -513,21 +528,21 @@

        Day 1 (Assignment 1): Challenges 1-9< 6 -Your First Pull Request +Open Your First Pull Request Close issue Yes (PR structure) Yes (issue reference) 7 -Resolve a Merge Conflict +Survive a Merge Conflict Close issue Yes (PR feedback) Yes (no conflict markers) 8 -Open Source Culture +The Culture Layer Close issue -- -- @@ -674,5 +689,6 @@

        GIT Going with GitHub - A workshop by Community Access

        View on GitHub · community-access.org

        + - \ No newline at end of file + diff --git a/html/classroom/teardown-checklist.html b/html/classroom/teardown-checklist.html index ae9fd0a..a8f2a87 100644 --- a/html/classroom/teardown-checklist.html +++ b/html/classroom/teardown-checklist.html @@ -62,19 +62,19 @@

        Post-Workshop Teardown Checklist

        Use this checklist after each workshop cohort completes the course.

        Within 24 hours of Day 2

          -
        • Export grades from GitHub Classroom (Classroom Settings, Download Grades)
          • -
        • Verify all students have at least one merged PR
          • -
        • Note any students who need follow-up (incomplete capstone, missing challenges)
          • -
        • Send post-workshop survey link (see ANNOUNCEMENT.md for template)
          • +
        • Export grades from GitHub Classroom (Classroom Settings, Download Grades)
          • +
        • Verify all students have at least one merged PR
          • +
        • Note any students who need follow-up (incomplete capstone, missing challenges)
          • +
        • Send post-workshop survey link (see ANNOUNCEMENT.md for template)

        Within one week

          -
        • Review student feedback from surveys
          • -
        • Move any private registration exports, accommodation notes, grade exports, or follow-up notes to Community-Access/git-going-student-success
          • -
        • Archive the classroom (Classroom Settings, Archive)
          • -
        • Close any remaining open issues across student Learning Room repositories (or leave them open if students want to continue practicing post-workshop)
          • -
        • Merge or close any abandoned student PRs with a kind comment
          • -
        • Update the student roster in the main repo if students should retain access for ongoing contribution
          • +
        • Review student feedback from surveys
          • +
        • Move any private registration exports, accommodation notes, grade exports, or follow-up notes to Community-Access/git-going-student-success
          • +
        • Archive the classroom (Classroom Settings, Archive)
          • +
        • Close any remaining open issues across student Learning Room repositories (or leave them open if students want to continue practicing post-workshop)
          • +
        • Merge or close any abandoned student PRs with a kind comment
          • +
        • Update the student roster in the main repo if students should retain access for ongoing contribution

        Clean up student repositories

        GitHub Classroom creates one repository per student per assignment. After the course:

        @@ -85,17 +85,17 @@

        Clean up student repositories

      Update facilitator notes

        -
      • Document any chapter sections that confused multiple students
        • -
      • Note any technical issues encountered (e.g., Copilot activation problems, clone failures)
        • -
      • File issues in the git-going-with-github repo for curriculum improvements
        • -
      • Update the FACILITATOR.md with any new troubleshooting tips
        • +
      • Document any chapter sections that confused multiple students
        • +
      • Note any technical issues encountered (e.g., Copilot activation problems, clone failures)
        • +
      • File issues in the git-going-with-github repo for curriculum improvements
        • +
      • Update the FACILITATOR.md with any new troubleshooting tips

      Prepare for next cohort

        -
      • Review and incorporate feedback from this cohort
        • -
      • Update roster-template.csv with new student list
        • -
      • Create a fresh classroom following README.md
        • -
      • Test all invite links with a test account
        • +
      • Review and incorporate feedback from this cohort
        • +
      • Update roster-template.csv with new student list
        • +
      • Create a fresh classroom following README.md
        • +
      • Test all invite links with a test account
      @@ -103,5 +103,6 @@

      Prepare for next cohort

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/docs/00-pre-workshop-setup.html b/html/docs/00-pre-workshop-setup.html index 5118e95..8388dfa 100644 --- a/html/docs/00-pre-workshop-setup.html +++ b/html/docs/00-pre-workshop-setup.html @@ -60,7 +60,7 @@

      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.

      +

      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 @@ -71,6 +71,7 @@

      Everything You Need Before Day

      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

      1. What You Will Need
        2. @@ -608,6 +609,8 @@

        Turn on Quick Nav for fast naviga
      2. Press Left Arrow + Right Arrow simultaneously to toggle Quick Nav
      3. With Quick Nav on: H = next heading, L = next link, B = next button (same as NVDA/JAWS browse mode keys)
        4. +

        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

        @@ -1090,7 +1093,7 @@

        Getting Help Before the Event

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

        @@ -1100,5 +1103,6 @@

        Getting Help Before the Event

        GIT Going with GitHub - A workshop by Community Access

        View on GitHub · community-access.org

        + - \ No newline at end of file + diff --git a/html/docs/01-choose-your-tools.html b/html/docs/01-choose-your-tools.html index 654d246..6b7f0b2 100644 --- a/html/docs/01-choose-your-tools.html +++ b/html/docs/01-choose-your-tools.html @@ -645,7 +645,7 @@

        10. If You Get Stuck

        -

        ➡️ Next Step: Start your learning journey with Chapter 02: Understanding GitHub.

        +

        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

        @@ -655,5 +655,6 @@

        10. If You Get Stuck

        GIT Going with GitHub - A workshop by Community Access

        View on GitHub · community-access.org

        + - \ No newline at end of file + diff --git a/html/docs/01-understanding-github-web-structure.html b/html/docs/01-understanding-github-web-structure.html deleted file mode 100644 index d54c209..0000000 --- a/html/docs/01-understanding-github-web-structure.html +++ /dev/null @@ -1,667 +0,0 @@ - - - - - - - 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.

        -
        -

        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

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

        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.

        -

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

        5. Visual Map of a Repository Page

        -

        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.

        -
        -
        - - -

        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.

        -
        -

        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.

        -

        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.

        -
        -

        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: Navigating Repositories -Back: Pre-Workshop Setup -Reference: Screen Reader Cheat Sheet | GitHub Concepts Glossary

        - -
        - - - \ No newline at end of file diff --git a/html/docs/02-navigating-repositories.html b/html/docs/02-navigating-repositories.html deleted file mode 100644 index 2966203..0000000 --- a/html/docs/02-navigating-repositories.html +++ /dev/null @@ -1,752 +0,0 @@ - - - - - - - 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.

        -
        -

        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 2)

        -

        Chapter 2 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 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

        -

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

        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/learning-room
-
-# Clone and cd into the folder
-gh repo clone community-access/learning-room && cd learning-room
        -

        Or with standard Git

        -
        git clone https://github.com/community-access/learning-room.git
-cd learning-room
        -

        Setup: Install the GitHub CLI from cli.github.com and authenticate with gh auth login. See Appendix D for details.

        -
        - - -

        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.

        -

        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.

        -
        -
        - - -

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

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

        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: The Learning Room -Back: Understanding GitHub's Web Structure -Reference: Screen Reader Cheat Sheet

        - -
        - - - \ No newline at end of file diff --git a/html/docs/02-understanding-github.html b/html/docs/02-understanding-github.html index b66f112..3cbfe18 100644 --- a/html/docs/02-understanding-github.html +++ b/html/docs/02-understanding-github.html @@ -60,7 +60,7 @@

        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.

        +

        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 @@ -860,7 +860,7 @@

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

        @@ -870,5 +870,6 @@

        Day 2 Amplifier

        GIT Going with GitHub - A workshop by Community Access

        View on GitHub · community-access.org

        + - \ No newline at end of file + diff --git a/html/docs/03-navigating-repositories.html b/html/docs/03-navigating-repositories.html index 6d8fe44..fed3c7b 100644 --- a/html/docs/03-navigating-repositories.html +++ b/html/docs/03-navigating-repositories.html @@ -60,7 +60,7 @@

        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.

        +

        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 @@ -73,8 +73,8 @@

        A Screen Reader Guide to G

        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 2)

        -

        Chapter 2 is a confidence-building orientation chapter.

        +

        Workshop Recommendation (Chapter 3)

        +

        Chapter 3 is a confidence-building orientation chapter.

        • Challenge count: none
        • Automation check: none
          • @@ -86,7 +86,7 @@

          Safety-First Learning Pattern

        • 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 issue-based, traceable challenges.
          • +
        • 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.

      @@ -961,7 +961,7 @@

      Day 2 Amplifier -

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

      @@ -971,5 +971,6 @@

      Day 2 Amplifier -

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/docs/03-the-learning-room.html b/html/docs/03-the-learning-room.html deleted file mode 100644 index 33cdb89..0000000 --- a/html/docs/03-the-learning-room.html +++ /dev/null @@ -1,772 +0,0 @@ - - - - - - - The Learning Room: Shared Practice Repository - GIT Going with GitHub - - - - - - - - -
      -

      The Learning Room: Shared 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.

      -
      -

      What Is the Learning Room?

      -

      The Learning Room is a single, shared GitHub repository where all workshop participants collaborate together. It is not your personal fork. It is not your individual repository. It is one repo with many students, many branches, and many pull requests.

      -

      Workshop Recommendation (Chapter 3)

      -

      Chapter 3 is a system orientation chapter.

      -
        -
      • Challenge count: none
        • -
      • Automation check: none
        • -
      • Why: this chapter explains the shared workflow and prepares students for issue-based challenges in Chapters 4 and 5.
        • -
      -

      Readiness Checkpoint

      -

      Before starting Chapter 4 challenges, students should be able to:

      -
        -
      1. Find learning-room/docs/CHALLENGES.md.
        2. -
      2. Explain issue -> branch -> PR -> review -> merge.
        3. -
      3. Identify where bot feedback appears on PRs.
        4. -
      -

      Description

      -

      The learning-room is a single shared repository. It has a protected main branch, and each student opens pull requests against it. For example: Student A's PR #12 is open and assigned to Student B for review, Student B's PR #13 is assigned to Student C, Student C's PR #14 is assigned to Student A, and Student A's earlier PR #11 has already been merged. More PRs appear as students contribute.

      -

      Why one shared repo?

      -
        -
      • Realistic - Open source projects are shared spaces
        • -
      • Community - You see each other's work and learn from each other
        • -
      • Peer review - You review the people sitting next to you
        • -
      • Automation - The bot serves one repo, coordinating all contributions
        • -
      -

      Two Tracks, One Repository

      -

      Throughout Day 1, you work on two parallel learning tracks:

      -

      Track 1: GitHub Skills Modules (Your Account)

      - -

      Scope: Your personal account (private to you unless you make it public)
      Bot: Mona (GitHub's automated learning bot) guides each step
      Pace: Self-directed, you complete at your own speed
      Purpose: Hands-on practice of individual skills

      -

      Track 2: Learning Room Contribution Sprint (Shared)

      -
        -
      • Block 5: Your first real contribution (you and 5-20 other students contributing simultaneously)
        • -
      • Block 6: Community tools (labels, milestones, notifications)
        • -
      -

      Scope: The shared learning-room repository (one repo, visible to everyone)
      Bot: The Learning Room automation bot validates PRs and tracks progress
      Pace: Structured by facilitator; synchronized with workshop schedule
      Purpose: Collaborative practice of the full workflow (issue → branch → PR → review → merge)

      -

      The Two Tracks Reinforce Each Other

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      StepSkills Module (individual)Learning Room (group)
      1Create a branchCreate a branch (together)
      2Open a PROpen a PR (see others' too)
      3Get instant bot feedbackGet bot feedback + human review
      4Mona verifies your stepHuman peer reviewer approves
      5Next step unlockedReady to merge
      -

      Learning Room Folder Structure

      -

      The learning-room repository contains these files and folders:

      -
        -
      • README.md -- Getting started guide
        • -
      • AUTOMATION.md -- How the bot works
        • -
      • .github/
          -
        • workflows/ -- 3 automation workflows
            -
          • learning-room-pr-bot.yml (PR validation)
            • -
          • skills-progression.yml (progress 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/
            -
          • LEARNING_PATHS.md (skill progression guide)
            • -
          • IMPLEMENTATION_GUIDE.md (facilitator setup)
            • -
          -
          • -
        -
        • -
      • docs/
          -
        • CHALLENGES.md -- 12 challenges (Beginner to Expert)
          • -
        • GROUP_CHALLENGES.md -- 7 collaborative exercises
          • -
        • 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

      -

      When you join the workshop, the facilitator creates a personal practice branch for you in the Learning Room repository. This branch is automatically created using your GitHub username with -practice appended:

      -
      -

      Branch naming convention: username-practice (all lowercase)

      -
      -

      Examples:

      -
        -
      • If your GitHub username is payown, your practice branch is payown-practice
        • -
      • If your username is BudgieMom, your practice branch is budgiemom-practice
        • -
      • If your username is Weijun-Zhang-1996, your practice branch is weijun-zhang-1996-practice
        • -
      -

      Why you have a practice branch

      -
        -
      • Protected main branch - The main branch in the Learning Room is protected and requires pull requests for all changes
        • -
      • Your workspace - Your practice branch is where you commit and push changes before opening a PR
        • -
      • No conflicts - Each student has their own branch, so you will never accidentally overwrite someone else's work
        • -
      • Realistic workflow - This mirrors how real open source projects work - contributors create feature branches and submit pull requests
        • -
      -

      How to use your practice branch

      -
        -
      1. When you clone the Learning Room repository locally (Chapter 11), switch to your practice branch:
        git checkout username-practice
        -
        2. -
      2. Make your changes, commit them to your practice branch
        3. -
      3. Push your practice branch to GitHub
        4. -
      4. Open a pull request from your practice branch → main
        5. -
      -
      -

      Which branch do I use and when?

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      ChapterBranch needed?What to use
      Chapter 4 (Issues)NoWork happens in issue threads directly. No branch or file editing required.
      Chapter 6 (PRs, web editor)Yes, auto-createdGitHub creates a branch when you click "Propose changes." Name it fix/yourname-issueXX.
      Chapter 6 (PRs, local clone)Yes, create manuallygit checkout -b fix/yourname-issueXX from main.
      Chapter 11+ (Local Git)YesUse your username-practice branch or create fix/yourname-issueXX branches from main.
      -

      Summary: Chapter 4 needs no branch. Chapters 6-7 use short-lived fix/ branches. Your username-practice branch becomes essential starting in Chapter 11 when you work locally with Git and VS Code.

      -
      -

      The Practice Files: What You Will Work On

      -

      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 12 challenges organized by skill level:

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      LevelChallengesRequirement
      Beginner (1-3)Fix broken link, add shortcut, complete welcome guide0+ merged PRs
      Intermediate (4-6)Fix heading hierarchy, improve link text, add alt text1+ merged PRs
      Advanced (7-9)Accessibility review, create documentation, mentor a peer3+ merged PRs
      Expert (10-12)Design a challenge, full accessibility audit, create issue template5+ merged PRs
      -

      Each challenge lists the file(s) to edit, estimated time, skills practiced, success criteria, and a link to detailed instructions.

      -

      docs/GROUP_CHALLENGES.md - Collaborative Exercises

      -

      Seven group exercises for study groups, ranging from a Documentation Sprint (divide docs/welcome.md among group members) to a Full Repository Audit (each person audits a section of the workshop documentation). Groups of 2-6 students work together with coordinated PRs and cross-review.

      -

      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 the PR. All students can read it.

      -

      Step 3: Peer Reviewer Is Assigned

      -

      Pairing Bot (.github/workflows/student-grouping.yml)

      -
        -
      • Automatically selects a reviewer (uses least_reviews strategy - balances workload)
        • -
      • Requests review via GitHub API
        • -
      • Posts assignment comment explaining what to look for
        • -

      • Example:

        -
        ## Peer Review Assigned
-
-Hi @studentA! Your PR has been automatically paired with @studentC for peer review.
-
-### For @studentC:
-This is a great opportunity to practice code review skills! Here's what to look for:
-- Did all three [TODO] sections get completed in welcome.md?
-- Does the new content match the style of existing sections?
-- Is the heading hierarchy correct (H1 → H2)?
-- Does the bot report pass all required checks?
        -
        • -
      -

      Visibility

      -
        -
      • Student A sees their assigned reviewer
        • -
      • Student C receives a notification: "review requested"
        • -
      • All students see the assignment comment in the PR thread
        • -
      -

      Step 4: Reviewer Reads and Comments

      -

      Student C (the assigned reviewer reviewing the welcome.md changes)

      -
        -
      1. Receives notification: "PR review requested"
        2. -
      2. Navigates to the PR in the Learning Room repo
        3. -
      3. Reads:
          -
        • PR title: "Complete [TODO] sections in welcome.md"
          • -
        • PR description: lists which sections were completed
          • -
        • Bot 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

      -
        -
      • Student A (PR author) gets notification: "Your PR has a new review"
        • -
      • All students see the review comments in the PR thread
        • -
      • Student C's review shows in the Reviewers sidebar
        • -
      -

      Step 5: Author Responds and Updates

      -

      Student A (PR author)

      -
        -
      1. Reads the bot feedback and 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

      -
        -
      • Bot re-validates on each new commit
        • -
      • All students see updated activity in the PR
        • -
      • Timeline shows iteration happening
        • -
      -

      Step 6: Merge and Celebration

      -

      When Reviewer Approves

      -
        -
      • Student A merges the PR (button becomes available)
        • -
      • PR closes, shows "merged"
        • -
      -

      Bot Posts Celebration

      -
        -
      • Skills progression bot tracks the merge
        • -
      • Posts achievement comment (badge earned, level up tracking)
        • -
      • Updates student roster progress
        • -
      • Shows milestone celebration if applicable
        • -
      -

      Visibility

      -
        -
      • All students see the merged PR
        • -
      • Achievement comment is public
        • -
      • Progress reflected in Learning Paths documentation
        • -
      -

      What All Students See

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      WhatWhereWho Sees It
      All open PRsPull Requests tabEveryone
      PR description & changesPR pageEveryone
      Bot feedbackPR commentsEveryone
      Peer review commentsPR commentsEveryone
      Reviewer assignmentsPR sidebar "Reviewers"Everyone
      Merge celebrationsPR commentsEveryone
      Your review requestYour notification inboxYou + PR author
      You assigned as reviewerYour review requests filterYou + PR author
      -

      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 facilitator creates study groups, you'll be assigned with 2-3 other students:

      -
        -
      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. Learning Room

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      AspectGitHub Skills (Your Account)Learning Room (Shared)
      RepoYour personal copyOne shared repo
      BotMona (GitHub)Learning Room automation bot
      ReviewerMona (auto)Human peer (auto-assigned)
      VisibilityPrivate (unless you make public)Public to all workshop students
      PaceSelf-directedSynchronized with workshop
      PurposeIndividual skill buildingCollaborative, real-world practice
      FeedbackInstant, next-step onlyBoth bot + human, comprehensive
      CompletionBadge on your profileProgress appears in Learning Paths
      CommunityYou aloneAll students together
      -

      Tips for PR Sharing

      -

      Finding PRs to Review

      -
      -Visual / mouse users - -
        -
      1. Go to github.com/[org]/learning-room
        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 github.com/[org]/learning-room
-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 github.com/[org]/learning-room
-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"
      -
      - - -

      FAQ: PR Sharing in Learning Room

      -

      "Can I see other students' PRs?"

      -

      Yes! All PRs in the shared repo are visible. This is intentional - you learn by seeing how others approach problems.

      -

      "What if I don't agree with my assigned reviewer?"

      -

      You can request additional reviewers manually. The bot's assignment is a convenience, not a mandate. Click "Reviewers" → select someone else.

      -

      "Will my PR get lost with everyone's open at once?"

      -

      No. Each PR has its own conversation thread. The bot update is yours alone. Your reviewer is specifically assigned.

      -

      "Can I comment on someone else's PR?"

      -

      Yes! Anyone can comment on public PRs. If you see something helpful, jump in. This is real open source.

      -

      "What if my reviewer doesn't respond?"

      -

      Mention them directly: "@name, any thoughts on the changes I pushed?" or ask your facilitator for help.

      -

      "Can I work with a friend?"

      -

      Your study group will be created by facilitator, but you likely know your reviewers from the workshop. It's okay to chat between sessions.

      -

      "How long does review take?"

      -

      Typically 15-60 minutes during the workshop. If a reviewer is slow, your facilitator can help or assign someone else.

      -

      "What if bot feedback is wrong?"

      -

      Comment explaining why. Request human review. The bot isn't perfect - that's why you have humans too.

      -

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

      -

      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.

      -

      Next: Working with Issues -Back: Navigating Repositories -Reference: Automation Guide | Available Challenges

      - -
      - - - \ No newline at end of file diff --git a/html/docs/04-the-learning-room.html b/html/docs/04-the-learning-room.html index e575a6e..9bef42b 100644 --- a/html/docs/04-the-learning-room.html +++ b/html/docs/04-the-learning-room.html @@ -60,7 +60,7 @@

      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.

      +

      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 @@ -125,7 +125,7 @@

      5. Find your first challenge issueWhen 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: Your First Issue" authored by aria-bot (or github-actions[bot]).
        3. +
      3. 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]).
      4. Open Challenge 1. Read the issue body -- it tells you what to do, where to find evidence, and how to submit completion.
      @@ -138,8 +138,8 @@

      5. Find your first challenge issue6. 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 3)

      -

      Chapter 3 is a system orientation chapter.

      +

      Workshop Recommendation (Chapter 4)

      +

      Chapter 4 is a system orientation chapter.

      • Challenge count: none
      • Automation check: none
        • @@ -149,7 +149,7 @@

        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 -> PR -> review -> merge.
          3. +
        3. Explain the flow: issue -> branch -> pull request -> review -> merge.
        4. Identify where Aria bot feedback appears on a PR (the Conversation tab).

        Two Tracks That Reinforce Each Other

        @@ -370,25 +370,25 @@

        Tool Cards: Switch to Your Pr

        github.com (browser):

        1. On the repository page, click the branch selector dropdown (shows "main").
          2. -
        2. Type your username to filter, then select username-practice.
          3. +
        3. Type learn to filter, then select learn/<username>.

        github.dev (web editor):

        1. Click the branch name in the bottom-left status bar.
          2. -
        2. Select your username-practice branch from the list.
          3. +
        3. Select your learn/<username> branch from the list.

        VS Code Desktop:

        1. Click the branch name in the bottom-left status bar (or press Ctrl+Shift+P then type Git: Checkout to).
          2. -
        2. Select origin/username-practice from the branch list.
          3. +
        3. Select origin/learn/<username> from the branch list.

        GitHub Desktop:

        1. Click the Current Branch dropdown at the top.
          2. -
        2. Type your username to filter, then select username-practice.
          3. +
        3. Type learn to filter, then select learn/<username>.

        Git CLI (terminal):

        -
        git checkout username-practice
        +
        git checkout learn/<username>

        The Practice Files: What You Will Work On

        @@ -1029,7 +1029,7 @@

        Celebration: You're ContributingThat 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.

        +

        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

        @@ -1039,5 +1039,6 @@

        Celebration: You're ContributingGIT Going with GitHub - A workshop by Community Access

        View on GitHub · community-access.org

        + - \ No newline at end of file + diff --git a/html/docs/04-working-with-issues.html b/html/docs/04-working-with-issues.html deleted file mode 100644 index 20f2420..0000000 --- a/html/docs/04-working-with-issues.html +++ /dev/null @@ -1,1149 +0,0 @@ - - - - - - - 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.

        -
        -

        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 4)

        -

        Chapter 4 is the first issue-based challenge chapter with short, confidence-building tasks.

        -
          -
        • Challenge count: 3
          • -
        • Time per challenge: under 10 minutes
          • -
        • Evidence: issue comments and issue metadata
          • -
        • Pattern: claim -> act -> confirm
          • -
        -

        Chapter 4 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. Add a sub-issue - break a larger issue into smaller, trackable pieces.
          4. -
        -
        -

        Branch guidance for Chapter 4: Chapter 4 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 all three challenges, post a comment on your assigned Chapter 4 challenge issue with links to the issues you created, commented on, and organized. The facilitator reviews your issue activity directly. No pull request is required for Chapter 4.

        -
        -

        Challenge 4.1 Step-by-Step: Create Your First Issue

        -

        Goal: File a new issue in the Learning Room repository with a specific title and a meaningful description.

        -

        Where you are working: the Issues tab of the learning-room repository on GitHub.com.

        -
          -
        1. Open the 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:
            -
          • "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 the learning-room repository on GitHub.com.

        -
          -
        1. Open the Issues tab in the 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. -
        -

        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 the 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

        -

        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")
          • -
        -

        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.

        -

        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.

        -

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

        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

        -

        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.

        -
        - - -

        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.

        -

        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.

        -
        -

        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.

        -

        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.

        -

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

        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.

        -
        -
        -

        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.

        -
        -

        Next: VS Code Accessibility -Back: The Learning Room -Related: Issue Templates Guide | Labels & Milestones | Culture & Etiquette

        - -
        - - - \ No newline at end of file diff --git a/html/docs/05-vscode-accessibility.html b/html/docs/05-vscode-accessibility.html deleted file mode 100644 index 3931a53..0000000 --- a/html/docs/05-vscode-accessibility.html +++ /dev/null @@ -1,2902 +0,0 @@ - - - - - - - VS Code Setup & Accessibility Basics - GIT Going with GitHub - - - - - - - - -
        -

        VS Code Setup & Accessibility Basics

        -
        -

        Listen to Episode 11: VS Code Setup and Accessibility - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

        -
        -

        Your Accessible Development Environment - The Foundation

        -
        -

        Day 2, Block 1 Material

        -

        This chapter is the bridge between GitHub's browser interface (Day 1) and real contribution work in VS Code (Day 2). You will learn how to launch VS Code, sign in to your GitHub account, verify GitHub Copilot is active, configure screen reader mode, navigate every major surface area, and master the accessibility tools that make VS Code one of the most accessible code editors available.

        -

        Prerequisites: Complete Day 1 walkthrough of GitHub's browser interface before working through VS Code material.

        -
        -

        Workshop Recommendation (Chapter 5)

        -

        For this workshop, Chapter 5 is a guided setup chapter with a lightweight completion challenge.

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

        Challenge 5.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 the 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 5: Submit Your Evidence

        -

        Return to GitHub.com, open your assigned Chapter 5 challenge issue, and post a completion comment:

        -
        Chapter 5 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 your Chapter 5 challenge 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.

        -
        -

        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 Keyboard Reference)
          • -
        • 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.)
          • -
        -

        Try It Right Now

        -

        Before reading the rest of this guide:

        -
          -
        1. Open github.com/community-access/learning-room 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

        -
        -

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

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

        -

        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 barInstall the GitHub Copilot extension: 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
          • -
        -
        - - -
        -

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

        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)
        -
        -

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

        16. Accessible Help, Accessible View, and Accessible Diff

        -

        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.

        -
        -

        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.

        -
        -

        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. Git Operations Inside VS Code

        -

        This section previews the key Git operations you will perform inside VS Code. Chapter 6 (Git & Source Control) covers each in full detail with step-by-step walkthroughs. This is your orientation.

        -

        Cloning a Repository

        -

        What it does: Downloads a complete copy of a GitHub repository to your local machine.

        - - - - - - - - - - - - - - - - - - - -
        MethodSteps
        Command PaletteCtrl+Shift+P then type Git: Clone then paste the repository URL then choose a local folder
        TerminalCtrl+` then type git clone https://github.com/owner/repo.git
        Source Control viewIf no folder is open, the Source Control view shows a "Clone Repository" button
        -

        Screen reader tip: After cloning, VS Code asks "Would you like to open the cloned repository?" Press Enter to open it immediately.

        -

        Forking a Repository

        -

        What it does: Creates your own copy of someone else's repository under your GitHub account.

        -

        Forking happens on GitHub.com, not inside VS Code. After forking:

        -
          -
        1. Go to your fork on GitHub.com (github.com/your-username/repo)
          2. -
        2. Clone your fork using the steps above
          3. -
        3. VS Code's Git extension automatically tracks your fork as the origin remote
          4. -
        -

        Pulling Changes

        -

        What it does: Downloads and applies new commits from the remote repository to your local copy.

        - - - - - - - - - - - - - - - - - - - - - - - -
        MethodSteps
        Command PaletteCtrl+Shift+P then type Git: Pull
        Status BarClick the sync icon (circular arrows) in the Status Bar
        TerminalCtrl+` then type git pull
        Source Control viewClick the "..." menu then Pull
        -

        Fetching Changes

        -

        What it does: Checks for new commits on the remote without applying them. Fetch is "look but do not touch."

        - - - - - - - - - - - - - - - -
        MethodSteps
        Command PaletteCtrl+Shift+P then type Git: Fetch
        TerminalCtrl+` then type git fetch
        -

        After fetching, the Status Bar shows if you are behind the remote (e.g., "0 up, 3 down" means 3 commits to pull).

        -

        Pushing Changes

        -

        What it does: Uploads your local commits to the remote repository.

        - - - - - - - - - - - - - - - - - - - - - - - -
        MethodSteps
        Command PaletteCtrl+Shift+P then type Git: Push
        Status BarClick the sync icon
        TerminalCtrl+` then type git push
        Source Control viewClick the "..." menu then Push
        -

        Branching

        -

        What it does: Creates an isolated workspace for your changes without affecting the main branch.

        - - - - - - - - - - - - - - - - - - - -
        MethodSteps
        Command PaletteCtrl+Shift+P then type Git: Create Branch then enter branch name
        Status BarClick the branch name (bottom-left) then select "Create new branch"
        TerminalCtrl+` then type git checkout -b branch-name
        -

        Staging and Committing

        -

        What it does: Staging selects which changes to include. Committing saves them as a permanent snapshot.

        -
          -
        1. Open Source Control (Ctrl+Shift+G)
          2. -
        2. Navigate the changes list with Up/Down Arrow
          3. -
        3. Press Enter on a file to see the diff
          4. -
        4. Press + (or use the stage button) to stage a file
          5. -
        5. Move to the commit message input at the top
          6. -
        6. Type your commit message
          7. -
        7. Press Ctrl+Enter to commit
          8. -
        -

        Learning Cards: Git in VS Code

        -
        -Screen reader users - -
          -
        • Source Control view (Ctrl+Shift+G): Your screen reader announces the number of changed files. Navigate with Up/Down Arrow.
          • -
        • Staging: With a file focused in the changes list, press the stage button (announced as "Stage Changes"). Or open Command Palette and type Git: Stage.
          • -
        • Committing: The commit message input is at the top of the Source Control view. Type your message and press Ctrl+Enter.
          • -
        • Branch switching: The current branch name is in the Status Bar. Click or Enter on it for a branch picker. Your screen reader announces each branch name.
          • -
        • Sync status: The Status Bar shows upload/download arrow counts. Tab to it to hear "0 pending uploads, 2 pending downloads" style announcements.
          • -
        -
        - -
        -Low vision users - -
          -
        • Source Control view uses colored indicators: green + for new files, yellow M for modified, red D for deleted
          • -
        • The diff editor shows added lines with a green background and removed lines with a red background
          • -
        • Use the minimap gutter in the diff view to see the overall pattern of changes
          • -
        • Branch name in the Status Bar is always visible - the font respects your zoom level
          • -
        -
        - -
        -Sighted users - -
          -
        • Click the Source Control icon (branch/fork icon) in the Activity Bar
          • -
        • Click + next to files to stage them, or click the + on the "Changes" header to stage all
          • -
        • Type your commit message in the text box at the top and click the checkmark to commit
          • -
        • The branch name in the bottom-left Status Bar is clickable for branch switching
          • -
        -
        - - -
        -

        Next: Working with Pull Requests -Back: Working with Issues -Related: Git & Source Control in VS Code | GitHub Pull Requests Extension | GitHub Copilot | Screen Reader Cheat Sheet | VS Code Accessibility Reference

        - -
        - - - \ No newline at end of file diff --git a/html/docs/05-working-with-issues.html b/html/docs/05-working-with-issues.html index f50c922..1459676 100644 --- a/html/docs/05-working-with-issues.html +++ b/html/docs/05-working-with-issues.html @@ -60,7 +60,7 @@

        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.

        +

        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 @@ -80,31 +80,28 @@

        Filing, Managing, an

        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 4)

        -

        Chapter 4 is the first issue-based challenge chapter with short, confidence-building tasks.

        +

        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: 3
          • +
        • 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 4 Challenge Set

        +

        Chapter 5 Challenge Set

        1. Create your first issue - file a new issue with a clear title and description.
        2. Comment and @mention - leave a comment on a classmate's issue and tag them with an @mention.
          3. -
        3. Add a sub-issue - break a larger issue into smaller, trackable pieces.
          4. +
        4. 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 4: Chapter 4 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 all three challenges, post a comment on your assigned Chapter 4 challenge issue with links to the issues you created, commented on, and organized. The facilitator reviews your issue activity directly. No pull request is required for Chapter 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 4.1 Step-by-Step: Create Your First Issue

        +

        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.

        -
        -
        -

        🛠️ 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.

        +

        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.

          @@ -1499,7 +1496,7 @@

          Before and After: A Vag

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

        +

        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

        @@ -1578,7 +1575,7 @@

        Day 2 Amplifier -

        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.

      +

      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

      @@ -1588,5 +1585,6 @@

      Day 2 Amplifier -

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/docs/05-working-with-pull-requests.html b/html/docs/05-working-with-pull-requests.html deleted file mode 100644 index 61230d7..0000000 --- a/html/docs/05-working-with-pull-requests.html +++ /dev/null @@ -1,1124 +0,0 @@ - - - - - - - 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.

      -
      -

      Creating, Reviewing, and Merging Pull Requests with a Screen Reader

      -
      -

      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.

      -

      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 5)

      -

      Chapter 5 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 5 Challenge Set

      -
        -
      1. Create one small branch change - edit the file specified in your claimed issue.
        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 5: 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 use your username-practice branch yet. The practice branch is for Chapter 11 and beyond when you work locally with Git and VS Code. For Chapter 5, use a short-lived feature branch as described above.

      -
      -

      Challenge 5.1 Step-by-Step: Create One Small Branch Change

      -

      Goal: Edit the file referenced in the issue you claimed in Chapter 4 (Challenge 4.2).

      -

      Where you are working: the learning-room repository on GitHub.com, using the web editor.

      -

      Before you start: Open the issue you claimed in Chapter 4.2 and note which file needs editing. The issue description tells you the file path and what to fix. The practice files are:

      -

      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 the 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 5.2.

      -

      Challenge 5.2 Step-by-Step: Open a Linked PR

      -

      Goal: Open a pull request 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 5.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 5 challenge issue (not the issue you claimed in Chapter 4, unless they are the same).
          • -
        • If you are also closing the issue you claimed in Chapter 4, add that reference too: Also addresses #YY.
          • -
        -
        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 5.3.

      -

      Challenge 5.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. -
      -

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

      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 use your username-practice branch instead of creating a feature branch. Switch to it with git checkout username-practice (replacing username with your GitHub username, all lowercase).

      -
      -
      - - -

      What Is a Pull Request?

      -

      A pull request (PR) is a proposal to merge changes from one branch into another. When you have:

      -
        -
      • Edited a file directly on GitHub (web editor)
        • -
      • Made changes in your fork
        • -
      • Made changes on a feature branch
        • -
      -

      ...you open a PR to request that those changes be merged into the target branch (usually main).

      -

      A PR shows:

      -
        -
      • What changed - a diff of every file
        • -
      • Why it changed - your PR description
        • -
      • Conversation - comments, reviews, and discussion
        • -
      • Status - automated checks (CI/CD) and review status
        • -
      -
      -

      Learning Room connection: In the Learning Room repository, every hands-on contribution follows this pattern. For example, when you complete Challenge 3 (filling the [TODO] sections in docs/welcome.md), you open a PR that shows your added content as green + lines in the diff, your description explains which TODOs you completed and why, and the validation bot posts automated check results. The scenarios in this chapter use Learning Room files so you can follow along with real content.

      -
      -

      Navigating to Pull Requests

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

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

      -
      - - -

      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]
      -

      Navigating the PR Tab Bar

      -

      The Conversation, Commits, and Files changed tabs are in a “Pull request navigation tabs” landmark.

      -
      -Visual / mouse users - -

      The three tabs - Conversation, Commits, and Files changed - appear just below the PR title. Click the tab you want. The active tab is underlined. The count on Files changed shows how many files were modified.

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

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

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

      Navigating the diff with a screen reader

      -
      -Visual / mouse users - -

      Each file’s diff shows added lines in green and removed lines in red. Scroll the page to read through changes. Unchanged context lines are shown in white/grey. Collapse a file’s diff by clicking the arrow next to its filename heading. Use Ctrl+F (browser Find) to search for specific text within visible diffs.

      -
      - -
      -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. ↓ to move through lines one by one
        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. -
      -
      - -
      -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.

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

      -

      Opening a Pull Request

      -

      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)
      -

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

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

      -

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

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

      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 (06-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
      -

      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.

      -
      -

      Next: Merge Conflicts -Back: Working with Issues -Related: Accessible Code Review | Screen Reader Cheat Sheet | Culture & Etiquette | GitHub Actions

      - -
      - - - \ No newline at end of file diff --git a/html/docs/06-merge-conflicts.html b/html/docs/06-merge-conflicts.html deleted file mode 100644 index 22df405..0000000 --- a/html/docs/06-merge-conflicts.html +++ /dev/null @@ -1,544 +0,0 @@ - - - - - - - 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.

      -
      -

      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 6)

      -

      Chapter 6 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 6 Challenge: Resolve Conflict Markers

      -

      Practice sample: learning-room/docs/samples/chapter-6-conflict-practice-sample.md

      -
        -
      1. Open the assigned merge-conflict practice issue.
        2. -
      2. Edit only the designated practice file/section.
        3. -
      3. Remove conflict markers (<<<<<<<, =======, >>>>>>>) and keep the intended final content.
        4. -
      4. Open PR with Closes #XX and complete with a short issue comment summary.
        5. -
      -

      Expected Outcomes

      -
        -
      • Student can identify conflict markers immediately.
        • -
      • Student can remove markers and keep intended content.
        • -
      • Student can submit a clean, issue-linked PR after resolution.
        • -
      -

      If You Get Stuck

      -
        -
      1. Pause and read marker blocks line by line before editing.
        2. -
      2. Keep one side, or combine both sides when both lines are valid.
        3. -
      3. Delete all marker lines (<<<<<<<, =======, >>>>>>>).
        4. -
      4. Ask facilitator to sanity-check final content before opening PR.
        5. -
      -

      Learning Moment

      -

      Merge conflicts are not failures. They are a normal collaboration checkpoint and a chance to make an intentional content decision.

      -

      Why this chapter is structured this way

      -
        -
      • Real conflicts can be unpredictable for new contributors.
        • -
      • Controlled practice keeps the experience safe and repeatable.
        • -
      • Students still get real issue and PR workflow practice.
        • -
      -

      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.

      -

      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

      -

      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.

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

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

      -

      Resolving Conflicts in VS Code (Day 2)

      -

      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.

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

      -

      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.

      -
      -

      Next: Culture and Etiquette -Back: Working with Pull Requests -Related: Git & Source Control in VS Code

      - -
      - - - \ No newline at end of file diff --git a/html/docs/06-working-with-pull-requests.html b/html/docs/06-working-with-pull-requests.html index 7aefb9b..757a64f 100644 --- a/html/docs/06-working-with-pull-requests.html +++ b/html/docs/06-working-with-pull-requests.html @@ -60,7 +60,7 @@

      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.

      +

      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 @@ -103,7 +103,7 @@

      Chapter 6 Challenge Set

    1. 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).
    2. 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.
      3. -

      Do NOT use your username-practice branch yet. The practice branch is for Chapter 11 and beyond when you work locally with Git and VS Code. For Chapter 6, use a short-lived feature branch as described above.

      +

      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.

      @@ -162,10 +162,7 @@

      Challenge 6.1

      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 effectively audit and approve the code your AI generates tomorrow. Make your Markdown clean and structured — AI agents love reading well-formatted Markdown!

      -
      -
      -

      🛠️ 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 effectively audit and approve the code your AI generates tomorrow. Make your Markdown clean and structured—AI agents love reading well-formatted Markdown! that links to your challenge issue so it closes automatically on merge.

      +

      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").

        @@ -1677,7 +1674,7 @@

        Day 2 Amplifier - Acce

        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.

      +

      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

      @@ -1687,5 +1684,6 @@

      Day 2 Amplifier - Acce

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/docs/07-culture-etiquette.html b/html/docs/07-culture-etiquette.html deleted file mode 100644 index 7b74b85..0000000 --- a/html/docs/07-culture-etiquette.html +++ /dev/null @@ -1,594 +0,0 @@ - - - - - - - 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.

      -
      -

      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 7)

      -

      Chapter 7 is a communication and culture chapter.

      -
        -
      • Challenge count: no bot-graded challenge
        • -
      • Automation check: none
        • -
      • Why: communication quality is important but too subjective for fair automated scoring.
        • -
      -

      Optional Guided Reflection (Issue Comment Evidence)

      -

      Students can post one short comment on their assigned issue:

      -
      Chapter 7 reflection:
-- One respectful review habit I will use:
-- One way I will ask for help clearly:
-- One way I will respond to feedback constructively:
      -

      This keeps learning visible without creating a pass/fail pressure point.

      -

      Expected Outcomes

      -
        -
      • Student can name respectful collaboration behaviors.
        • -
      • Student can prepare a constructive feedback style before review work.
        • -
      • Student feels safer asking for help in public threads.
        • -
      -

      If You Get Stuck

      -
        -
      1. Use one simple sentence per prompt.
        2. -
      2. Focus on one real behavior you can do today.
        3. -
      3. If writing feels hard, draft bullet points first, then post.
        4. -
      4. Ask facilitator for one example response and adapt it.
        5. -
      -

      Learning Moment

      -

      Technical quality and communication quality work together. Respectful, clear communication helps good code get merged faster.

      -

      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" in older projects or enterprise environments. It uses longer-lived branches (develop, release/, hotfix/) and is more complex. For open source contribution - especially at a hackathon - GitHub Flow is what you want. It is what GitHub itself uses and what most modern open source projects follow.

      -

      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.

      -

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

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

      The Footer (Optional)

      -

      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.

      -

      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.

      -

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

      Community Health Files

      -

      A healthy open source project makes these expectations explicit and visible. When you join a project, always check:

      -

      CODE_OF_CONDUCT.md

      -

      Community standards and what behavior is expected. Most projects use the Contributor Covenant. When you see this file, it means:

      -
        -
      • The maintainers take community health seriously
        • -
      • There is a process for reporting violations
        • -
      • You are protected and expected to protect others
        • -
      -

      CONTRIBUTING.md

      -

      Specific instructions for how to contribute to this project:

      -
        -
      • How to set up the development environment
        • -
      • The branch and PR naming conventions
        • -
      • What tests to run before submitting
        • -
      • How to have a change considered
        • -
      -

      Always read CONTRIBUTING.md before opening a PR. Skipping it leads to rejected PRs and wasted effort.

      -

      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

      - -
      - - - \ No newline at end of file diff --git a/html/docs/07-merge-conflicts.html b/html/docs/07-merge-conflicts.html index 14aa2b5..c26b3ee 100644 --- a/html/docs/07-merge-conflicts.html +++ b/html/docs/07-merge-conflicts.html @@ -60,7 +60,7 @@

      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.

      +

      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 @@ -88,7 +88,7 @@

      Chapter 7 Challenge Set

      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.

      +

      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.

      @@ -204,7 +204,7 @@

      Local Git

      Look for the conflict markers:

      <<<<<<< HEAD
 Your version of the content
-=======
+=======
 The incoming version from main
 >>>>>>> main

      Step 3 - Resolve by editing:

      @@ -427,7 +427,7 @@

      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

      @@ -605,9 +605,9 @@

      Resolving Conflicts in VS Code (Da

      VS Code shows conflicts as

      <<<<<<< HEAD (Current Change)
 Your version
-======= original                   -- (3-way merge, if enabled)
+======= original                   -- (3-way merge, if enabled)
 Original version before both edits
-=======
+=======
 Incoming version
 >>>>>>> branch-name (Incoming Change)

      VS Code merge conflict actions

      @@ -793,7 +793,7 @@

      Try It: Read a Conflict (Without Fe 
      The button should have an
 <<<<<<< HEAD
 aria-label="Submit form"
-=======
+=======
 aria-label="Send your response"
 >>>>>>> feature-branch
 attribute for screen readers.
      @@ -819,7 +819,7 @@

      Day 2 Amplifier

      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.

      +

      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

      @@ -829,5 +829,6 @@

      Day 2 Amplifier

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/docs/08-culture-etiquette.html b/html/docs/08-culture-etiquette.html deleted file mode 100644 index f2af4f5..0000000 --- a/html/docs/08-culture-etiquette.html +++ /dev/null @@ -1,724 +0,0 @@ - - - - - - - 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.

      -
      -

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

      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.

      -

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

      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.

      -

      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.

      -

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

      Community Health Files

      -

      A healthy open source project makes these expectations explicit and visible. When you join a project, always check:

      -

      CODE_OF_CONDUCT.md

      -

      Community standards and what behavior is expected. Most projects use the Contributor Covenant. When you see this file, it means:

      -
        -
      • The maintainers take community health seriously
        • -
      • There is a process for reporting violations
        • -
      • You are protected and expected to protect others
        • -
      -

      CONTRIBUTING.md

      -

      Specific instructions for how to contribute to this project:

      -
        -
      • How to set up the development environment
        • -
      • The branch and PR naming conventions
        • -
      • What tests to run before submitting
        • -
      • How to have a change considered
        • -
      -

      Always read CONTRIBUTING.md before opening a PR. Skipping it leads to rejected PRs and wasted effort.

      -

      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

      - -
      - - - \ No newline at end of file diff --git a/html/docs/08-labels-milestones-projects.html b/html/docs/08-labels-milestones-projects.html deleted file mode 100644 index 39a5736..0000000 --- a/html/docs/08-labels-milestones-projects.html +++ /dev/null @@ -1,577 +0,0 @@ - - - - - - - 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.

      -
      -

      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 8)

      -

      Chapter 8 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 8 Guided Challenge: Triage Recommendation Comment

      -
        -
      1. Open your assigned challenge issue.
        2. -
      2. Review issue title, description, and target file.
        3. -
      3. Post a triage recommendation comment using this format:
        4. -
      -
      Chapter 8 triage recommendation:
-- Suggested labels:
-- Suggested milestone:
-- Suggested project board column:
-- One-sentence reason:
      -
        -
      1. If you have write access, apply the recommended labels/milestone directly.
        2. -
      -

      This keeps the task simple and accessible for all students, including those without triage permissions.

      -

      Expected Outcomes

      -
        -
      • Student can recommend labels/milestone/project placement using issue context.
        • -
      • Student understands triage even without maintainer permissions.
        • -
      • Student leaves a clear, reusable triage note for maintainers.
        • -
      -

      If You Get Stuck

      -
        -
      1. Start with one label only (documentation, bug, or accessibility).
        2. -
      2. If milestone is unclear, write none and explain why.
        3. -
      3. If project board is unknown, write needs triage and continue.
        4. -
      4. Ask facilitator to review your one-sentence reason before posting.
        5. -
      -

      Learning Moment

      -

      Triage is about clarity, not authority. Good recommendations reduce maintainer effort and speed up collaboration.

      -

      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

      -

      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.

      -

      Milestones

      -

      What Are Milestones?

      -

      Milestones group issues and PRs toward a shared goal or deadline. Think of a milestone as a sprint, a version release, or an event (like "Hackathon Day 1 Deliverables"). A milestone shows:

      -
        -
      • A title and optional description
        • -
      • An optional due date
        • -
      • A progress bar (percentage of closed issues vs total)
        • -
      -

      Navigating to Milestones

      -

      From Issues tab:

      -
        -
      1. Press K to find the "Milestones" link → Enter
        2. -
      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.

      -

      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.

      -

      GitHub Projects

      -

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

      Practical Organization Strategy for the Hackathon

      -

      Here is a recommended structure for the 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
      -

      Try It: Label and Link

      -

      Time: 2 minutes | What you need: Browser, signed in to GitHub

      -

      Go to the Learning Room repository and do two things:

      -
        -
      1. Add a label to an issue - Open any issue (press G then I, then Enter on an issue title). Press L (in Focus Mode) to open the label picker. Type documentation to filter, then press Enter to apply it. Press Esc to close.
        2. -
      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: Notifications -Back: Culture and Etiquette -Related: Working with Issues | Day 1 Agenda

      - -
      - - - \ No newline at end of file diff --git a/html/docs/08-open-source-culture.html b/html/docs/08-open-source-culture.html index 97f5955..2f05abe 100644 --- a/html/docs/08-open-source-culture.html +++ b/html/docs/08-open-source-culture.html @@ -60,7 +60,7 @@

      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.

      +

      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 @@ -987,7 +987,7 @@

      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.

      +

      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

      @@ -1182,7 +1182,7 @@

      Practical habits

    3. 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.
      4. -

      ➡️ Challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects.

      +

      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

      @@ -1192,5 +1192,6 @@

      Practical habits

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/docs/09-labels-milestones-projects.html b/html/docs/09-labels-milestones-projects.html index a22fc3c..7099645 100644 --- a/html/docs/09-labels-milestones-projects.html +++ b/html/docs/09-labels-milestones-projects.html @@ -60,7 +60,7 @@

      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.

      +

      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 @@ -85,7 +85,7 @@

      Chapter 9 Challenge Set

      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 (like
      eeds-review\ or \ccessibility-check).

      +

      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.

        @@ -750,7 +750,7 @@

        Day 2

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

      @@ -760,5 +760,6 @@

      Day 2

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/docs/09-notifications.html b/html/docs/09-notifications.html deleted file mode 100644 index 135b364..0000000 --- a/html/docs/09-notifications.html +++ /dev/null @@ -1,616 +0,0 @@ - - - - - - - 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.

      -
      -

      Managing Your GitHub Notification Inbox

      -
      -

      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 9)

      -

      For this workshop, Chapter 9 is a guided practice chapter, not a graded automation chapter.

      -
        -
      • No Actions-based validation: Notification settings and inbox actions are account-level behaviors and are not reliably validated by the Learning Room PR bot.
        • -
      • Keep it teachable and simple: Focus on one clear routine students can repeat daily.
        • -
      • Use a consistent pattern: Demonstrate once, then have students complete a short guided walkthrough.
        • -
      -

      Why this chapter has no bot-graded challenge

      -
        -
      • The current validation workflow checks PR and markdown quality, not personal notification preferences.
        • -
      • Notification state changes (watch level, mute, done, saved) are not part of repository file changes.
        • -
      • A forced graded check here would create busywork instead of meaningful skill practice.
        • -
      -

      Guided Walkthrough Challenge (No Automation Check)

      -

      Use this as the chapter exercise. It should take about 5-8 minutes.

      -

      Goal

      -

      Set up a useful notification workflow so students can keep up with reviews, mentions, and assignments without inbox overload.

      -

      Student Steps

      -
        -
      1. Open the workshop repository and set Watch to Participating and @mentions.
        2. -
      2. Open the notifications inbox: https://github.com/notifications.
        3. -
      3. Activate the Review requested filter.
        4. -
      4. Activate the Assigned filter.
        5. -
      5. Open one notification and return to inbox.
        6. -
      6. Perform one inbox action on a non-critical thread:
          -
        • M to mute, or
          • -
        • E to mark done.
          • -
        -
        7. -
      -

      Expected Outcome

      -
        -
      • Student can find review requests quickly.
        • -
      • Student can find assigned work quickly.
        • -
      • Student can reduce noise with one inbox action.
        • -
      -

      Facilitator Verification (Lightweight)

      -

      Ask each student to report the following verbally or in chat:

      -
        -
      1. Their selected watch level.
        2. -
      2. Which two filters they used.
        3. -
      3. Which inbox action they tested (M or E).
        4. -
      -

      This keeps Chapter 9 practical and consistent without adding grading overhead.

      -

      If You Get Stuck

      -
        -
      1. Reload the notifications page and reapply one filter at a time.
        2. -
      2. If inbox is empty, switch to Done and practice action flow there.
        3. -
      3. If shortcuts conflict with screen reader mode, focus the notification row and retry.
        4. -
      4. Ask facilitator to model one inbox action live, then repeat.
        5. -
      -

      Learning Moment

      -

      Notification management protects focus. You can stay responsive without drowning in updates.

      -

      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

      -

      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)
      -

      Navigating the notification list

      -
      -Visual / mouse users - -

      The inbox shows notifications grouped by date (Today, Yesterday, This week, Older). Each row shows the repository, the issue or PR title, the event type, and the time. Click a row to open the notification and go to the issue or PR. Use the left sidebar filters to narrow the view. The Mark all as done button clears the entire inbox at once.

      -
      - -
      -Screen reader users (NVDA / JAWS) - -
        -
      1. D → main content landmark
        2. -
      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

      -

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

      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.

      -

      Recommended Watching Strategy for This Workshop

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

      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.

      -
      -

      Next: Day 2 Agenda -Back: Labels, Milestones, and Projects -Related: Culture & Etiquette | Working with Issues

      - -
      - - - \ No newline at end of file diff --git a/html/docs/10-notifications-and-day-1-close.html b/html/docs/10-notifications-and-day-1-close.html index e3c396a..efc58d8 100644 --- a/html/docs/10-notifications-and-day-1-close.html +++ b/html/docs/10-notifications-and-day-1-close.html @@ -60,7 +60,7 @@

      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.

      +

      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 @@ -921,7 +921,7 @@

      You Already Know More Than You Thi

      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.

      +

      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

      @@ -931,5 +931,6 @@

      You Already Know More Than You Thi

      GIT Going with GitHub - A workshop by Community Access

      View on GitHub · community-access.org

      + - \ No newline at end of file + diff --git a/html/docs/10-notifications.html b/html/docs/10-notifications.html deleted file mode 100644 index a5a0b1f..0000000 --- a/html/docs/10-notifications.html +++ /dev/null @@ -1,625 +0,0 @@ - - - - - - - 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.

      -
      -

      Managing Your GitHub Notification Inbox

      -
      -

      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 the learning-room repository settings.

      -

      Estimated time: 5-8 minutes.

      -
        -
      1. Open the 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. -
      -

      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

      -

      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

      -

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

      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
      -

      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.

      -
      -

      Next: Day 2 Agenda -Back: Labels, Milestones, and Projects -Related: Culture & Etiquette | Working with Issues

      - -
      - - - \ No newline at end of file diff --git a/html/docs/10-vscode-basics.html b/html/docs/10-vscode-basics.html deleted file mode 100644 index 63cdc91..0000000 --- a/html/docs/10-vscode-basics.html +++ /dev/null @@ -1,951 +0,0 @@ - - - - - - - VS Code Setup & Accessibility Basics - GIT Going with GitHub - - - - - - - - -
      -

      VS Code Setup & Accessibility Basics

      -
      -

      Listen to Episode 11: VS Code Setup and Accessibility - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      -
      -

      Your Accessible Development Environment - Part 1: Foundation

      -
      -

      Day 2, Block 1 Material

      -

      This guide covers VS Code fundamentals: why VS Code for open source, accessing VS Code through github.dev (no installation), screen reader configuration, keyboard navigation essentials, and VS Code's three primary accessibility tools (Accessible Help, Accessible View, Accessible Diff).

      -

      Prerequisites: Complete Day 1 walkthrough of GitHub's browser interface before working through VS Code material.

      -
      -

      Workshop Recommendation (Chapter 10)

      -

      For this workshop, Chapter 10 is a guided setup chapter with a lightweight completion challenge.

      -
        -
      • Primary goal: make sure every student can open and navigate VS Code accessibly.
        • -
      • No strict bot grading: setup state is local/account-level and not fully reliable for Actions-based validation.
        • -
      • Issue-linked evidence: students still complete work through their challenge issue workflow.
        • -
      -

      Challenge Type

      -

      Use a guided checklist challenge and record completion in a GitHub issue comment.

      -

      Guided Walkthrough Challenge: VS Code Accessibility Baseline (No Bot Check)

      -

      Use this challenge for Chapter 10. Estimated time: 8-10 minutes.

      -

      Goal

      -

      Confirm students can access VS Code (github.dev or desktop), enable screen reader support, and perform core file navigation.

      -

      Student Steps

      -
        -
      1. Open any repository and launch github.dev with . (period key).
        2. -
      2. Screen reader mode setup:
        3. -
      -
        -
      • Windows (NVDA/JAWS): enable with Shift+Alt+F1.
        • -
      • Mac (VoiceOver): mode is usually already optimized. If needed, open Command Palette and run Toggle Screen Reader Accessibility Mode.
        • -
      -
        -
      1. Open Explorer with Ctrl+Shift+E (Mac: Cmd+Shift+E).
        2. -
      2. Open README.md from the file tree.
        3. -
      3. Open outline/symbols with Ctrl+Shift+O (Mac: Cmd+Shift+O).
        4. -
      4. Open Command Palette with Ctrl+Shift+P (Mac: Cmd+Shift+P) and run any command.
        5. -
      5. Return to your assigned challenge issue and post a completion comment using this format:
        6. -
      -
      Chapter 10 complete:
-- Opened github.dev: yes
-- Screen reader mode enabled: yes
-- Opened file in Explorer: yes
-- Opened outline/symbols: yes
-- Opened Command Palette: yes
      -

      Facilitator Verification (Lightweight)

      -
        -
      • Confirm the completion comment exists on the student's assigned issue.
        • -
      • If a student is blocked, ask for the exact step and shortcut where they got stuck.
        • -
      • Treat this as readiness verification for later PR-focused chapters, not pass/fail grading.
        • -
      -

      Expected Outcomes

      -
        -
      • Student can launch and navigate github.dev or desktop VS Code.
        • -
      • Student can enable screen reader mode and open core navigation surfaces.
        • -
      • Student is ready for VS Code-based contribution chapters.
        • -
      -

      If You Get Stuck

      -
        -
      1. Confirm you are in a repository page before pressing ..
        2. -
      2. Retry screen reader mode toggle once, then verify in settings.
        3. -
      3. On Mac with VoiceOver, run Toggle Screen Reader Accessibility Mode from Command Palette if navigation is inconsistent.
        4. -
      4. Use Command Palette to run commands when shortcut memory is hard.
        5. -
      5. Ask facilitator for a side-by-side demo and repeat the same 5 steps.
        6. -
      -

      Learning Moment

      -

      Tool setup is part of contribution skill. A stable, accessible editor reduces stress and increases contribution quality.

      -

      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. Essential Keyboard Navigation and Find/Filter
        5. -
      5. Accessible Help, Accessible View, and Accessible Diff
        6. -
      -

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

      -

      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're 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's 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 → 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 Keyboard Reference)
      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 - can't run shell commands, npm, git CLI
      No GitHub Copilot - Copilot requires the desktop app or a Codespace
      No Accessibility Agents 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's the bridge. You spend Day 1 in the GitHub browser interface. You'll 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're on a machine where you can't install software
        • -
      • You want to browse code with VS Code navigation (symbols, search, split view)
        • -
      • You're 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 agents
        • -
      • You're 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
        • -
      -

      Navigation

      -
        -
      • Use Ctrl+Shift+E to open the Explorer (file tree)
        • -
      • Use Up/Down Arrow to navigate files
        • -
      • Press Enter on a file to open it in the editor
        • -
      • The editor behaves like a standard text area - your screen reader's reading commands work normally
        • -
      -

      NVDA/JAWS users

      -
        -
      • You remain in Browse/Virtual mode for the overall interface
        • -
      • When focus enters the editor text area, you're 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.)
        • -
      -

      Try It Right Now

      -

      Before reading the rest of this guide:

      -
        -
      1. Open github.com/community-access/accessibility-agents 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 and agents added.

      -

      3. Screen Reader Mode in VS Code

      -
      -

      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) → type "screen reader" → 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+,) → search for accessibility support → 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 → Preferences → Settings → 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 → Shift+Alt+F1 (Mac: Shift+Option+F1) to confirm screen reader mode
        2. -
      2. In VoiceOver Utility: Verbosity → 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. -
      -

      4. Essential Keyboard Navigation and Find/Filter

      -

      Panels and Areas

      -
      -

      Mac users: Substitute Cmd for Ctrl and Option for Alt in all shortcuts below.

      -

      For example: Ctrl+Shift+E → Cmd+Shift+E, Ctrl+Backtick → Ctrl+Backtick (same on Mac), Ctrl+Shift+P → Cmd+Shift+P.

      -
      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      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+BacktickTerminal 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 → type line number
      Go to line and columnCtrl+G → type N:C (e.g., 10:5 for line 10, column 5)
      Go to character offsetCtrl+G → type ::N (e.g., ::599 for the 599th character in the file)
      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 → 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+; → Arrow keys to navigate path segments
      -

      Rich Find and Filtering Experiences

      -

      VS Code's Find and Search tools go far beyond a simple text match. Every option below is keyboard-accessible, and all toggles are announced as checkboxes by screen readers.

      -

      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 → type glob patterns
      Exclude files filterTab to "files to exclude" field → type glob patterns
      Collapse all resultsCtrl+Shift+J
      Open a resultNavigate the result tree with Up/Down Arrow → Enter to open
      -
      Glob pattern examples for this workshop
      -
      docs/*.md          → all Markdown files in the docs folder
-*.agent.md         → all Accessibility Agents agent definition files
-.github/**         → everything inside the .github folder
-!node_modules/**   → exclude the node_modules folder from results
      -

      Finding Settings (Ctrl+,)

      -

      The Settings editor has built-in search that filters by keyword as you type. Additional filter options:

      - - - - - - - - - - - - - - - - - - - - - - - -
      FilterWhat It Shows
      @modifiedOnly settings you have changed from their defaults
      @tag:accessibilityAll accessibility-related settings
      @tag:advancedAdvanced settings - useful for finding less common configuration options
      @tag:experimentalExperimental features not enabled by default
      -

      Type any of these directly in the Settings search box (Ctrl+,).

      -

      Terminal IntelliSense (Ctrl+Space)

      -

      The VS Code integrated terminal now offers completions for shell commands, file paths, and arguments. Press Ctrl+Space while typing in the terminal to trigger the completion list. Navigate suggestions with Up/Down Arrow, accept with Tab or Enter.

      -

      Enable with: Settings (Ctrl+,) → search terminal.integrated.suggest.enabled → set to on.

      -

      Screen reader note: Terminal IntelliSense completions are announced via ARIA live regions. The completion popup behaves the same as editor IntelliSense.

      -

      Type-to-Filter in Tree Views

      -

      In the Explorer file tree and the Source Control changes list, you can type characters to narrow the visible items - no scrolling required:

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

      This is one of VS Code's most useful keyboard affordances for large repositories with many files.

      -

      Go to Symbol with Inline Filtering (Ctrl+Shift+O)

      -

      In any Markdown file, Ctrl+Shift+O opens a symbol picker populated by every heading in the document. Type to narrow the list:

      -
        -
      • Ctrl+Shift+O → symbol picker opens
        • -
      • Type ## Day → results narrow to all H2 headings containing "Day"
        • -
      • Up/Down Arrow → move through results
        • -
      • Enter → jump to the selected heading
        • -
      -

      For navigating accessibility-agents's longer reference documents, this is faster than heading-by-heading screen reader navigation.

      -

      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)
      -

      5. Accessible Help, Accessible View, and Accessible Diff

      -

      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.

      -

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

      -

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

      Recommended workflow for Copilot Chat

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

      Recommended workflow for hover documentation

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

      5.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 → 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 → F7 to enter the first hunk → navigate each change → F7 for next hunk → 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 → navigate to the changed file → 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.

      -

      Accessibility Signals and Audio Cues

      -

      VS Code can communicate editor state through accessibility signals - sounds that announce when you move past line breaks, reach the end of a file, land on an error, or complete a task. This is particularly useful for screen reader users who benefit from non-verbal state confirmation.

      -

      Enabling Accessibility Signals

      -

      Open Settings (Ctrl+,) → search "accessibility signals":

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      SettingRecommended ValueWhat It Does
      editor.accessibilitySupportonFull screen reader mode
      accessibility.signals.lineHasErroronSound when cursor is on a line with an error
      accessibility.signals.lineHasWarningautoSound on warnings (lower pitch than errors)
      accessibility.signals.taskCompletedonSound when a terminal command completes
      accessibility.signals.taskFailedonDifferent sound when a command fails
      accessibility.signals.diffLineInsertedonSound when navigating over added lines in a diff
      accessibility.signals.diffLineDeletedonSound when navigating over deleted lines in a diff
      accessibility.signals.chatResponsePendingonSound while Copilot is generating
      accessibility.signals.chatResponseReceivedonSound when Copilot response is complete
      -

      Recommended Profile for Screen Reader Users

      -

      Add this to your VS Code settings.json (Command Palette → "Open User Settings JSON"):

      -
      {
-  "editor.accessibilitySupport": "on",
-  "accessibility.signals.lineHasError": "on",
-  "accessibility.signals.taskCompleted": "on",
-  "accessibility.signals.taskFailed": "on",
-  "accessibility.signals.chatResponseReceived": "on",
-  "accessibility.signals.diffLineInserted": "on",
-  "accessibility.signals.diffLineDeleted": "on",
-  "editor.minimap.enabled": false,
-  "editor.renderWhitespace": "none",
-  "editor.wordWrap": "on"
-}
      -

      Note: minimap.enabled: false removes the visual minimap that adds no value for screen reader users and can cause some accessibility tools to announce additional regions.

      -

      Next: Git & Source Control in VS Code
      Back: Day 2 Agenda
      Related: GitHub Pull Requests Extension | GitHub Copilot

      - -
      - - - \ No newline at end of file diff --git a/html/docs/11-git-source-control.html b/html/docs/11-git-source-control.html deleted file mode 100644 index 55e7819..0000000 --- a/html/docs/11-git-source-control.html +++ /dev/null @@ -1,1964 +0,0 @@ - - - - - - - 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.

      -
      -

      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 11)

      -

      Chapter 11 is the first local Git workflow chapter with hands-on repository management.

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

      Chapter 11 Challenge Set

      -
        -
      1. Clone the sci-fi themes repository - clone vscode-sci-fi-themes to your local machine using VS Code.
        2. -
      2. Create a branch and make one commit - create a named branch, edit a theme 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 that references your challenge issue.
        4. -
      -

      Challenge 11.1 Step-by-Step: Clone the Sci-Fi Themes Repository

      -

      Goal: Get a local copy of the vscode-sci-fi-themes repository on your machine using VS Code.

      -

      Where you are working: VS Code desktop (or github.dev if you cannot install desktop VS Code).

      -

      This repo contains custom Copilot Chat loading phrases from three sci-fi universes (Star Trek, Hitchhiker's Guide, and Star Wars). Cloning it gives you a fun, real codebase to explore while learning Git.

      -
        -
      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: https://github.com/Community-Access/vscode-sci-fi-themes.git
        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, CLONE-THIS-REPO.md, and a themes/ folder containing three JSON files.
        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: The vscode-sci-fi-themes folder is open in VS Code and you can see the themes/ folder with its three JSON files (star-trek, hitchhikers, star-wars) in the Explorer panel.

      -
      -

      After cloning: check what branches exist. A fresh clone only checks out the default branch (usually main), but the remote may have other branches. 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/chapter11/example-branch
      -

      The * marks your current branch. Lines starting with remotes/origin/ are branches on GitHub that you can check out locally with git checkout branch-name or git switch branch-name. This is especially useful in the Learning Room, where facilitators may have pre-created branches for challenges.

      -
      -

      Challenge 11.2 Step-by-Step: Create a Branch and Commit

      -

      Goal: Create a properly named branch, edit a theme file, stage the change, and commit with a clear message.

      -

      Where you are working: VS Code with the cloned vscode-sci-fi-themes repository open.

      -
        -
      1. Open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P).
        2. -
      2. Type git create branch and select Git: Create Branch...
        3. -
      3. VS Code asks for a branch name. Type: chapter11/yourname-issueXX (replace yourname with your GitHub username and XX with your Chapter 11.2 challenge issue number). Press Enter.
        4. -
      4. The status bar at the bottom of VS Code now shows your new branch name instead of main. Your screen reader announces the branch name when you focus the status bar.
        5. -
      5. Open the Explorer (Ctrl+Shift+E) and navigate to the themes/ folder. Open any theme file (for example, star-trek-settings.json).
        6. -
      6. Make one small, meaningful edit. For example, add a new thinking phrase to the array, fix a typo, or improve a description. Save the file with Ctrl+S (Mac: Cmd+S).
        7. -
      7. 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."
        8. -
      8. 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."
        9. -
      9. Move focus to the Message input box at the top of the Source Control panel. Type a clear commit message, for example: feat: add new thinking phrase to Star Trek theme
        10. -
      10. Press Ctrl+Enter (Mac: Cmd+Enter) to commit. The staged changes disappear, which means your commit succeeded.
        11. -
      -

      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.

      -

      Challenge 11.3 Step-by-Step: Push and Open a Linked PR

      -

      Goal: Push your branch to GitHub and open a PR 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 https://github.com/Community-Access/vscode-sci-fi-themes.
        5. -
      5. GitHub usually shows a yellow banner: "yourname recently pushed to chapter11/yourname-issueXX." 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 chapter11/yourname-issueXX branch.
        7. -
      7. In the PR title, write a descriptive title (for example: "Add new thinking phrase to Star Trek theme").
        8. -
      8. In the PR description, type Closes Community-Access/learning-room#XX (replace XX with your Chapter 11.3 challenge issue number). This cross-repo reference tells GitHub to automatically close that issue in the learning-room when this PR is merged.
        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.

      -

      Cross-repo linking: Because your challenge issue lives in learning-room but your PR is in vscode-sci-fi-themes, you use the full format Closes Community-Access/learning-room#XX instead of just Closes #XX. GitHub resolves cross-repo references automatically.

      -

      You are done when: Your PR appears on the Pull requests tab of vscode-sci-fi-themes, shows your branch name, and the description contains the cross-repo reference to your challenge issue.

      -

      Completing Chapter 11: Submit Your Evidence

      -

      Open your assigned Chapter 11.3 challenge issue in the learning-room repo and post a completion comment:

      -
      Chapter 11 completed:
-- Repository cloned: vscode-sci-fi-themes
-- Branch name: chapter11/[yourname]-[issueXX]
-- Commit message: [your commit message]
-- PR number: Community-Access/vscode-sci-fi-themes#[your PR number]
-- PR links to issue: yes (Closes Community-Access/learning-room#XX in description)
      -

      Close your Chapter 11 challenge issues (11.1, 11.2, 11.3) when your PR is open.

      -

      Expected Outcomes

      -
        -
      • Student can clone a repository using VS Code Command Palette.
        • -
      • Student can create 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 cross-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. Cross-repo link not working? Make sure the format is exactly Closes Community-Access/learning-room#XX with no extra spaces. The org/repo prefix is required when linking across repositories.
        7. -
      7. Ask facilitator to verify your clone location, branch name, and help with one push.
        8. -
      -
      -

      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

      -

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

      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

      -

      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.

      -

      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.

      -

      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: GitHub Pull Requests Extension
      Back: VS Code Setup & Accessibility Basics
      Related: Merge Conflicts | Culture & Etiquette

      - -
      - - - \ No newline at end of file diff --git a/html/docs/11-vscode-interface.html b/html/docs/11-vscode-interface.html index 4bea719..a0f2bcc 100644 --- a/html/docs/11-vscode-interface.html +++ b/html/docs/11-vscode-interface.html @@ -60,7 +60,7 @@

      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.

      +

      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 @@ -73,19 +73,19 @@

      Your Accessibl

      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 5)

      -

      For this workshop, Chapter 5 is a guided setup chapter with a lightweight completion challenge.

      +

      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 5 Challenge Set

      +

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

      Challenge 5.1 Step-by-Step: VS Code Accessibility Baseline

      +

      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.

      @@ -105,9 +105,9 @@

      Challenge 5.1
    4. 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 5: Submit Your Evidence

    -

    Return to GitHub.com, open your assigned Chapter 5 challenge issue, and post a completion comment:

    -
    Chapter 5 completed:
+
    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
@@ -115,7 +115,7 @@ 
    Completing Chapter 5: Submit
 - 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 your Chapter 5 challenge issue when done.
    
+
    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.
      • 
@@ -1395,5 +1395,6 @@ 
      Learning Cards: Keyboard Short
     
      GIT Going with GitHub - A workshop by Community Access
      
     
      View on GitHub · community-access.org
      
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/12-github-pull-requests-extension.html b/html/docs/12-github-pull-requests-extension.html
deleted file mode 100644
index 4aa6825..0000000
--- a/html/docs/12-github-pull-requests-extension.html
+++ /dev/null
@@ -1,878 +0,0 @@
-
-
-
-  
-  
-  
-  GitHub Pull Requests Extension - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
      
-    
      GitHub Pull Requests Extension
      
-
      
-
      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 12)
      
-
      Chapter 12 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 12 Challenge 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. 
-
      
-
      Challenge 12.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 the 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 the learning-room repository.
      
-
      Challenge 12.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 11).
        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 12: Submit Your Evidence
      
-
      Open your assigned Chapter 12 challenge issue and post a completion comment:
      
-
      Chapter 12 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. 
-
      
-
      
-
      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
        • 
-
      
-
      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. 
-
      
-
      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/05-vscode-accessibility.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).
      
-
      5. Creating a Pull Request from VS Code
      
-
      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
      
-
      
-
-
-
      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.
      
-
      
-
-
-
      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. 
-
      
-
      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
      
-
-  
      
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/12-vscode-accessibility.html b/html/docs/12-vscode-accessibility.html
index eed2a21..58a4c79 100644
--- a/html/docs/12-vscode-accessibility.html
+++ b/html/docs/12-vscode-accessibility.html
@@ -60,7 +60,7 @@
   
      
     
      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.
      
+
      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
@@ -1927,5 +1927,6 @@ 
      If You Get Stuck
      
     
      GIT Going with GitHub - A workshop by Community Access
      
     
      View on GitHub · community-access.org
      
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/13-github-copilot.html b/html/docs/13-github-copilot.html
deleted file mode 100644
index ed144e0..0000000
--- a/html/docs/13-github-copilot.html
+++ /dev/null
@@ -1,1538 +0,0 @@
-
-
-
-  
-  
-  
-  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.
      
-
      
-
      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 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.
      
-
      
-
      Chapter 13 introduces GitHub Copilot for AI-assisted documentation and writing.
      
-
        
-
      • 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
        • 
-
      
-
      Chapter 13 Challenge Set
      
-
        
-
      1. Install GitHub Copilot and sign in - add the Copilot Chat extension and authenticate.
        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: Install and Sign In
      
-
      Goal: Install the GitHub Copilot Chat extension and verify it responds to prompts.
      
-
      Where you are working: VS Code desktop with the learning-room repository open.
      
-
      Estimated time: 3-5 minutes.
      
-
        
-
      1. Open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X).
        2. 
-
      2. Type GitHub Copilot in the search box and press Enter.
        3. 
-
      3. Find GitHub Copilot (publisher: GitHub) in the results. Activate Install.
        4. 
-
      4. VS Code may also install GitHub Copilot Chat automatically. If not, search for it separately and install it.
        5. 
-
      5. After installation, VS Code prompts you to sign in. 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 Chapter 13: Submit Your Evidence
      
-
      Open your assigned Chapter 13 challenge 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 Chapter 13 challenge issues 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. 
-
      
-
      
-
      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 Free tier: Available for all GitHub users. Provides access to inline suggestions and Copilot Chat with usage limits. No payment required for this workshop.
      
-
      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)
        • 
-
      
-
      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+/
      
-
      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"
        • 
-
      
-
      
-
-
-
      4. GitHub Copilot Chat - Conversational Assistance
      
-
      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.2 (1× premium requests)
        • 
-
      • Running Agent mode? GPT-5.1-Codex-Max or GPT-5.2-Codex are optimized for autonomous tasks
        • 
-
      • High cost to avoid unless needed: Claude Opus 4.6 (3× cost) - powerful but reserve for the most demanding work
        • 
-
      
-
      For the complete model comparison, strengths, weaknesses, and plan availability, see Appendix X: GitHub Copilot AI Models 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 @05-vscode-accessibility.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.
      
-
      
-
      5. Copilot Edits — Making Multi-File Changes
      
-
      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
        • 
-
      
-
      
-
      6. Agent Mode — Let Copilot Drive
      
-
      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
      
-
      
-
      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 ✨ sparkle / 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)✅✅
      Repository / issue / PR context✅ Built-in✅ Via @github
      Inline code suggestions❌✅
      Copilot Edits (multi-file)❌✅
      Agent mode❌✅
      PR description generation✅❌
      Code review comments✅ (for maintainers)❌
      No install required✅Requires extension
      
-
      
-
      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.
      
-
      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.
      
-
      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:
      
-
-
      
-
      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.
      
-
      
-
      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: Accessible Code Review
-Back: GitHub Pull Requests Extension
-Related: VS Code Setup & Accessibility Basics | Appendix M: VS Code Accessibility Reference | Appendix W: GitHub Copilot Reference | Appendix X: AI Models Reference
      
-
-  
      
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/13-how-git-works.html b/html/docs/13-how-git-works.html
index 33a82cf..863c784 100644
--- a/html/docs/13-how-git-works.html
+++ b/html/docs/13-how-git-works.html
@@ -400,7 +400,7 @@ 
      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
      
 
@@ -598,5 +598,6 @@ 
      10. If You Get Stuck
      GIT Going with GitHub - A workshop by Community Access
      View on GitHub · community-access.org
      
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/14-accessible-code-review.html b/html/docs/14-accessible-code-review.html
deleted file mode 100644
index 1a315e7..0000000
--- a/html/docs/14-accessible-code-review.html
+++ /dev/null
@@ -1,1604 +0,0 @@
-
-
-
-  
-  
-  
-  Accessible Code Review - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
      
-    
      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 14)
      
-
      Chapter 14 is the code review chapter focused on practicing constructive feedback.
      
-
        
-
      • 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
        • 
-
      
-
      Chapter 14 Challenge 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. 
-
      
-
      Challenge 14.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 the 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 11). 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 12). 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.
      
-
      Challenge 14.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 Chapter 14: Submit Your Evidence
      
-
      Open your assigned Chapter 14 challenge issue and post a completion comment:
      
-
      Chapter 14 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 Chapter 14 challenge issues 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. 
-
      
-
      
-
      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
      
-
      
-
-
-
      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:
      
-
      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 16):
      
-
        
-
      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 16):
      
-
      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: Issue Templates
-Back: GitHub Copilot
-Related: Screen Reader Cheat Sheet | Merge Conflicts | Git & Source Control in VS Code
      
-
-  
      
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/14-git-in-practice.html b/html/docs/14-git-in-practice.html
index c71ada7..48ef1c9 100644
--- a/html/docs/14-git-in-practice.html
+++ b/html/docs/14-git-in-practice.html
@@ -60,7 +60,7 @@
   
      
     
      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.
      
+
      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
@@ -73,21 +73,21 @@ 
      Managing Reposito
 
      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 11)
      
-
      Chapter 11 is the first local Git workflow chapter with hands-on repository management.
      
+
      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
        • 
 
      
-
      Chapter 11 Challenge Set
      
+
      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 Chapter 11 challenge issue.
        4. 
+
      4. 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.
        5. 
 
      
-
      Challenge 11.1 Step-by-Step: Clone Your Learning Room Repository
      
+
      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.
      
@@ -115,7 +115,7 @@ 
      Challeng
   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.

    -

    Challenge 11.2 Step-by-Step: Create a Branch and Commit

    +

    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.

    @@ -125,7 +125,7 @@

    Challenge 11.2 St
  • Open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P).
  • 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>.
  • 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.
    • -
  • Open the Explorer (Ctrl+Shift+E) and navigate to the docs/ folder. Open any file mentioned in your Chapter 11 challenge issue (for example, docs/welcome.md).
    • +
  • 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).
  • 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).
  • 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."
  • 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."
    • @@ -134,7 +134,7 @@

    Challenge 11.2 St

    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.

    -

    Challenge 11.3 Step-by-Step: Push and Open a Linked PR

    +

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

      @@ -145,21 +145,21 @@

      Challenge 11.3 Ste
    1. GitHub usually shows a yellow banner: "yourname recently pushed to learn/yourname." Activate the Compare & pull request button in that banner.
    2. 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.
    3. In the PR title, write a descriptive title (for example: "docs: improve welcome.md introduction").
      4. -
    4. In the PR description, type Closes #XX (replace XX with your Chapter 11 challenge issue number). Because the issue lives in the same repo as the PR, you only need the short #XX form.
      5. +
    5. 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.
    6. Activate the Create pull request button.

    Screen reader tip: The "Compare & pull request" banner is a standard link element near the top of the repository page. If your screen reader does not find it, use the heading navigation to jump to the Pull Requests tab instead.

    Same-repo linking: Because your challenge issue and your PR live in the same repository, the short form Closes #XX is enough -- GitHub automatically resolves the issue number to a closure link. (If you ever open a PR in a different repo, you would use the full Closes <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 Chapter 11: Submit Your Evidence

    -

    Open your assigned Chapter 11.3 challenge issue in your Learning Room repo and post a completion comment:

    -
    Chapter 11 completed:
+
    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 Chapter 11 challenge issues (11.1, 11.2, 11.3) when your PR is open.
    
+
    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.
      • 
@@ -1603,7 +1603,7 @@ 
      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):
      
@@ -2084,5 +2084,6 @@ 
      Try It: Clone, Branch, Commit
      
     
      GIT Going with GitHub - A workshop by Community Access
      
     
      View on GitHub · community-access.org
      
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/15-code-review.html b/html/docs/15-code-review.html
index 97aee9c..49fd2c4 100644
--- a/html/docs/15-code-review.html
+++ b/html/docs/15-code-review.html
@@ -65,7 +65,7 @@ 
      Code Review: PRs, Diffs
 
 
      
 
      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 (to be written in Phase 3) adds the reviewer's judgment framework.
      
+
      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
      
@@ -73,7 +73,7 @@ 
      Part 1: The GitHub Pull Reque
 
      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.
      
+
      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
      
 
      
@@ -82,20 +82,20 @@ 
      Managing Pull Requests from VS Code
 
      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 12)
      
-
      Chapter 12 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code.
      
+
      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 12 Challenge Set
      
+
      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. 
 
      
-
      Challenge 12.1 Step-by-Step: Install the Extension
      
+
      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.
      
@@ -111,14 +111,14 @@ 
      Challenge 12.1 Step-by
 
 
      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.
      
-
      Challenge 12.2 Step-by-Step: Check Out a PR and Post a Comment
      
+
      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 11).
        4. 
+
      4. Navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14).
        5. 
 
      5. 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.
        6. 
 
      6. Open the Command Palette again and run GitHub Pull Requests: Open Changed Files. This shows the list of files the PR changed.
        7. 
 
      7. Open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right.
        8. 
@@ -130,9 +130,9 @@ 
        Challenge
 
        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 12: Submit Your Evidence
        
-
        Open your assigned Chapter 12 challenge issue and post a completion comment:
        
-
        Chapter 12 completed:
+
        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]
@@ -1068,37 +1068,37 @@ 
        Try It: Review a PR from VS Code
        
 
        
 
        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.
        
+
        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 14)
        
-
        Chapter 14 is the code review chapter focused on practicing constructive feedback.
        
+
        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
          • 
 
        
-
        Chapter 14 Challenge Set
        
+
        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. 
 
        
-
        Challenge 14.1 Step-by-Step: Review a PR and Leave Inline Comments
        
+
        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 11). Open it.
          3. 
+
        3. Find a classmate's open PR (from Chapter 6, 7, or 14). Open it.
          4. 
 
        4. Activate the Files changed tab. This shows the diff - lines added in green, lines removed in red.
          5. 
 
        5. 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 12). Use F7/Shift+F7 to move between changes.
            • 
+
          • In VS Code: Press F7 to open the Accessible Diff Viewer (see Chapter 15, Part 1). Use F7/Shift+F7 to move between changes.
            • 
 
          
 
          6. 
 
        6. Read through the changes carefully. Look for:
            
@@ -1125,7 +1125,7 @@ 
            Challe
 
        
 
        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.
        
-
        Challenge 14.2 Step-by-Step: Submit a Formal Review Verdict
        
+
        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).
        
 
          
@@ -1147,14 +1147,14 @@ 
          Challenge 14.
 
        1. Activate Submit review.
          2. 
 
        
 
        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 Chapter 14: Submit Your Evidence
        
-
        Open your assigned Chapter 14 challenge issue and post a completion comment:
        
-
        Chapter 14 completed:
+
        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 Chapter 14 challenge issues when done.
        
+
        Close your Challenge 12 issue when done.
        
 
        Expected Outcomes
        
 
          
 
        • Student can navigate PR diffs with a screen reader.
          • 
@@ -1188,10 +1188,10 @@ 
          Learning Pattern Used in This Cha
 
          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)
            • 
+
          •  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
          
@@ -2026,8 +2026,8 @@ 
          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 
+
            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. 
@@ -2067,8 +2067,8 @@ 
            What to do
            
 
          4. Find the line in the diff with the problematic link
            5. 
 
          5. Hover over the line number and click to open a comment box (or press C)
            6. 
 
          6. Type:
            
-
            nit: Link text "click here" is not descriptive. Screen reader users 
-who list links won't know the context. Suggest: "Read the accessibility 
+
            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.
            
 
            7. 
 
          7. Click Comment or press Ctrl+Enter
            8. 
@@ -2278,9 +2278,9 @@ 
            Step 8: Write Your Accessible
 
            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 
+
              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. 
@@ -2302,14 +2302,14 @@ 
              What to do
              
 
            3. Go to GitHub in your browser and open the same PR
              4. 
 
            4. Scroll to the bottom and leave a comment in the Conversation tab:
              5. 
 
            
-
            I've now reviewed this PR in both the browser and VS Code. Here's 
+
            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 
+**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 
+**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]
@@ -2372,33 +2372,33 @@ 
            Question 1: Environment Preference
            
 
            Question 2: Strengths of Each Environment
            
-
            Browser made this easier: [One specific task, e.g., "Finding the PR URL"] 
+
            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"] 
+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, 
+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 
+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 
+
            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. 
+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, 
+After reviewing this PR using both the browser and VS Code environments,
 here's what I found:
 
 ### Environment Preference
@@ -2419,7 +2419,7 @@ 
            Full template to copy into t
 
 ### Real-World Impact
 
-The heading hierarchy skip in the published document matters because: 
+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
            
@@ -2505,13 +2505,13 @@ 
            Example Exchange
            
   "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. 
+  "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 
+  - 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)
            
 
              
@@ -2609,15 +2609,15 @@ 
              Writing Constructive Feedback
              
 
              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
                • 
+
              •  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.
              
@@ -2710,7 +2710,7 @@ 
              A Real Example: The Flow
              
 
            1. Write comment explaining why it matters
              2. 
 
            2. Submit your verdict
              3. 
 
        
-
        Agent-Assisted Review (what you'll do in Chapter 16):
        
+
        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. 
@@ -2721,7 +2721,7 @@ 
          A Real Example: The Flow
          
 
          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 16):
          
+
          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)
            • 
@@ -2740,5 +2740,6 @@ 
            A Real Example: The Flow
            
     
            GIT Going with GitHub - A workshop by Community Access
            
     
            View on GitHub · community-access.org
            
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/15-issue-templates.html b/html/docs/15-issue-templates.html
deleted file mode 100644
index af735c9..0000000
--- a/html/docs/15-issue-templates.html
+++ /dev/null
@@ -1,2182 +0,0 @@
-
-
-
-  
-  
-  
-  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.
            
-
            
-
            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 13: 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 15
              • 
-
            
-
            Day 2 Amplifier: In Chapter 16 (Accessibility Agents), you'll use @template-builder to automate template creation. Complete this chapter first, then come back to Chapter 16.
            
-
            Estimated time for this chapter: 2-2.5 hours (including exercises and YAML troubleshooting time)
            
-
            Workshop Recommendation (Chapter 15)
            
-
            Chapter 15 is a template design and implementation chapter focused on structuring contributions with a concrete, familiar example.
            
-
              
-
            • 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
              • 
-
            
-
            Chapter 15 Challenge 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 15.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 15.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 15.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 15.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 Chapter 15: Submit Your Evidence
            
-
            Open your assigned Chapter 15 challenge issue and post a completion comment:
            
-
            Chapter 15 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 Chapter 15 challenge issues 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/chapter-15-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. 
-
            
-
            
-
            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.
            
-
            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"
              • 
-
            
-
            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
            
-
            Choosing Between Markdown and YAML Templates
            
-
            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
              • 
-
            
-
            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
              • 
-
            
-
            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.
            
-
            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.
            
-
            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 15, 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
            
-
            Prerequisite: Complete Exercise D above. You should understand what fields you want to ask for and why.
            
-
            Chapter 16 Exercise (Accessibility Agents): Use @template-builder to generate a template for a real project, then customize or extend it. See Accessibility Agents: Contributing to the Ecosystem.
            
-
            After the Workshop: Any repetitive GitHub task - templates, checklists, workflows - can be built with Accessibility Agents. The Template Builder shows how.
            
-
            Next: Accessibility Agents
-Back: Accessible Code Review
-Related: Working with Issues | Culture & Etiquette | Accessibility Agents
            
-
-  
            
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/16-accessibility-agents.html b/html/docs/16-accessibility-agents.html
deleted file mode 100644
index f5ab309..0000000
--- a/html/docs/16-accessibility-agents.html
+++ /dev/null
@@ -1,2245 +0,0 @@
-
-
-
-  
-  
-  
-  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.
            
-
            
-
            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 13: 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 16)
            
-
            Chapter 16 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.
            
-
              
-
            • 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
              • 
-
            
-
            Chapter 16 Challenge 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 16.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 Chapter 16 challenge 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 Chapter 16.1 challenge issue.
              6. 
-
            6. Post a discovery mapping comment using this format:
              7. 
-
            
-
            Chapter 16.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 16.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 Chapter 16.2 challenge issue and post an evaluation comment:
              7. 
-
            
-
            Chapter 16.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 16.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 Chapter 16.3 challenge issue and post your analysis:
              6. 
-
            
-
            Chapter 16.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 Challenges 16.4-16.5 (Hackathon)
            
-
            Challenge 16.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.
              • 
-
            
-
            Challenge 16.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 Chapter 16: Submit Your Evidence
            
-
            Your evidence is the individual challenge issue comments (16.1, 16.2, 16.3). Close each challenge issue as you complete it. For optional challenges, 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. 
-
            
-
            
-
            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.
            
-
            
-
            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.
            
-
            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.
            
-
            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 V 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.
            
-
            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
            
-
            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.
            
-
            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.
            
-
            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 V, 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 V: 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)
            
-
            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. 
-
            
-
            Back: Issue Templates
            Reference: Appendix V: Accessibility Agents Reference
            Related: Culture & Etiquette | Working with Issues | Appendix M: VS Code Accessibility Reference
            
-
-  
            
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/16-github-copilot.html b/html/docs/16-github-copilot.html
index 66ed23a..00c4c56 100644
--- a/html/docs/16-github-copilot.html
+++ b/html/docs/16-github-copilot.html
@@ -60,7 +60,7 @@
   
            
     
            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.
            
+
            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
@@ -80,19 +80,19 @@ 
            AI-Powered Code Assistance in VS
 
            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 13)
            
+
            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.
            
+
            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 13 introduces GitHub Copilot for AI-assisted documentation and writing.
            
+
            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
              • 
 
            
-
            Chapter 13 Challenge Set
            
+
            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. 
@@ -146,15 +146,15 @@ 
              Challenge 13.3 Step-by-
 
            
 
            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 Chapter 13: Submit Your Evidence
            
-
            Open your assigned Chapter 13 challenge issue and post a completion comment:
            
+
            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 Chapter 13 challenge issues when done.
            
+
            Close your Challenge 13 issue when done.
            
 
            Expected Outcomes
            
 
              
 
            • Student can install and authenticate GitHub Copilot Chat.
              • 
@@ -1053,7 +1053,7 @@ 
              Copilot for Pull Request SummariesWhen 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 ✨ sparkle / Copilot icon next to the description field
                3. 
+
              3. In the PR form, look for the Copilot icon next to the description field
                4. 
 
              4. Click it — Copilot reads your commits and diff and writes a draft description
                5. 
 
              5. Review and edit the draft — it typically includes what changed and why
                6. 
 
              6. Submit the PR
                7. 
@@ -1080,42 +1080,42 @@ 
                Copilot on GitHub.com vs VS Code
                
 
 
 Chat (general questions)
-✅
-✅
+Yes
+Yes
 
 
 Repository / issue / PR context
-✅ Built-in
-✅ Via @github
+Yes, built in
+Yes, via @github
 
 
 Inline code suggestions
-❌
-✅
+No
+Yes
 
 
 Copilot Edits (multi-file)
-❌
-✅
+No
+Yes
 
 
 Agent mode
-❌
-✅
+No
+Yes
 
 
 PR description generation
-✅
-❌
+Yes
+No
 
 
 Code review comments
-✅ (for maintainers)
-❌
+Yes, for maintainers
+No
 
 
 No install required
-✅
+Yes
 Requires extension
 
 
@@ -1896,5 +1896,6 @@ 
                Try It: Your First Copilot Conve
     
                GIT Going with GitHub - A workshop by Community Access
                
     
                View on GitHub · community-access.org
                
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/17-issue-templates.html b/html/docs/17-issue-templates.html
index 94b6c69..e4f4a7c 100644
--- a/html/docs/17-issue-templates.html
+++ b/html/docs/17-issue-templates.html
@@ -60,7 +60,7 @@
   
                
     
                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.
                
+
                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
@@ -74,38 +74,38 @@ 
                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)
                  • 
+
                •  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 13: 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)
                  • 
+
                •  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 15
                  • 
+
                •  You filled out the Workshop Registration template to join this workshop - this is your learning tool for Chapter 17
                  • 
 
                
-
                Day 2 Amplifier: In Chapter 16 (Accessibility Agents), you'll use @template-builder to automate template creation. Complete this chapter first, then come back to Chapter 16.
                
+
                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 15)
                
-
                Chapter 15 is a template design and implementation chapter focused on structuring contributions with a concrete, familiar example.
                
+
                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
                  • 
 
                
-
                Chapter 15 Challenge Set
                
+
                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 15.1 Step-by-Step: Analyze the Registration Template
                
+
                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.
                
@@ -138,14 +138,14 @@ 
                Challenge
 
              7. 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.
                8. 
 
              
 
              You are done when: You can explain the purpose of each field type and why templates reduce back-and-forth questions.
              
-
              Challenge 15.2 Step-by-Step: Remix the Registration Template
              
+
              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:
              
 
                
@@ -167,7 +167,7 @@ 
                Challenge 15
 
              • Commit and push to your repository.
                • 
 
        
 
        You are done when: Your remixed template file is committed and the YAML syntax validates without errors.
        
-
        Challenge 15.3 (Optional) Step-by-Step: Create a Markdown Template
        
+
        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.
        
 
          
@@ -196,7 +196,7 @@ 
          Challeng
 
        1. Commit and push.
          2. 
 
        
 
        You are done when: Your Markdown template file is committed with proper frontmatter and section structure.
        
-
        Challenge 15.4 (Optional): Test in the Template Chooser
        
+
        Challenge 14.4 (Optional): Test in the Template Chooser
        
 
          
 
        1. Navigate to your test repository on GitHub.com.
          2. 
 
        2. Activate New Issue.
          3. 
@@ -204,16 +204,16 @@ 
          Challenge 15.4 (Opt
 
        3. Activate Get started on your template and file a test issue.
          4. 
 
        
 
        You are done when: Your template works and appears in the GitHub template picker.
        
-
        Completing Chapter 15: Submit Your Evidence
        
-
        Open your assigned Chapter 15 challenge issue and post a completion comment:
        
-
        Chapter 15 completed:
+
        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 Chapter 15 challenge issues when done.
        
+
        Close your Challenge 14 issue when done.
        
 
        Expected Overall Outcomes
        
 
          
 
        • Student understands template structure (YAML frontmatter, field types, validation).
          • 
@@ -226,7 +226,7 @@ 
          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/chapter-15-registration-remix-example.yml and check indentation.
            4. 
+
          4. YAML not parsing? Compare with the remix sample in learning-room/docs/samples/challenge-14-registration-remix-example.yml and check indentation.
            5. 
 
          5. 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.
            6. 
 
          6. 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.
            7. 
 
          7. Remix approach feels overwhelming? Start by changing just the field labels and descriptions. Do not change the structure yet.
            8. 
@@ -583,7 +583,7 @@ 
            Complete Markdown Template ExampleComplete Markdown Template Example*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]  
+**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
@@ -623,10 +623,10 @@ 
            Complete Markdown Template ExampleWhat happens
            
 
            Step 5: Copy the Accessibility Template YAML
            
 
            What to do
            
 
              
-
            1. Go to Chapter 15, Section 7 in this curriculum
              2. 
+
            2. Go to Chapter 17, Section 7 in this curriculum
              3. 
 
            3. Find the complete YAML template code block (starting with name: and ending with the last field)
              4. 
 
            4. Select all the YAML code (use Ctrl+A on the webpage or manually select)
              5. 
 
            5. Copy it (Ctrl+C)
              6. 
@@ -1856,13 +1856,13 @@ 
              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 
+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 
+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
@@ -1946,7 +1946,7 @@ 
              What to do
              
 
        
 
 
      8. Leave a reply comment on the PR:
        
-
        Thanks for the feedback! I've made the changes you requested 
+
        Thanks for the feedback! I've made the changes you requested
 in commit [commit hash]. The template now includes [what you changed].
        
 
        9. 
 
      9. Click Reply
        10. 
@@ -2398,5 +2398,6 @@ 
        Using the Template Builder
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/18-fork-and-contribute.html b/html/docs/18-fork-and-contribute.html
index 1a0325d..3929278 100644
--- a/html/docs/18-fork-and-contribute.html
+++ b/html/docs/18-fork-and-contribute.html
@@ -541,16 +541,16 @@ 
        Learning Cards: Keeping Your F
 
        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)
          • 
+
        •  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:
        
@@ -615,5 +615,6 @@ 
        13. If You Get Stuck
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/19-accessibility-agents.html b/html/docs/19-accessibility-agents.html
index 5687a9d..1d45b50 100644
--- a/html/docs/19-accessibility-agents.html
+++ b/html/docs/19-accessibility-agents.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
@@ -78,10 +78,10 @@ 
        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 13: 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)
          • 
+
        •  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:
        
@@ -121,8 +121,8 @@ 
        Agent Prerequisit
 
 
        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 16)
        
-
        Chapter 16 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.
        
+
        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)
          • 
@@ -130,7 +130,7 @@ 
          Workshop Recommendation (Chapter 16)
 
        • Pattern: explore, validate, read internals, optionally contribute
          • 
 
        • Key principle: Skill First, Agent Second - every agent requires manual prerequisite skills
          • 
 
        
-
        Chapter 16 Challenge Set
        
+
        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. 
@@ -138,9 +138,9 @@ 
          Chapter 16 Challenge Set
          
 
        3. Improve an Existing Agent (optional hackathon) - find a gap in an agent's instructions and fix it via PR.
          4. 
 
        4. Propose a New Agent (optional hackathon) - file an issue proposing an agent for an uncovered workflow.
          5. 
 
        
-
        Challenge 16.1 Step-by-Step: Agent Discovery Mapping
        
+
        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 Chapter 16 challenge issue.
        
+
        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:
        
 
          
@@ -158,10 +158,10 @@ 
          Challenge 16.1 Step-
 
        • Example: You checked colors for contrast - you can use @contrast-master
          • 
 
        
 
-
      10. Open your assigned Chapter 16.1 challenge issue.
        11. 
+
      11. Open your assigned Challenge 15 issue.
        12. 
 
      12. Post a discovery mapping comment using this format:
        13. 
 
      
-
      Chapter 16.1 - Agent Discovery Mapping:
+
      Challenge 15.1 - Agent Discovery Mapping:
 
 Agent 1: @[agent-name]
 I am ready because I have already: [specific skill from Day 1]
@@ -172,7 +172,7 @@ 
      Challenge 16.1 Step-
 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 16.2 Step-by-Step: Agent Skill Validation
      
+
      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.
      
@@ -187,9 +187,9 @@ 
      Challenge 16.2 Step-b
 
    
 
 
  • Read the agent's output carefully. Take a moment to think about what you expected.
    • 
-
  • Open your assigned Chapter 16.2 challenge issue and post an evaluation comment:
    • 
+
  • Open your assigned Challenge 15 issue and post an evaluation comment:
    • 
 
-
    Chapter 16.2 - Agent Validation:
+
    Challenge 15.2 - Agent Validation:
 
 Agent used: @[agent-name]
 Prompt: [exact prompt you used]
@@ -203,7 +203,7 @@ 
    Challenge 16.2 Step-b
 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 16.3 Step-by-Step: Agent Instructions Deep Dive
    
+
    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.
    
@@ -217,9 +217,9 @@ 
    Challenge 16.3
 
 
 
  • Think critically: could this agent make a mistake? What kind?
    • 
-
  • Open your assigned Chapter 16.3 challenge issue and post your analysis:
    • 
+
  • Open your assigned Challenge 15 issue and post your analysis:
    • 
 
-
    Chapter 16.3 - Agent Internals:
+
    Challenge 15.3 - Agent Internals:
 
 Agent file: [filename]
 Purpose: [one sentence]
@@ -227,8 +227,8 @@ 
    Challenge 16.3
 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 Challenges 16.4-16.5 (Hackathon)
    
-
    Challenge 16.4: Improve an Existing Agent (45 min)
    
+
    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.
      • 
@@ -236,15 +236,15 @@ 
      Optional Challenges 16.4-16.5 (Ha
 
    • Open a PR with your improvement.
      • 
 
    • Evidence: your merged PR.
      • 
 
    
-
    Challenge 16.5: Propose a New Agent (60 min)
    
+
    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 Chapter 16: Submit Your Evidence
    
-
    Your evidence is the individual challenge issue comments (16.1, 16.2, 16.3). Close each challenge issue as you complete it. For optional challenges, your PR or proposal issue is the evidence.
    
+
    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.
      • 
@@ -1047,9 +1047,9 @@ 
      Output example
      
 ### 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  
+**Files Changed:** 1
+**Lines Added:** 127
+**Lines Removed:** 18
 
 ### Risk Assessment
 **Risk Level:** Low
@@ -1163,9 +1163,9 @@ 
      Output example
      
 ### Issues Found: 2
 
 #### Issue 1: Heading Hierarchy Skip
-**File:** docs/11-vscode-basics.md  
-**Commit:** a3f2b9c  
-**Line:** 142  
+**File:** docs/11-vscode-basics.md
+**Commit:** a3f2b9c
+**Line:** 142
 
 **Problem:** H1 → H3 skip (missing H2)
 
@@ -1184,9 +1184,9 @@ 
      Output example
      
 
 #### Issue 2: Non-Descriptive Link Text
 
-**File:** README.md  
-**Commit:** b8e3c1d  
-**Line:** 28  
+**File:** README.md
+**Commit:** b8e3c1d
+**Line:** 28
 
 **Problem:** Link text is "click here"
 
@@ -1205,9 +1205,9 @@ 
      Output example
      
 
 #### Improvement: ARIA Label Added
 
-**File:** docs/navigation-guide.md  
-**Commit:** c7d4e2f  
-**Line:** 89  
+**File:** docs/navigation-guide.md
+**Commit:** c7d4e2f
+**Line:** 89
 
 **Change:** Added `aria-label` to icon-only button example
 
@@ -1325,7 +1325,7 @@ 
      Most Useful for This Workshop
      
 
 
 
      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 V for the complete list.
      
+
      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
@@ -1871,7 +1871,7 @@ 
      What to do
      
 
      What to look for
      
 
      ## Pre-Built Workflow: Guided Accessibility Template
 
-The agent includes a guided workflow for the most common case: building 
+The agent includes a guided workflow for the most common case: building
 an accessibility bug report template.
 
 ### Invoke with
@@ -2257,7 +2257,7 @@ 
      Slash Commands That Save the Mos
 
    • /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 V, and Episode 39 walks through all of them with examples.
    
+
    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:
    
@@ -2287,7 +2287,7 @@ 
    Scope 3: The Cloud (GitHub A
 
    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 V: Accessibility Agents Reference. For the audio version, listen to Episode 39: Accessibility Agents - Complete Reference.
    
+
    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
@@ -2447,5 +2447,6 @@ 
    Solutions
    
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/20-build-your-agent.html b/html/docs/20-build-your-agent.html
index f1a4321..5cb8118 100644
--- a/html/docs/20-build-your-agent.html
+++ b/html/docs/20-build-your-agent.html
@@ -97,11 +97,11 @@ 
    1. The Capstone Challenge
    
 
    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
      • 
+
    •  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.
    
@@ -346,11 +346,11 @@ 
    Testing with GitHub Copilot Chat
    
 
 
    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)
      • 
+
    •  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:
    
@@ -414,11 +414,11 @@ 
    Tool Cards: Open Your Capstone PR
    
 
    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
      • 
+
    •  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:
    
@@ -719,5 +719,6 @@ 
    The universal safety net
    
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/21-next-steps.html b/html/docs/21-next-steps.html
index 4fe58aa..6fd59f1 100644
--- a/html/docs/21-next-steps.html
+++ b/html/docs/21-next-steps.html
@@ -466,5 +466,6 @@ 
    8. Final Words
    
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/CHALLENGES.html b/html/docs/CHALLENGES.html
index 8fd8de5..d719254 100644
--- a/html/docs/CHALLENGES.html
+++ b/html/docs/CHALLENGES.html
@@ -59,308 +59,321 @@
   
   
    
     
    Challenge Hub
    
-
    Welcome to the Challenge Hub -- your guide to all 16 core challenges and 5 bonus challenges.
    
-
    How challenges work
    
-
      
-
    1. Go to the Issues tab of this repository.
      2. 
-
    2. Find issues assigned to you (filter by your username).
      3. 
-
    3. Each issue has step-by-step instructions, evidence prompts, and buddy checks.
      4. 
-
    4. Complete the challenge, post your evidence as a comment, and close the issue.
      5. 
-
    
-
    Curriculum chapters: Every challenge links to chapters in the curriculum repository where you can read the full material.
    
-
    
+
    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
    
-
    Navigate the learning-room repository like a scavenger hunt. Find the tabs, explore the file tree, read the README, and locate key files.
    
+
    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 files in the root
      • 
-
    • Open the Issues tab and find an open issue
      • 
-
    • Navigate to docs/welcome.md and read the first paragraph
      • 
-
    • Find the repository description and the README
      • 
+
    • 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
      • 
 
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Find a TODO comment in docs/welcome.md and file an issue describing the problem with a clear title and description.
    
+
    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 descriptive title
      • 
-
    • Explain what needs to change, where, and why
      • 
+
    • Create a new issue with a specific title
      • 
+
    • Explain what needs to change, where it is, and why the change would help
      • 
 
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Comment on a buddy's issue using @mentions and reactions.
    
+
    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
      • 
+
    • 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 their original issue
      • 
+
    • Add a reaction to the original issue or a helpful comment
      • 
 
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Create a personal branch named learn/YOUR-USERNAME for your Day 1 work.
    
+
    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 dropdown on the Code tab
      • 
-
    • Type learn/YOUR-USERNAME and create the branch from main
      • 
+
    • 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
      • 
 
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Edit docs/welcome.md on your branch to fix the TODO, then commit with a meaningful message.
    
+
    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 real content
      • 
-
    • Write a commit message that explains what you changed and why
      • 
+
    • Edit docs/welcome.md to replace the TODO with useful content
      • 
+
    • Write a commit message that explains the change in plain language
      • 
 
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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 PR
+Challenge 6: Open Your First Pull Request
 
 
    Chapter: Ch06 | Evidence: Comment
    
-
    Open a pull request from your branch to main, linking it to your issue with Closes #XX.
    
+
    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 base to main, compare to learn/YOUR-USERNAME
      • 
+
    • 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
      • 
 
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Resolve a facilitator-triggered merge conflict by removing conflict markers and keeping the right content.
    
+
    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 conflict markers (<<<<<<<, =======, >>>>>>>) in the file
      • 
-
    • Decide which content to keep and delete all marker lines
      • 
-
    • Commit the resolution
      • 
+
    • 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
      • 
 
    
-
    The autograder checks that no conflict markers remain.
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Reflect on open source culture and triage an issue with labels.
    
+
    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 a reflection question about your workshop experience
      • 
-
    • Add a label to an open issue that describes its type
      • 
-
    • Leave a comment explaining your triage decision
      • 
+
    • 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
      • 
 
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Get your Day 1 PR merged, verify your changes on main, and celebrate.
    
+
    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 the facilitator to approve)
      • 
-
    • Confirm your changes appear on the main branch
      • 
-
    • Check that your linked issue was automatically closed
      • 
+
    • 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
      • 
 
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Clone the repo, create a feature branch, edit, commit, and push from your local tool.
    
+
    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 the repository to your computer (VS Code, GitHub Desktop, or CLI)
      • 
+
    • 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 to GitHub
      • 
+
    • Commit and push the branch to GitHub
      • 
 
    
-
    The autograder verifies a commit on a non-default branch.
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Open a PR from your locally-pushed branch. Notice the workflow pattern is the same as Day 1.
    
+
    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 clear title and description
      • 
-
    • Recognize: the pull request step is identical whether you edit online or locally
      • 
+
    • Write a title and description that describe the change clearly
      • 
+
    • Notice the familiar shape: branch, compare, title, body, submit
      • 
 
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Perform a full code review of your buddy's Day 2 PR.
    
+
    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 and go to Files changed
      • 
-
    • Leave at least two inline comments (one praise, one suggestion)
      • 
-
    • Use the Suggest changes feature for at least one comment
      • 
-
    • Submit your review with a verdict (Approve, Request changes, or Comment)
      • 
+
    • 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
      • 
 
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Use GitHub Copilot to improve documentation, then critically evaluate the output.
    
+
    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:
    
 
      
-
    • Use Copilot to improve a documentation file
      • 
-
    • Apply the trust-verify-reject framework to each suggestion
      • 
-
    • Document what you accepted, modified, and rejected
      • 
+
    • 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
      • 
 
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Create a custom issue template by remixing the registration template.
    
+
    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 the sample at docs/samples/challenge-14-registration-remix-example.yml
      • 
+
    • Study docs/samples/challenge-14-registration-remix-example.yml
      • 
 
    • Create a new YAML template in .github/ISSUE_TEMPLATE/
      • 
-
    • Include a name, description, title, and at least one form field
      • 
-
    • Commit and push
      • 
+
    • Include name, description, title, and at least one form field
      • 
+
    • Commit and push the template
      • 
 
    
-
    The autograder verifies a valid YAML template with a name field.
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Discover accessibility agents, run one, and read one agent's instructions.
    
+
    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:
    
 
      
-
    • Browse the accessibility-agents repository
      • 
-
    • Find and name at least 3 different agents
      • 
-
    • Run one agent and describe what happened
      • 
-
    • Read one agent's .agent.md file and identify its purpose and guardrails
      • 
+
    • Browse the Community Access Accessibility Agents repository
      • 
+
    • Find and name at least three different agents
      • 
+
    • Run or inspect one agent and describe what happened
      • 
+
    • Read one .agent.md file and identify its purpose and guardrails
      • 
 
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    Fork the accessibility-agents repo, write your own agent, and open a cross-fork PR.
    
+
    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 accessibility-agents repository
      2. 
-
    2. Clone your fork and create a branch agent/YOUR-USERNAME
      3. 
+
    3. Fork the Community Access Accessibility Agents repository
      4. 
+
    4. Clone your fork and create a branch named agent/YOUR-USERNAME
      5. 
 
    5. Write an .agent.md file with YAML frontmatter, responsibilities, and guardrails
      6. 
 
    6. Push and open a cross-fork PR to the original repository
      7. 
-
    7. Review a classmate's capstone PR
      8. 
+
    8. Review a classmate's capstone PR when one is available
      9. 
 
    
-
    Use the agent file template and fork workflow checklist for guidance.
    
-
    The autograder verifies your agent file exists, has valid YAML, and contains required sections.
    
-
    Compare your work: When you are done, you can view a completed example to see how your approach compares. Different is fine. The learning objective is what matters.
    
+
    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
    
-
    For students who finish early and want to keep building.
    
+
    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 an improvement, and open a PR.
    
-
    Compare your work: View a completed example
    
+
    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 your workshop experience using proper Markdown.
    
-
    Compare your work: View a completed example
    
+
    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 that future cohorts can use.
    
-
    Compare your work: View a completed example
    
+
    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 notification settings for a productive workflow.
    
-
    Compare your work: View a completed example
    
+
    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 as a visual timeline.
    
-
    Compare your work: View a completed example
    
+
    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.
    
 
    
 
-
    
-
    If you get stuck
    
-
    Every challenge issue includes an "If you get stuck" table with common problems and solutions. You can also:
    
+
    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.
    
 
   
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-a-glossary.html b/html/docs/appendix-a-glossary.html
index 3f5bf04..ac31472 100644
--- a/html/docs/appendix-a-glossary.html
+++ b/html/docs/appendix-a-glossary.html
@@ -60,7 +60,7 @@
   
    
     
    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.
    
+
    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
    
@@ -253,7 +253,7 @@ 
    Merge Conflict
    
 
    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.
    
@@ -858,5 +858,6 @@ 
    Alphabetical Quick Reference
    
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-aa-advanced-git.html b/html/docs/appendix-aa-advanced-git.html
deleted file mode 100644
index ef010d2..0000000
--- a/html/docs/appendix-aa-advanced-git.html
+++ /dev/null
@@ -1,919 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix: Advanced Git Operations - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix: 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.
    
-
    
-
    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. 
-
    
-
    
-
    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 11, 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.
    
-
    
-
    
-
    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 13: GitHub Copilot for the full guide to Copilot Chat, inline suggestions, and effective prompting. Appendix W: Copilot Reference for the complete command and participant reference.
    
-
    
-
    
-
    Related appendices: Appendix D: Git Authentication · Appendix H: Releases, Tags, and Insights · Appendix K: Branch Protection and Rulesets · Chapter 11: Git & Source Control
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-ab-github-desktop.html b/html/docs/appendix-ab-github-desktop.html
deleted file mode 100644
index 3188e5a..0000000
--- a/html/docs/appendix-ab-github-desktop.html
+++ /dev/null
@@ -1,571 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix AB: GitHub Desktop - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix AB: 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.
    
-
    
-
    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
    
-
      
-
    • ✅ Clone repositories from GitHub
      • 
-
    • ✅ Create, switch, and delete branches
      • 
-
    • ✅ Stage files (and individual lines/hunks within files)
      • 
-
    • ✅ Write commit messages and commit
      • 
-
    • ✅ Push and pull from GitHub
      • 
-
    • ✅ Open pull requests (launches GitHub.com in your browser)
      • 
-
    • ✅ Resolve merge conflicts with a visual editor
      • 
-
    • ✅ View commit history and diffs
      • 
-
    • ✅ Cherry-pick commits between branches
      • 
-
    • ✅ Stash and restore uncommitted changes
      • 
-
    • ✅ Undo commits and discard changes
      • 
-
    
-
    What it does not support (use Git CLI or VS Code terminal instead)
    
-
      
-
    • ❌ Interactive rebase (git rebase -i)
      • 
-
    • ❌ git bisect
      • 
-
    • ❌ git clean
      • 
-
    • ❌ Creating annotated tags
      • 
-
    • ❌ 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.
    
-
    
-
    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
    
-
    
-
    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 11, 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.
    
-
    
-
    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.
    
-
    
-
    Related chapters and appendices: Chapter 11: Git & Source Control in VS Code · Appendix AA: Advanced Git Operations · Appendix D: Git Authentication · Chapter 12: GitHub Pull Requests Extension
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-ac-github-cli.html b/html/docs/appendix-ac-github-cli.html
deleted file mode 100644
index 04339a8..0000000
--- a/html/docs/appendix-ac-github-cli.html
+++ /dev/null
@@ -1,757 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix AC: GitHub CLI Reference - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix AC: 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.
    
-
    
-
    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.
    
-
    
-
    
-
    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.
    
-
    
-
    
-
    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.
    
-
    
-
    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
      • 
-
    
-
    
-
    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
    
-
    
-
    Related appendices: Appendix AA: Advanced Git Operations · Appendix AB: GitHub Desktop · Appendix D: Git Authentication · Appendix W: Copilot Reference
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-ad-git-security.html b/html/docs/appendix-ad-git-security.html
deleted file mode 100644
index a12ffc6..0000000
--- a/html/docs/appendix-ad-git-security.html
+++ /dev/null
@@ -1,490 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix AD: Git Security for Contributors - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix AD: 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.
    
-
    
-
    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. 
-
    
-
    
-
    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
    
-
    ❌ Don't 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.
    
-
    
-
    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.
    
-
    
-
    
-
    Related appendices: Appendix D: Git Authentication · Appendix K: Branch Protection and Rulesets · Appendix L: GitHub Security Features · Appendix AA: Advanced Git Operations
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-ae-github-social.html b/html/docs/appendix-ae-github-social.html
deleted file mode 100644
index a667c2c..0000000
--- a/html/docs/appendix-ae-github-social.html
+++ /dev/null
@@ -1,522 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix AE: GitHub Social — Stars, Following, and Finding Your Community - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix AE: GitHub Social — Stars, Following, and Finding Your Community
    
-
    
-
    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.
    
-
    
-
    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.
    
-
    
-
    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
    
-
    
-
    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. 
-
    
-
    
-
    Related appendices: Appendix R: Profile, Sponsors, and Wikis · Appendix J: Advanced Search · Appendix T: Contributing to Open Source · Appendix AC: GitHub CLI Reference
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-b-screen-reader-cheatsheet.html b/html/docs/appendix-b-screen-reader-cheatsheet.html
index de2da6d..ffd0ed6 100644
--- a/html/docs/appendix-b-screen-reader-cheatsheet.html
+++ b/html/docs/appendix-b-screen-reader-cheatsheet.html
@@ -60,7 +60,7 @@
   
    
     
    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.
    
+
    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
    
@@ -1598,7 +1598,7 @@ 
    Keyboard Shortcuts in Other Appe
 
 
 GitHub Copilot Chat and inline suggestions
-Appendix W - GitHub Copilot Reference
+Appendix K - GitHub Copilot Reference
 
 
 VS Code setup and configuration shortcuts
@@ -1654,5 +1654,6 @@ 
    If a command doesn't work a
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-c-accessibility-standards.html b/html/docs/appendix-c-accessibility-standards.html
deleted file mode 100644
index 2c993cf..0000000
--- a/html/docs/appendix-c-accessibility-standards.html
+++ /dev/null
@@ -1,586 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix C: Accessibility Standards Reference - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix C: 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.
    
-
    
-
    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.
    
-
    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. 
-
    
-
    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
    
-
    Return to: Resources | Appendix B - Screen Reader Cheat Sheet | Appendix A - Glossary
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-c-markdown-reference.html b/html/docs/appendix-c-markdown-reference.html
index abffbd0..c7eed5f 100644
--- a/html/docs/appendix-c-markdown-reference.html
+++ b/html/docs/appendix-c-markdown-reference.html
@@ -60,7 +60,7 @@
   
    
     
    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.
    
+
    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
    
@@ -254,15 +254,15 @@ 
    Day 2 - VS Code and Accessibil
 While not full Markdown, commit messages follow similar plain-text conventions
 
 
-Using Copilot Chat (Chapter 13)
+Using Copilot Chat (Chapter 16)
 Copilot returns responses formatted in Markdown
 
 
-Creating issue templates (Chapter 15)
+Creating issue templates (Chapter 17)
 Templates use Markdown for the body content
 
 
-Agent commands and output (Chapter 16)
+Agent commands and output (Chapter 19)
 Agent reports are rendered Markdown
 
 
@@ -313,8 +313,8 @@ 
    Paragraphs
    
 
    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  
+
    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:
    
@@ -401,7 +401,7 @@ 
    Rules for accessible headings
    
 
 
    Markdown also supports "setext" headings where you underline text with = or - characters:
    
 
    Heading Level 1
-===============
+===============
 
 Heading Level 2
 ---------------
    
@@ -2205,58 +2205,58 @@ 
    29. Accessible Markdown Auth
 
    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
      • 
+
    •  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
      • 
+
    •  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
      • 
+
    •  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)
      • 
+
    •  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
      • 
+
    •  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
      • 
+
    •  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
      • 
+
    •  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
      • 
+
    •  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.
    
@@ -2547,5 +2547,6 @@ 
    Mermaid diagram (with accessible t
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-d-git-authentication.html b/html/docs/appendix-d-git-authentication.html
index 8835871..3a8c29d 100644
--- a/html/docs/appendix-d-git-authentication.html
+++ b/html/docs/appendix-d-git-authentication.html
@@ -60,7 +60,7 @@
   
    
     
    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.
    
+
    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
    
@@ -369,5 +369,6 @@ 
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-e-advanced-git.html b/html/docs/appendix-e-advanced-git.html
index 331b5e5..745d3c4 100644
--- a/html/docs/appendix-e-advanced-git.html
+++ b/html/docs/appendix-e-advanced-git.html
@@ -316,7 +316,7 @@ 
    The Three Modes
    
 
 
 
    
-
    --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 11, Section 10b).
    
+
    --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
    
@@ -971,7 +971,7 @@ 
    GitHub Copilot CLI — Git
 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 13: GitHub Copilot for the full guide to Copilot Chat, inline suggestions, and effective prompting. Appendix W: Copilot Reference for the complete command and participant reference.
    
+
    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
    
@@ -981,5 +981,6 @@ 
    GitHub Copilot CLI — Git
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-e-github-flavored-markdown.html b/html/docs/appendix-e-github-flavored-markdown.html
deleted file mode 100644
index 8b6acc5..0000000
--- a/html/docs/appendix-e-github-flavored-markdown.html
+++ /dev/null
@@ -1,2374 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix E: Markdown and GitHub Flavored Markdown - Complete Guide - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix E: 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.
    
-
    
-
    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
    
-
    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 13)Copilot returns responses formatted in Markdown
    Creating issue templates (Chapter 15)Templates use Markdown for the body content
    Agent commands and output (Chapter 16)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.
    
-
    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.
    
-
    
-
    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.
    
-
    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.
    
-
    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.
    
-
    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>
    
-
    Return to: Course Guide | Appendix B - Screen Reader Cheat Sheet | Appendix A - Glossary | Resources
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-f-git-security.html b/html/docs/appendix-f-git-security.html
index 392fb71..05a4cb5 100644
--- a/html/docs/appendix-f-git-security.html
+++ b/html/docs/appendix-f-git-security.html
@@ -213,10 +213,10 @@ 
    GitHub's .gitignore templates
    
 
    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)
+
    # Never do this (hardcoded secret in code)
 API_KEY = "sk-abc123yoursecretkeyhere"
 
-# ✅ Do this instead (read from environment)
+# 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
    
@@ -260,13 +260,13 @@ 
    git diff --staged — s
 
 
    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
+
    # Risky - stages everything without review
 git add .
 
-# ✅ Better — stage specific files you know are clean
+# Better - stage specific files you know are clean
 git add src/auth.js docs/README.md
 
-# ✅ Or stage interactively — review each file before adding
+# 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
    
@@ -418,7 +418,7 @@ 
    Quick decision flowchart
    
 
    Secret committed
       │
       ├─ Still local only (not pushed)?
-      │     └─ git reset --soft HEAD~1 → remove secret → recommit ✅
+      │     └─ git reset --soft HEAD~1 -> remove secret -> recommit
       │
       └─ Already pushed?
             ├─ Rotate the secret FIRST (assume compromised)
@@ -457,7 +457,7 @@ 
    Checking your repo's p
 
    
 
    8. Secure Credential Storage
    
 
    Never store credentials in plaintext
    
-
    ❌ Don't do these:
    
+
    Do not do these:
    
 
    # Storing a token in a plain text file
 echo "ghp_mytoken" > ~/token.txt
 
@@ -466,7 +466,7 @@ 
    Never store credentials in plainte
 
 # 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:
    
+
    Do this instead - use the OS credential store:
    
 
    # macOS — use Keychain
 git config --global credential.helper osxkeychain
 
@@ -517,29 +517,29 @@ 
    9. Security Checklist for Contrib
 
    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
      • 
+
    •  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)
      • 
+
    •  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
      • 
+
    •  .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
      • 
+
    •  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.
    
@@ -552,5 +552,6 @@ 
    If you're a maintainer
    
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-f-github-gists.html b/html/docs/appendix-f-github-gists.html
deleted file mode 100644
index 759962b..0000000
--- a/html/docs/appendix-f-github-gists.html
+++ /dev/null
@@ -1,315 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix F: GitHub Gists - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix F: 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.
    
-
    
-
    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)
    
-
    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. 
-
    
-
    Warning: Deletion is permanent. Forks of your Gist are not deleted.
    
-
    Return to: Resources
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-g-github-discussions.html b/html/docs/appendix-g-github-discussions.html
deleted file mode 100644
index 5c0d3ec..0000000
--- a/html/docs/appendix-g-github-discussions.html
+++ /dev/null
@@ -1,279 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix G: GitHub Discussions - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix G: 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.
    
-
    
-
    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.
    
-
    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
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-g-vscode-reference.html b/html/docs/appendix-g-vscode-reference.html
index f50e231..8e12e7a 100644
--- a/html/docs/appendix-g-vscode-reference.html
+++ b/html/docs/appendix-g-vscode-reference.html
@@ -60,7 +60,7 @@
   
    
     
    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.
    
+
    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
    
@@ -1756,7 +1756,7 @@ 
    Learning Cards: Accessibility Sign
 
 
 
    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 5, Section 9: Profiles for how to create, switch, export, and share profiles.
    
+
    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
    
 
    {
@@ -1896,5 +1896,6 @@ 
    
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-h-github-desktop.html b/html/docs/appendix-h-github-desktop.html
index e22af70..b284714 100644
--- a/html/docs/appendix-h-github-desktop.html
+++ b/html/docs/appendix-h-github-desktop.html
@@ -96,25 +96,25 @@ 
    1. What GitHub Desktop Does
 
    GitHub Desktop covers the everyday Git workflow that most contributors use on most days.
    
 
    What it supports
    
 
      
-
    • ✅ Clone repositories from GitHub
      • 
-
    • ✅ Create, switch, and delete branches
      • 
-
    • ✅ Stage files (and individual lines/hunks within files)
      • 
-
    • ✅ Write commit messages and commit
      • 
-
    • ✅ Push and pull from GitHub
      • 
-
    • ✅ Open pull requests (launches GitHub.com in your browser)
      • 
-
    • ✅ Resolve merge conflicts with a visual editor
      • 
-
    • ✅ View commit history and diffs
      • 
-
    • ✅ Cherry-pick commits between branches
      • 
-
    • ✅ Stash and restore uncommitted changes
      • 
-
    • ✅ Undo commits and discard changes
      • 
+
    • 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)
    
 
      
-
    • ❌ Interactive rebase (git rebase -i)
      • 
-
    • ❌ git bisect
      • 
-
    • ❌ git clean
      • 
-
    • ❌ Creating annotated tags
      • 
-
    • ❌ Commit signing (GPG/SSH)
      • 
+
    • 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
    
@@ -492,7 +492,7 @@ 
    Restore your stash
    
 
  • Your changes come back
    • 
 
 
    
-
    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 11, Section 10 for the full stash guide.
    
+
    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
    
@@ -664,5 +664,6 @@ 
    16. GitHub De
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-h-releases-tags-insights.html b/html/docs/appendix-h-releases-tags-insights.html
deleted file mode 100644
index b96b7aa..0000000
--- a/html/docs/appendix-h-releases-tags-insights.html
+++ /dev/null
@@ -1,538 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix H: Releases, Tags, and Repository Insights - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix H: 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.
    
-
    
-
    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
    
-
    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.
    
-
    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
    
-
    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
    
-
    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
      • 
-
    
-
    Use these instead of navigating the Insights UI when you want contribution data without leaving VS Code and without dealing with canvas charts.
    
-
    Return to: Resources | Glossary
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-i-github-cli.html b/html/docs/appendix-i-github-cli.html
index a45dd0c..c74c000 100644
--- a/html/docs/appendix-i-github-cli.html
+++ b/html/docs/appendix-i-github-cli.html
@@ -861,5 +861,6 @@ 
    Copilot
    
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-i-github-projects.html b/html/docs/appendix-i-github-projects.html
deleted file mode 100644
index 61c06c4..0000000
--- a/html/docs/appendix-i-github-projects.html
+++ /dev/null
@@ -1,468 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix I: GitHub Projects Deep Dive - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix I: 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.
    
-
    
-
    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
    
-
    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
      • 
-
    
-
    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.
    
-
    
-
    Return to: Resources | Glossary
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-j-advanced-search.html b/html/docs/appendix-j-advanced-search.html
deleted file mode 100644
index 9510ed3..0000000
--- a/html/docs/appendix-j-advanced-search.html
+++ /dev/null
@@ -1,424 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix J: GitHub Advanced Search - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix J: 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.
    
-
    
-
    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.)
    
-
    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
    
-
    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
    
-
    Return to: Resources | Screen Reader Cheat Sheet
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-j-cloud-editors.html b/html/docs/appendix-j-cloud-editors.html
index b6d09b3..1b86b9c 100644
--- a/html/docs/appendix-j-cloud-editors.html
+++ b/html/docs/appendix-j-cloud-editors.html
@@ -60,7 +60,7 @@
   
    
     
    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.
    
+
    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
    
@@ -521,5 +521,6 @@ 
    My changes are no
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-k-branch-protection-rulesets.html b/html/docs/appendix-k-branch-protection-rulesets.html
deleted file mode 100644
index 001d644..0000000
--- a/html/docs/appendix-k-branch-protection-rulesets.html
+++ /dev/null
@@ -1,401 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix K: Branch Protection Rules and Repository Rulesets - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
    
-    
    Appendix K: 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.
    
-
    
-
    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.
    
-
    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.
    
-
    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.
    
-
-
-
    Return to: Resources | Appendix L - Security Features
    
-
-  
    
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-k-copilot-reference.html b/html/docs/appendix-k-copilot-reference.html
index 2bb7e3e..5f39378 100644
--- a/html/docs/appendix-k-copilot-reference.html
+++ b/html/docs/appendix-k-copilot-reference.html
@@ -69,11 +69,11 @@ 
    Appendix K: Copilot 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.
    
+
    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 13: GitHub Copilot. For Accessibility Agents specifically, see Appendix V: Accessibility Agents Reference.
    
+
    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
    
 
      
@@ -334,7 +334,7 @@ 
      Workspace management slash commands
 After 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 V for the full list.
      
+
      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
@@ -1784,7 +1784,7 @@ 
      Resources
      
 
 
 
      
-
      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 V for the full Accessibility Agents reference.
      
+
      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:
      
@@ -1806,11 +1806,11 @@ 
      Learning Cards: GitHub Agentic
 
    1. 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
      2. 
 
 
      Chapter: GitHub Copilot
-Related: Appendix V: Accessibility Agents Reference | Appendix M: VS Code Accessibility Reference | Appendix X: AI Models Reference
      
+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.
      
+
      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.
      
 
      
 
 
        
@@ -2330,5 +2330,6 @@ 
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-l-agents-reference.html b/html/docs/appendix-l-agents-reference.html
index 44991d6..711761f 100644
--- a/html/docs/appendix-l-agents-reference.html
+++ b/html/docs/appendix-l-agents-reference.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
@@ -68,7 +68,7 @@ 
        Appendix L: Accessibility Age
 
        
 
        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 16: Accessibility Agents. For Copilot keyboard shortcuts and Chat features, see Appendix W: GitHub Copilot Reference.
        
+
        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
        
 
          
@@ -2051,7 +2051,7 @@ 
          Accessibility Agents Keyboard S
 
 
 
          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 W: GitHub Copilot & Agentic Reference.
          
+
          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
          
 
@@ -2081,5 +2081,6 @@ 
          Official accessibility.github.co
     
          GIT Going with GitHub - A workshop by Community Access
          
     
          View on GitHub · community-access.org
          
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-l-github-security-features.html b/html/docs/appendix-l-github-security-features.html
deleted file mode 100644
index 8e8c333..0000000
--- a/html/docs/appendix-l-github-security-features.html
+++ /dev/null
@@ -1,348 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix L: GitHub Security Features - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
          
-    
          Appendix L: 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.
          
-
          
-
          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 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 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 Tab
            9. 
-
          9. Security and Accessibility Agents
            10. 
-
          
-
          1. The Security Tab - What It Contains
          
-
          Every GitHub repository has a Security 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 Tab
          
-
          On any repository page:
-Tab navigation → secondary nav region → "Security" link → Enter
-Or: G then S (GitHub keyboard shortcut - enable Focus Mode first)
          
-
          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.
          
-
          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 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 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 tab → Policies section → "Security policy" link
            2. 
-
          2. Or directly: https://github.com/owner/repo/security/policy
            3. 
-
          
-
          Screen reader path:
          
-
          Security 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 Tab
          
-
          Reaching the Security 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 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 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 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 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)
          
-
          Workshop exercise: Run /security-dashboard on your fork after Day 2. Review any Dependabot PRs open on the upstream community-access/accessibility-agents - merging one is a real security contribution.
          
-
          Return to: Resources | Appendix Q - GitHub Actions | Appendix K - Branch Protection
          
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-m-accessibility-standards.html b/html/docs/appendix-m-accessibility-standards.html
index 65cec0b..5fccf61 100644
--- a/html/docs/appendix-m-accessibility-standards.html
+++ b/html/docs/appendix-m-accessibility-standards.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
@@ -651,5 +651,6 @@ 
        10. Official References
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-m-vscode-accessibility-reference.html b/html/docs/appendix-m-vscode-accessibility-reference.html
deleted file mode 100644
index 9139bd8..0000000
--- a/html/docs/appendix-m-vscode-accessibility-reference.html
+++ /dev/null
@@ -1,1786 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix M: VS Code Accessibility Reference - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Appendix M: 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.
        
-
        
-
        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
        
-
        
-
        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. 
-
        
-
        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.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.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.
        
-
        7. Settings.json Configuration Examples
        
-
        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
-}
        
-
        Back to: VS Code Setup & Accessibility Basics | GitHub Copilot | Accessibility Agents
        Related: Appendix B: Screen Reader Cheat Sheet
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-n-advanced-search.html b/html/docs/appendix-n-advanced-search.html
index 2d03228..905cb6b 100644
--- a/html/docs/appendix-n-advanced-search.html
+++ b/html/docs/appendix-n-advanced-search.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
@@ -489,5 +489,6 @@ 
        Example bookmarkable URL
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-n-github-codespaces.html b/html/docs/appendix-n-github-codespaces.html
deleted file mode 100644
index c1827e6..0000000
--- a/html/docs/appendix-n-github-codespaces.html
+++ /dev/null
@@ -1,424 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix N: GitHub Codespaces - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Appendix N: 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.
        
-
        
-
        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.
        
-
        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
          • 
-
        
-
        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.
        
-
        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.
        
-
        Return to: Resources | Appendix M - VS Code Accessibility Reference | Appendix A - Glossary
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-o-branch-protection.html b/html/docs/appendix-o-branch-protection.html
index d9d7f8e..4305b04 100644
--- a/html/docs/appendix-o-branch-protection.html
+++ b/html/docs/appendix-o-branch-protection.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
@@ -464,5 +464,6 @@ 
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-o-github-mobile.html b/html/docs/appendix-o-github-mobile.html
deleted file mode 100644
index 4d750a7..0000000
--- a/html/docs/appendix-o-github-mobile.html
+++ /dev/null
@@ -1,371 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix O: GitHub Mobile - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Appendix O: 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.
        
-
        
-
        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.
        
-
        
-
        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.
        
-
        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.
        
-
        Return to: Resources | Appendix B - Screen Reader Cheat Sheet | Appendix A - Glossary
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-p-github-pages.html b/html/docs/appendix-p-github-pages.html
deleted file mode 100644
index 1cbdae9..0000000
--- a/html/docs/appendix-p-github-pages.html
+++ /dev/null
@@ -1,381 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix P: Publishing with GitHub Pages - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Appendix P: 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.
        
-
        
-
        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.
        
-
        
-
        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:
        
-
-
        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.
        
-
        Return to: Resources | Appendix E - GitHub Flavored Markdown | Appendix A - Glossary
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-p-security-features.html b/html/docs/appendix-p-security-features.html
index 1ce36c4..9791139 100644
--- a/html/docs/appendix-p-security-features.html
+++ b/html/docs/appendix-p-security-features.html
@@ -4,7 +4,7 @@
   
   
   
-  appendix-p-security-features - GIT Going with GitHub
+  Appendix P: GitHub Security Features - GIT Going with GitHub
   
   
   
@@ -28,7 +28,7 @@
   
   
        
-    
        # Appendix P: GitHub Security Features
        
+    
        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.
        
+
        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
        
@@ -209,7 +209,7 @@ 
        Push Protection (Real-Time Prevent
 
        If your push is blocked:
        
 
        remote: error: GH013: Repository rule violations found for refs/heads/main.
 remote: Push cannot contain secrets
-remote: 
+remote:
 remote: - commit: abc123 in file: config.js
 remote:   secret: GitHub Personal Access Token
 remote:   location: line 5
        
@@ -412,5 +412,6 @@ 
        Sample output
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-q-actions-workflows.html b/html/docs/appendix-q-actions-workflows.html
index 35c9e3b..6254dcb 100644
--- a/html/docs/appendix-q-actions-workflows.html
+++ b/html/docs/appendix-q-actions-workflows.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
@@ -716,5 +716,6 @@ 
        Day 2 Bridge - From Ac
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-q-github-actions-workflows.html b/html/docs/appendix-q-github-actions-workflows.html
deleted file mode 100644
index 25228c0..0000000
--- a/html/docs/appendix-q-github-actions-workflows.html
+++ /dev/null
@@ -1,621 +0,0 @@
-
-
-
-  
-  
-  
-  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.
        
-
        
-
        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.
        
-
        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.
          • 
-
        
-
        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.
        
-
        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 the 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.
        
-
        
-
        Back: GitHub Concepts and Glossary
-Related: Day 1 Agenda | Day 2 Agenda
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-r-github-profile-sponsors-wikis.html b/html/docs/appendix-r-github-profile-sponsors-wikis.html
deleted file mode 100644
index 9bdff4d..0000000
--- a/html/docs/appendix-r-github-profile-sponsors-wikis.html
+++ /dev/null
@@ -1,221 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix R: GitHub Profile, Sponsors, and Wikis - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Appendix R: GitHub Profile, 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).
        
-
        
-
        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
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-r-projects-deep-dive.html b/html/docs/appendix-r-projects-deep-dive.html
index 8deff9f..0be189b 100644
--- a/html/docs/appendix-r-projects-deep-dive.html
+++ b/html/docs/appendix-r-projects-deep-dive.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
@@ -533,5 +533,6 @@ 
        Exercise 4: Cross-Repo Project (
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-s-github-organizations-templates.html b/html/docs/appendix-s-github-organizations-templates.html
deleted file mode 100644
index ee76b96..0000000
--- a/html/docs/appendix-s-github-organizations-templates.html
+++ /dev/null
@@ -1,213 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix S: Organizations, Templates, and Repository Settings - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Appendix S: Organizations, Templates, and Repository Settings
        
-
        
-
        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).
        
-
        
-
        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
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-s-releases-tags-insights.html b/html/docs/appendix-s-releases-tags-insights.html
index 56e8db6..fb61aa8 100644
--- a/html/docs/appendix-s-releases-tags-insights.html
+++ b/html/docs/appendix-s-releases-tags-insights.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
@@ -640,5 +640,6 @@ 
        /team-dashboard
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-t-community-and-social.html b/html/docs/appendix-t-community-and-social.html
index 9d42f8f..5747b1f 100644
--- a/html/docs/appendix-t-community-and-social.html
+++ b/html/docs/appendix-t-community-and-social.html
@@ -69,7 +69,7 @@ 
        Appendix T: Community and Social
        
 
        
 
        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.
        
+
        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
        
 
        
@@ -255,7 +255,7 @@ 
        Wiki Accessibility
        
 
        
 
        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.
        
+
        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
        
 
        
@@ -960,5 +960,6 @@ 
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-t-contributing-to-open-source.html b/html/docs/appendix-t-contributing-to-open-source.html
deleted file mode 100644
index f35df9a..0000000
--- a/html/docs/appendix-t-contributing-to-open-source.html
+++ /dev/null
@@ -1,213 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix T: Contributing to Open Source - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Appendix T: Contributing to Open Source
        
-
        
-
        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.
        
-
        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
        
-
        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.
          • 
-
        
-
        Return to: Resources | Appendix A - Glossary
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-u-discussions-and-gists.html b/html/docs/appendix-u-discussions-and-gists.html
index 3974df4..97fce34 100644
--- a/html/docs/appendix-u-discussions-and-gists.html
+++ b/html/docs/appendix-u-discussions-and-gists.html
@@ -69,7 +69,7 @@ 
        Appendix U: Discussions and Gists
        
 
        
 
        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.
        
+
        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
        
 
        
@@ -332,7 +332,7 @@ 
        10. Accessibility Agents
 
        
 
        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.
        
+
        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
        
 
        
@@ -634,5 +634,6 @@ 
        Deleting a Gist
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-u-resources.html b/html/docs/appendix-u-resources.html
deleted file mode 100644
index a446ad9..0000000
--- a/html/docs/appendix-u-resources.html
+++ /dev/null
@@ -1,1455 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix U: Resources - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Appendix U: 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.
        
-
        
-
        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.
        
-
        
-
        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
        
-
        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 advocate14-accessible-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/01-understanding-github-web-structure.md
        Navigating repositoriesdocs/02-navigating-repositories.md
        The Learning Roomdocs/03-the-learning-room.md
        Working with issuesdocs/04-working-with-issues.md
        Working with pull requestsdocs/06-working-with-pull-requests.md
        Merge conflictsdocs/07-merge-conflicts.md
        Culture and etiquettedocs/08-culture-etiquette.md
        Labels, milestones, projectsdocs/09-labels-milestones-projects.md
        Notificationsdocs/10-notifications.md
        Day 1 agendaDAY1_AGENDA.md
        Day 2 agendaDAY2_AGENDA.md
        VS Code: Setup & Accessibility Basicsdocs/05-vscode-accessibility.md
        VS Code: Git & Source Controldocs/11-git-source-control.md
        VS Code: GitHub Pull Requests Extensiondocs/12-github-pull-requests-extension.md
        VS Code: GitHub Copilotdocs/13-github-copilot.md
        Accessible Code Reviewdocs/14-accessible-code-review.md
        Issue Templatesdocs/15-issue-templates.md
        VS Code: Accessibility Agentsdocs/16-accessibility-agents.md
        Resources (this file)docs/appendix-u-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-c-accessibility-standards.md
        Appendix D: Git Authenticationdocs/appendix-d-git-authentication.md
        Appendix E: GitHub Flavored Markdowndocs/appendix-e-github-flavored-markdown.md
        Appendix F: GitHub Gistsdocs/appendix-f-github-gists.md
        Appendix G: GitHub Discussionsdocs/appendix-g-github-discussions.md
        Appendix H: Releases, Tags, and Repository Insightsdocs/appendix-h-releases-tags-insights.md
        Appendix I: GitHub Projects Deep Divedocs/appendix-i-github-projects.md
        Appendix J: GitHub Advanced Searchdocs/appendix-j-advanced-search.md
        Appendix K: Branch Protection Rules and Repository Rulesetsdocs/appendix-k-branch-protection-rulesets.md
        Appendix L: GitHub Security Featuresdocs/appendix-l-github-security-features.md
        Appendix M: VS Code Accessibility Referencedocs/appendix-m-vscode-accessibility-reference.md
        Appendix N: GitHub Codespacesdocs/appendix-n-github-codespaces.md
        Appendix O: GitHub Mobiledocs/appendix-o-github-mobile.md
        Appendix P: Publishing with GitHub Pagesdocs/appendix-p-github-pages.md
        Appendix Q: GitHub Actions and Workflowsdocs/appendix-q-github-actions-workflows.md
        Appendix R: GitHub Profile, Sponsors, and Wikisdocs/appendix-r-github-profile-sponsors-wikis.md
        Appendix S: Organizations, Templates, and Repository Settingsdocs/appendix-s-github-organizations-templates.md
        Appendix T: Contributing to Open Sourcedocs/appendix-t-contributing-to-open-source.md
        Appendix U: Resources (this file)docs/appendix-u-resources.md
        Appendix V: Accessibility Agents Referencedocs/appendix-v-accessibility-agents-reference.md
        Appendix W: GitHub Copilot Referencedocs/appendix-w-github-copilot-reference.md
        Appendix X: GitHub Copilot AI Modelsdocs/appendix-x-copilot-models.md
        
-
        Back: Issue Templates
-Start over: README ←
-Reference: Screen Reader Cheat Sheet
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-v-accessibility-agents-reference.html b/html/docs/appendix-v-accessibility-agents-reference.html
deleted file mode 100644
index 8e4bfc5..0000000
--- a/html/docs/appendix-v-accessibility-agents-reference.html
+++ /dev/null
@@ -1,1927 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix V: Accessibility Agents Reference - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Appendix V: 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.
        
-
        
-
        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 16: Accessibility Agents. For Copilot keyboard shortcuts and Chat features, see Appendix W: 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
        
-
        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.
          • 
-
        
-
        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
        
-
          
-
        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.
        
-
        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.
        
-
        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
          • 
-
        
-
        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 W: GitHub Copilot & 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/
        
-
        Chapter: Accessibility Agents
-Related: Appendix W: GitHub Copilot Reference | Issue Templates | Chapter 13: GitHub Copilot
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-v-github-mobile.html b/html/docs/appendix-v-github-mobile.html
index 6a2a43f..c9709f3 100644
--- a/html/docs/appendix-v-github-mobile.html
+++ b/html/docs/appendix-v-github-mobile.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
@@ -435,5 +435,6 @@ 
        GitHub Mobile crashes or freezes
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-w-github-copilot-reference.html b/html/docs/appendix-w-github-copilot-reference.html
deleted file mode 100644
index 6437cc2..0000000
--- a/html/docs/appendix-w-github-copilot-reference.html
+++ /dev/null
@@ -1,1673 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix W: GitHub Copilot & Agentic Reference - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Appendix W: GitHub Copilot & Agentic Reference
        
-
        
-
        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 13: GitHub Copilot. For Accessibility Agents specifically, see Appendix V: 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 V 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.
        
-
        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
        
-
        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
          • 
-
        
-
        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/
        
-
        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. The feature is in early development and may change significantly. Use with careful human supervision. See the official documentation and source repository (open source, MIT).
        
-
        
-
        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 V for the full Accessibility Agents reference.
        
-
        
-
        Chapter: GitHub Copilot
-Related: Appendix V: Accessibility Agents Reference | Appendix M: VS Code Accessibility Reference | Appendix X: AI Models Reference
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-w-github-pages.html b/html/docs/appendix-w-github-pages.html
index b0c81df..3c25784 100644
--- a/html/docs/appendix-w-github-pages.html
+++ b/html/docs/appendix-w-github-pages.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
@@ -445,5 +445,6 @@ 
        Screen reader announces wrong
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-x-copilot-models.html b/html/docs/appendix-x-copilot-models.html
deleted file mode 100644
index 9a6b7ea..0000000
--- a/html/docs/appendix-x-copilot-models.html
+++ /dev/null
@@ -1,570 +0,0 @@
-
-
-
-  
-  
-  
-  Appendix X: GitHub Copilot AI Models Reference - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Appendix X: GitHub Copilot AI Models Reference
        
-
        
-
        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 February 2026. For the latest additions and retirements, see the GitHub Copilot changelog and GitHub's official supported models documentation.
        
-
        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×
        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×
        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.
        
-
        
-
        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
        
-
        Models marked with a premium multiplier consume premium requests proportionally. For example, Claude Opus 4.6 (3× multiplier) uses 3 premium requests per message. Free models (0× multiplier) never consume premium requests.
        
-
        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 use GPT-5.1-Codex-Max or GPT-5.2-Codex
          • 
-
        
-
        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 February 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
          • 
-
        
-
        To stay current, watch the GitHub Copilot changelog - model additions and retirements are announced there.
        
-
-
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-x-resources.html b/html/docs/appendix-x-resources.html
index 2501f81..5054fcc 100644
--- a/html/docs/appendix-x-resources.html
+++ b/html/docs/appendix-x-resources.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
@@ -1516,5 +1516,6 @@ 
        Quick Navigation
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-y-accessing-workshop-materials.html b/html/docs/appendix-y-accessing-workshop-materials.html
deleted file mode 100644
index ca66848..0000000
--- a/html/docs/appendix-y-accessing-workshop-materials.html
+++ /dev/null
@@ -1,273 +0,0 @@
-
-
-
-  
-  
-  
-  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.
        
-
        
-
        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.
        
-
        
-
        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/Learning-Room.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 25 appendices (A-Y)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
        
-
        Return to: Appendix X - Copilot AI Models | Appendix A - Glossary | README
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-y-workshop-materials.html b/html/docs/appendix-y-workshop-materials.html
index fb4c556..882fa80 100644
--- a/html/docs/appendix-y-workshop-materials.html
+++ b/html/docs/appendix-y-workshop-materials.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
@@ -337,5 +337,6 @@ 
        Learning Cards: Choosing the R
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/appendix-z-github-skills-catalog.html b/html/docs/appendix-z-github-skills-catalog.html
deleted file mode 100644
index d7d4b39..0000000
--- a/html/docs/appendix-z-github-skills-catalog.html
+++ /dev/null
@@ -1,755 +0,0 @@
-
-
-
-  
-  
-  
-  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.
        
-
        
-
        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.
        
-
        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.
        
-
        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
        
-
-
        Last updated: March 2026
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/docs/appendix-z-github-skills.html b/html/docs/appendix-z-github-skills.html
index adbc65a..d0e3f62 100644
--- a/html/docs/appendix-z-github-skills.html
+++ b/html/docs/appendix-z-github-skills.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
@@ -818,5 +818,6 @@ 
        Additional Resources
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/course-guide.html b/html/docs/course-guide.html
index 8e76e2b..7a058c3 100644
--- a/html/docs/course-guide.html
+++ b/html/docs/course-guide.html
@@ -60,7 +60,7 @@
   
        
     
        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.
        
+
        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
        
 
        
@@ -69,11 +69,18 @@ 
        GitHub Learning
 
        
 
        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. By the end of Day 1, you will have filed issues, opened pull requests, reviewed someone else's work, and resolved a merge conflict - all in the 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. By the end of Day 2, your name is in the commit history of a real open source accessibility project.
        
+
        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
@@ -87,9 +94,10 @@ 
        The Journey Arc
        
 
 Day 2 - Deepen with VS Code + Accessibility Agents
   VS Code basics → Copilot inline → Copilot Chat
-  @daily-briefing → @issue-tracker → @pr-review → @analytics → ship upstream
        
+  @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
        • 
@@ -102,7 +110,7 @@ 
        Before You Begin
        
 
        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.
        
 
@@ -118,6 +126,12 @@ 
        Day 1: GitHub Foundations
        
 
 
 
+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
@@ -184,7 +198,7 @@ 
        Day 1: GitHub Foundations
        
 30 min
 
 
-
        Day 1 Total: ~8 hours of structured time
        
+
        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.
        
 
@@ -263,7 +277,7 @@ 
        Day 2: VS Code + Accessibility Agen
 
        30 min
 
        
 
        
-
        Day 2 Total: ~10 hours of structured time
        
+
        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)
        
@@ -571,17 +585,17 @@ 
        Getting Help
        
 
 
 
-FAQ
+FAQ
 Answers to common questions
 When you have a question about the workshop, GitHub, or screen readers
 
 
-Troubleshooting
+Troubleshooting
 Step-by-step solutions to common problems
 When something is not working
 
 
-Quick Reference
+Quick Reference
 Condensed shortcuts and commands
 When you need a keyboard shortcut or command fast
 
@@ -634,7 +648,7 @@ 
        Workshop at a Glance
        
 
 Outcome
 You can use GitHub independently
-Your name is in a real project's commit history
+You have a real contribution path and review process
 
 
 Time
@@ -650,5 +664,6 @@ 
        Workshop at a Glance
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/get-going.html b/html/docs/get-going.html
new file mode 100644
index 0000000..6eba071
--- /dev/null
+++ b/html/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/docs/solutions/solution-01-scavenger-hunt.html b/html/docs/solutions/solution-01-scavenger-hunt.html
index bb1beb9..ddd3361 100644
--- a/html/docs/solutions/solution-01-scavenger-hunt.html
+++ b/html/docs/solutions/solution-01-scavenger-hunt.html
@@ -96,5 +96,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-02-first-issue.html b/html/docs/solutions/solution-02-first-issue.html
index 1f49707..f704e39 100644
--- a/html/docs/solutions/solution-02-first-issue.html
+++ b/html/docs/solutions/solution-02-first-issue.html
@@ -93,5 +93,6 @@ 
        Alternate approaches
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-03-conversation.html b/html/docs/solutions/solution-03-conversation.html
index f3f77d3..5eb8704 100644
--- a/html/docs/solutions/solution-03-conversation.html
+++ b/html/docs/solutions/solution-03-conversation.html
@@ -91,5 +91,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-04-branch-out.html b/html/docs/solutions/solution-04-branch-out.html
index 855d6eb..fbdac7e 100644
--- a/html/docs/solutions/solution-04-branch-out.html
+++ b/html/docs/solutions/solution-04-branch-out.html
@@ -98,5 +98,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-05-make-your-mark.html b/html/docs/solutions/solution-05-make-your-mark.html
index 7190e83..b352af8 100644
--- a/html/docs/solutions/solution-05-make-your-mark.html
+++ b/html/docs/solutions/solution-05-make-your-mark.html
@@ -96,5 +96,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-06-first-pr.html b/html/docs/solutions/solution-06-first-pr.html
index 3ef50ef..1fa7bd1 100644
--- a/html/docs/solutions/solution-06-first-pr.html
+++ b/html/docs/solutions/solution-06-first-pr.html
@@ -105,5 +105,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-07-merge-conflict.html b/html/docs/solutions/solution-07-merge-conflict.html
index 198e413..b585e3a 100644
--- a/html/docs/solutions/solution-07-merge-conflict.html
+++ b/html/docs/solutions/solution-07-merge-conflict.html
@@ -64,7 +64,7 @@ 
        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
        
@@ -77,7 +77,7 @@ 
        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):
        
@@ -113,5 +113,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-08-culture.html b/html/docs/solutions/solution-08-culture.html
index f67ed23..7849b02 100644
--- a/html/docs/solutions/solution-08-culture.html
+++ b/html/docs/solutions/solution-08-culture.html
@@ -87,5 +87,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-09-merge-day.html b/html/docs/solutions/solution-09-merge-day.html
index 0fc8e74..9cde86d 100644
--- a/html/docs/solutions/solution-09-merge-day.html
+++ b/html/docs/solutions/solution-09-merge-day.html
@@ -96,5 +96,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-10-go-local.html b/html/docs/solutions/solution-10-go-local.html
index 9d3b442..6f18600 100644
--- a/html/docs/solutions/solution-10-go-local.html
+++ b/html/docs/solutions/solution-10-go-local.html
@@ -114,5 +114,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-11-day2-pr.html b/html/docs/solutions/solution-11-day2-pr.html
index 3e4c99c..97a9b33 100644
--- a/html/docs/solutions/solution-11-day2-pr.html
+++ b/html/docs/solutions/solution-11-day2-pr.html
@@ -120,5 +120,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-12-review.html b/html/docs/solutions/solution-12-review.html
index 8df1de1..b6ab911 100644
--- a/html/docs/solutions/solution-12-review.html
+++ b/html/docs/solutions/solution-12-review.html
@@ -94,5 +94,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-13-copilot.html b/html/docs/solutions/solution-13-copilot.html
index 3a55553..0785edb 100644
--- a/html/docs/solutions/solution-13-copilot.html
+++ b/html/docs/solutions/solution-13-copilot.html
@@ -95,5 +95,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-14-template.html b/html/docs/solutions/solution-14-template.html
index 9a39ad0..ff2b3ad 100644
--- a/html/docs/solutions/solution-14-template.html
+++ b/html/docs/solutions/solution-14-template.html
@@ -178,5 +178,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-15-agents.html b/html/docs/solutions/solution-15-agents.html
index acd8585..5fa5cc2 100644
--- a/html/docs/solutions/solution-15-agents.html
+++ b/html/docs/solutions/solution-15-agents.html
@@ -92,5 +92,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-16-capstone.html b/html/docs/solutions/solution-16-capstone.html
index e9d1ec7..adf205b 100644
--- a/html/docs/solutions/solution-16-capstone.html
+++ b/html/docs/solutions/solution-16-capstone.html
@@ -141,5 +141,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-bonus-a.html b/html/docs/solutions/solution-bonus-a.html
index a51296e..0ca8692 100644
--- a/html/docs/solutions/solution-bonus-a.html
+++ b/html/docs/solutions/solution-bonus-a.html
@@ -83,5 +83,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-bonus-b.html b/html/docs/solutions/solution-bonus-b.html
index e00f4dc..70b0773 100644
--- a/html/docs/solutions/solution-bonus-b.html
+++ b/html/docs/solutions/solution-bonus-b.html
@@ -111,5 +111,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-bonus-c.html b/html/docs/solutions/solution-bonus-c.html
index 5b5bb92..f42c33b 100644
--- a/html/docs/solutions/solution-bonus-c.html
+++ b/html/docs/solutions/solution-bonus-c.html
@@ -96,5 +96,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-bonus-d.html b/html/docs/solutions/solution-bonus-d.html
index cd73b7b..407ca4d 100644
--- a/html/docs/solutions/solution-bonus-d.html
+++ b/html/docs/solutions/solution-bonus-d.html
@@ -100,5 +100,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/solutions/solution-bonus-e.html b/html/docs/solutions/solution-bonus-e.html
index 370e0ec..87e0131 100644
--- a/html/docs/solutions/solution-bonus-e.html
+++ b/html/docs/solutions/solution-bonus-e.html
@@ -101,5 +101,6 @@ 
        What matters
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/docs/student-onboarding.html b/html/docs/student-onboarding.html
index b525b50..91da72f 100644
--- a/html/docs/student-onboarding.html
+++ b/html/docs/student-onboarding.html
@@ -140,5 +140,6 @@ 
        Getting Help
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/facilitator/FACILITATOR_GUIDE.html b/html/facilitator/FACILITATOR_GUIDE.html
deleted file mode 100644
index 8416c42..0000000
--- a/html/facilitator/FACILITATOR_GUIDE.html
+++ /dev/null
@@ -1,392 +0,0 @@
-
-
-
-  
-  
-  
-  Facilitator Guide and Workshop Timeline - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Facilitator Guide and Workshop Timeline
        
-
        Facilitator Team
        
-
          
-
        • Jeff Bishop -- lead facilitator, maintainer of Accessibility Agents
          • 
-
        • Michael Babcock -- co-facilitator
          • 
-
        
-
        Both facilitators run all sessions together. "The facilitator" or "your facilitator" in this guide refers to whichever of the two is leading a given moment; either can step in for the other on any task in this guide.
        
-
        Overview
        
-
        This is a two-day workshop designed for blind and low-vision students learning GitHub through hands-on collaboration. Each day runs approximately 8 hours with structured sessions and flexible working time.
        
-
        Format: Hybrid (streaming + individual GitHub Classroom repos)
-Main Goal: Get every student to merge their first pull request
        
-
        
-
        Deployment note: For setup instructions, see classroom/README.md.
-Each student receives their own private repository through GitHub Classroom.
-The Aria bot and student-progression workflow handle challenge delivery and feedback automatically.
        
-
        
-
        Before the Workshop (Day Before)
        
-
        Facilitator Checklist
        
-
          
-
        •   Verify GitHub Classroom roster is complete (all students accepted invite links)
          • 
-
        •   Confirm both assignments are published and invite links work
          • 
-
        •   Test Aria bot validation by submitting a practice PR in a test repo
          • 
-
        •   Verify student-progression workflow triggers correctly (close Challenge 1, see Challenge 2 appear)
          • 
-
        •   Share meeting link and reminder email with:
            
-
          • Video call link + audio-only option
            • 
-
          • Pre-workshop setup reminder (see docs/00-pre-workshop-setup.md)
            • 
-
          • FAQ: "What if I get stuck?"
            • 
-
          • Office hours/emergency contact info
            • 
-
          
-
          • 
-
        
-
        Verify Infrastructure
        
-
        Use the GitHub Classroom dashboard to confirm:
        
-
          
-
        1. All students have accepted their assignment invite links
          2. 
-
        2. Each student's private repo was created successfully
          3. 
-
        3. Challenge 1 issue exists in each student repo (auto-created on acceptance)
          4. 
-
        
-
        Test the automation by opening a PR in one student repo and confirming:
        
-
          
-
        • Aria bot comments with feedback within 30 seconds
          • 
-
        • Closing Challenge 1 issue triggers Challenge 2 to appear
          • 
-
        
-
        Day 1: GitHub Orientation and First Pull Request
        
-
        Hour 1: Welcome and GitHub Orientation (60 min)
        
-
        Facilitator Role:
        
-
          
-
        • Create welcoming opening acknowledging everyone's accessibility needs
          • 
-
        • Explain why GitHub matters for blind/low-vision inclusion
          • 
-
        • Demonstrate: "I'm going to open the repo right now and you'll follow along"
          • 
-
        • Q&A in chat -- answer every question
          • 
-
        
-
        What Students Do:
        
-
          
-
        • Join the video call with screen reader
          • 
-
        • Open GitHub in their browser
          • 
-
        • Navigate to their private repo (created by GitHub Classroom)
          • 
-
        • Confirm they can see their first challenge issue
          • 
-
        
-
        Resources to Have Ready:
        
-
          
-
        • Screen reader cheatsheet (Appendix B)
          • 
-
        • Common GitHub.com keyboard shortcuts
          • 
-
        • Chat moderator who watches for questions
          • 
-
        
-
        Success Metric: All students report "I found my issue"
        
-
        Hour 2: Demo -- Your First PR (30 min)
        
-
        You (facilitator) will:
        
-
          
-
        1. Show a completed example on screen with narration
          2. 
-
        2. Walk through EVERY step:
            
-
          • "First, I click the edit pencil"
            • 
-
          • "I see the markdown editor open"
            • 
-
          • "I make my change here"
            • 
-
          • "I scroll down and create a new branch"
            • 
-
          • "Now I click 'Propose changes' button"
            • 
-
          • "GitHub shows me the PR preview -- notice the Aria bot already right here checking my work"
            • 
-
          • "I fill in the PR template fields"
            • 
-
          • "I click 'Create Pull Request'"
            • 
-
          • "Aria comments within 30 seconds with feedback"
            • 
-
          • "I address the feedback and push an update commit"
            • 
-
          • "I request review by typing @peer_username"
            • 
-
          • "My peer reviews and I get approval"
            • 
-
          • "I click merge button"
            • 
-
          • "Done! My PR is merged!"
            • 
-
          
-
          3. 
-
        
-
        This is the workflow EVERY student will repeat. Make it crystal clear.
        
-
        Success Metric: Students report "I see how this works" in chat
        
-
        Hours 2-6: Working Session (approx. 4.5 hours)
        
-
        Students work independently on challenges in their own repos.
        
-
        This is THE MAIN ENGAGEMENT. They're making their first real contribution. When a student closes a challenge issue, the student-progression workflow automatically opens the next one.
        
-
        Facilitator Role:
        
-
          
-
        • Monitor the GitHub Classroom dashboard for student progress
          • 
-
        • Check individual student repos for PR comments and questions
          • 
-
        • Respond quickly to blockers
          • 
-
        • Celebrate each merged PR in chat
          • 
-
        
-
        Expected Cadence:
        
-
          
-
        • First hour -- Students opening issues, starting edits (expect early PRs from fast movers)
          • 
-
        • Second hour -- Aria bot feedback flowing, students making fixes
          • 
-
        • Third hour -- Reviews happening, merges happening, progression bot unlocking new challenges
          • 
-
        • Fourth hour -- Stragglers finishing, peer reviews catching up
          • 
-
        
-
        Facilitator Interventions:
        
-
        If a student hasn't opened a PR after the first hour:
        
-
          
-
        • Message them: "Hey @student! Need help getting started? Check your Issues tab for your current challenge."
          • 
-
        • Keep it low-pressure -- some students will take longer
          • 
-
        
-
        If Aria gives critical feedback:
        
-
          
-
        • Explain what the bot meant in plain language
          • 
-
        • Show the fix clearly
          • 
-
        • Make sure the student isn't discouraged
          • 
-
        
-
        If a peer review isn't happening:
        
-
          
-
        • Offer to do a facilitator review instead
          • 
-
        • Or ask another student: "Can you review this PR?"
          • 
-
        • Priority is getting to merge, not strict peer review
          • 
-
        
-
        Celebrate Merges:
-Post in the chat or discussion when a student merges their first PR. Public recognition matters.
        
-
        Hour 7: Q&A and Reflection (30 min)
        
-
        Prompt for Discussion:
        
-
        
-
        "Tell us in chat: What was one thing you learned today about GitHub?"
        
-
        
-
        Be ready to:
        
-
          
-
        • Answer "I got an error..." questions
          • 
-
        • Help troubleshoot remaining issues
          • 
-
        • Give credit to peer reviewers
          • 
-
        • Mark students who didn't finish but are close as "follow-up needed"
          • 
-
        
-
        Send them home with:
        
-
          
-
        • Tomorrow's agenda
          • 
-
        • Sneak peek at what's next (VS Code, local Git, advanced challenges)
          • 
-
        • Encouragement!
          • 
-
        
-
        Hour 8: Office Hours (Optional)
        
-
          
-
        • Available for 1:1 troubleshooting
          • 
-
        • Help students finish PRs
          • 
-
        • Answer "How do I...?" questions about GitHub
          • 
-
        • Document common questions for tomorrow's content
          • 
-
        
-
        Day 2: Deeper Skills and Celebration
        
-
        Hour 1: Recap and Wins (30 min)
        
-
        Facilitator:
        
-
          
-
        • Show stats from the GitHub Classroom dashboard: "X students, Y PRs merged on Day 1"
          • 
-
        • Acknowledge students who got stuck but persisted
          • 
-
        • Introduce the Day 2 assignment (students accept the second invite link)
          • 
-
        
-
        
-
        Students accept the Day 2 assignment invite link now.
-The student-progression workflow begins delivering Challenge 10 onwards.
        
-
        
-
        Hour 2: Deep Dive -- Code Review (60 min)
        
-
        Teach:
        
-
          
-
        • How to review someone else's PR
          • 
-
        • What good feedback looks like
          • 
-
        • How to incorporate feedback gracefully
          • 
-
        • Real-world code review practices
          • 
-
        
-
        Paired Activity:
        
-
          
-
        • Have students review each other's Day 1 PRs
          • 
-
        • Start with example feedback you provide
          • 
-
        • Let them practice the async review process
          • 
-
        
-
        Hours 3-7: Skill-Building Challenges (approx. 4.5 hours)
        
-
        Students work through progressively harder challenges delivered by the progression bot:
        
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
        TrackChallengesTopics
        Core Day 210-13VS Code, Git basics, local commits, code review
        Advanced14-16Issue templates, fork-and-contribute, capstone agent
        Bonusbonus-a through bonus-eAdvanced search, branch protection, GitHub CLI, cloud editors
        
-
        Challenges unlock automatically as students close issues. Faster students will reach bonus challenges; slower students may still be working through core content. Both paces are valid.
        
-
        Aria Bot Enhances:
        
-
          
-
        • Accessibility feedback becomes more detailed on later challenges
          • 
-
        • Highlights larger patterns ("You capitalized but others use lowercase")
          • 
-
        • Suggests improvements, not just fixes
          • 
-
        
-
        Facilitator Role:
        
-
          
-
        • Use the Classroom dashboard to track who's advancing through challenges
          • 
-
        • Give encouragement to students on later challenges
          • 
-
        • Help students with merge conflict resolution (Challenge 7 / autograder)
          • 
-
        • Keep the energy positive
          • 
-
        
-
        Hour 7: Final Q&A and Celebration (60 min)
        
-
        Metrics to share (pull from Classroom dashboard):
        
-
          
-
        • Total students enrolled
          • 
-
        • PRs merged (track real number)
          • 
-
        • Students who completed multiple challenges
          • 
-
        • Students who completed the code review cycle
          • 
-
        • Accessibility wins -- screen readers worked throughout
          • 
-
        
-
        Next Steps:
        
-
          
-
        • Point them to CONTRIBUTING.md in their favorite open source projects
          • 
-
        • Share list of "good first issue" finding techniques
          • 
-
        • Give them the resources appendices
          • 
-
        • Offer alumni community channel
          • 
-
        
-
        Hour 8: Informal Hangout (60 min)
        
-
          
-
        • Students hang out on the call
          • 
-
        • Chat with peers and facilitators
          • 
-
        • Ask follow-up questions
          • 
-
        • Exchange GitHub usernames
          • 
-
        
-
        Facilitator Role Critical Points
        
-
        Communication Style
        
-
        DO:
        
-
          
-
        • Use simple language: "Click the pencil icon to edit"
          • 
-
        • Narrate exactly what you're doing: "I'm clicking... now I'm typing..."
          • 
-
        • Normalize mistakes: "Oops I forgot something - let me fix it"
          • 
-
        • Celebrate effort not just success: "Nice work thinking through that!"
          • 
-
        • Answer the same question multiple times patiently
          • 
-
        
-
        DON'T:
        
-
          
-
        • Use "obviously" or assume prior knowledge
          • 
-
        • Assume everyone is on the same screen area
          • 
-
        • Rush through demos
          • 
-
        • Make anyone feel bad about getting stuck
          • 
-
        • Focus on speed - focus on understanding
          • 
-
        
-
        Responding to Common Issues
        
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
        Student SaysYour Response
        "I can't see my assignment issue"Have them go to Issues tab, filter by Assignee > Me, or give direct link
        "The bot is confusing me"Ask what part confused them, then explain in plain language
        "I don't know what [jargon] means"Explain, then add it to glossary so next student finds it
        "I accidentally merged the wrong thing"No big deal - revert commit, explain it, move on
        "My screen reader stops at the file picker"Have them use keyboard: Tab to button, Space to open, Type filename
        "I'm done - what's next?"Option 1: Do another challenge. Option 2: Review someone's PR. Option 3: Help a peer.
        
-
        End of Workshop Facilitator Duties
        
-
          
-
        1. Export metrics - Use progress tracker to generate final report
          2. 
-
        2. Write thank you email - Personal note to each student (use template)
          3. 
-
        3. Create alumni channel - Slack/Discord for ongoing support
          4. 
-
        4. Document what worked - Feedback for next workshop
          5. 
-
        5. Tag students in commit credit - Add to CONTRIBUTORS file
          6. 
-
        
-
        Emergency Protocols
        
-
        Bot stops responding to PRs
        
-
          
-
        • Check GitHub Actions status page
          • 
-
        • Manually review PRs and comment with feedback format bot would use
          • 
-
        • Post in Discussions: "Facing technical issue, we'll handle this manually"
          • 
-
        
-
        Student GitHub account locked
        
-
          
-
        • Have them reset password via GitHub
          • 
-
        • Or create temporary escalation issue for them to move forward
          • 
-
        
-
        Video call connectivity issues
        
-
          
-
        • Have phone dial-in number as backup
          • 
-
        • Offer to continue in Discussions if needed
          • 
-
        • Record session for students who lose connection
          • 
-
        
-
        Workshop needs to end early
        
-
          
-
        • Stop at natural break point
          • 
-
        • Students can continue async after
          • 
-
        • No one forced offline mid-PR
          • 
-
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/index.html b/html/index.html
deleted file mode 100644
index 9a41d1e..0000000
--- a/html/index.html
+++ /dev/null
@@ -1,393 +0,0 @@
-
-
-
-  
-  
-  
-  GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        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 during the week of March 7, 2026. 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.
        
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
        DetailInformation
        DatesSaturday, March 7 & Sunday, March 8, 2026
        Time12:00 PM - 8:00 PM Eastern (both days)
        LocationOnline via Zoom
        CostFree
        Presented byCommunity Access
        In partnership withGitHub
        
-
        Registration is now closed. Thank you to everyone who registered - let the learning begin!
        
-
        
-
        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 March 7. 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, your name will be in the commit history of a live, public open source project. Not a sandbox. Not a simulation. The real thing.
        
-
        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. By the end of the workshop, your name is in its commit history.
        
-
        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.
        
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
        BlockWhat Happens
        Welcome and Setup CheckIntroductions, verify everyone's screen reader and browser are ready
        Screen Reader Orientation to GitHubNavigate GitHub pages using headings, landmarks, and keyboard shortcuts
        Navigating RepositoriesExplore a real repository - files, branches, commits, contributors
        Working with IssuesSearch, file, comment on, and triage issues using Markdown
        Understanding Pull RequestsRead diffs, write inline review comments, approve and merge
        Your First Contribution SprintMake a real contribution to the shared practice repository - with automated bot feedback and human peer review
        Community and CultureOpen source etiquette, constructive feedback, managing notifications, organizing with labels
        
-
        You will also work through GitHub Skills modules - interactive, bot-guided courses that run in your own GitHub account. A bot named Mona creates real issues and pull requests for you, verifies your actions, and guides you through each step. It is the same mechanism used by real open source projects.
        
-
        Day 2 - From Contributor to Product Maker (VS Code + Accessibility Agents)
        
-
        You earned the tools. Now you wield them.
        
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
        BlockWhat Happens
        Day 1 DebriefCelebrate what shipped, surface questions, set your Day 2 goal
        VS Code SetupScreen reader mode, workspace navigation, the bridge from browser to editor
        Deep Contribution with CopilotUse GitHub Copilot as a writing partner - draft improvements, review your own work, commit with confidence
        Activate the AgentsExplore 55 AI agents across 3 teams that amplify every skill you built on Day 1 - daily briefings, issue triage, PR review, accessibility monitoring
        Ship Your ContributionOpen a real pull request to a live public repository. Your facilitator reviews and merges it.
        Design the FutureCollaborative speccing session - what should the next version of these tools look like? Your ideas, on the record.
        
-
        Prerequisites - What You Need Before Day 1
        
-
        Please complete these steps at least one day before the workshop. If anything gives you trouble, contact us - we will help you get set up. We want Day 1 to start with learning, not troubleshooting.
        
-
        Hardware
        
-
          
-
        • A computer running Windows or macOS
          • 
-
        • A reliable internet connection
          • 
-
        • Headphones (recommended - screen reader audio in a group call can get lively)
          • 
-
        
-
        Screen Reader
        
-
        You need one of the following. Use whichever you are most comfortable with.
        
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
        Screen ReaderPlatformCostWhere to Get It
        NVDAWindowsFreeDownload NVDA
        JAWSWindowsPaid (40-minute trial available)Download JAWS
        VoiceOvermacOSBuilt-in (free)Already on your Mac - press Cmd+F5 to activate
        
-
        All exercises work with any of these. Where keyboard commands differ, we provide all three.
        
-
        Web Browser
        
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
        PlatformRecommended
        WindowsChrome or Firefox (Edge also works)
        macOSSafari (best VoiceOver support) or Firefox
        
-
        Software to Install
        
-
        Install these before the workshop. Detailed, screen-reader-friendly installation instructions are in our Pre-Workshop Setup Guide.
        
-
          
-
        1. Git - the version control system underneath GitHub
          
-
            
-
          • Windows: Download from Git for Windows download page - run the installer with default options
            • 
-
          • macOS: Open Terminal and type git --version - if Git is not installed, macOS will prompt you to install it automatically
            • 
-
          • Verify: Open a terminal and run git --version - you should see a version number
            • 
-
          
-
          2. 
-
        2. Visual Studio Code - the free, accessible code editor used on Day 2
          
-
            
-
          • Download from code.visualstudio.com
            • 
-
          • After installing, press Shift+Alt+F1 to enable Screen Reader Mode - this is essential
            • 
-
          
-
          3. 
-
        3. GitHub Copilot Chat extension - installed from within VS Code
          
-
            
-
          • Press Ctrl+Shift+X in VS Code to open Extensions
            • 
-
          • Search for "GitHub Copilot Chat" (publisher: GitHub)
            • 
-
          • Install it - Copilot Free tier is available to all GitHub users at no cost
            • 
-
          
-
          4. 
-
        4. GitHub Pull Requests extension - also installed from within VS Code
          
-
            
-
          • Search for "GitHub Pull Requests" (publisher: GitHub) in the Extensions panel
            • 
-
          • Install it
            • 
-
          
-
          5. 
-
        
-
        GitHub Account
        
-
        If you do not have a GitHub account, create one before the workshop:
        
-
          
-
        1. Navigate to the GitHub sign-up page
          2. 
-
        2. Enter your email address, create a password, and choose a username
            
-
          • Your username appears on every contribution you make - keep it professional
            • 
-
          
-
          3. 
-
        3. Complete the verification step
            
-
          • Screen reader users: GitHub's visual CAPTCHA can be a barrier. Look for an "Audio" or "Try an audio challenge" option. If neither is accessible, contact us before the event and we will assist with verification.
            • 
-
          
-
          4. 
-
        4. Check your email for a verification code and enter it on the GitHub page
          5. 
-
        5. Verify your email address when GitHub sends a separate confirmation link
          6. 
-
        
-
        After creating your account, configure these accessibility settings (they make a significant difference):
        
-
          
-
        1. Go to GitHub Accessibility Settings
          2. 
-
        2. Turn OFF Hovercards / Link Previews - this is the single most important setting. With hovercards on, your screen reader announces extra noise on every link you pass. Turn it off.
          3. 
-
        3. Turn ON Link Underlines - makes links visually distinguishable without relying on color
          4. 
-
        4. Set your preferred theme at GitHub Appearance Settings - high contrast options are available
          5. 
-
        
-
        Enable two-factor authentication (strongly recommended):
        
-
          
-
        1. Go to GitHub Security Settings
          2. 
-
        2. Enable 2FA using an authenticator app, SMS, or a security key
          3. 
-
        3. Save your recovery codes somewhere safe
          4. 
-
        
-
        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.
        
-
        Our Pre-Workshop Setup Guide walks through every one of these steps with detailed screen reader instructions for NVDA, JAWS, and VoiceOver.
        
-
        Registration Closed
        
-
        Registration for GIT Going with GitHub is now closed. Thank you to all who registered!
        
-
        Already registered? Complete the Pre-Workshop Setup Guide before March 7 to make sure you are ready for Day 1.
        
-
        What Makes This Workshop Different
        
-
        Most GitHub tutorials tell you what buttons to click. This one starts from a different place entirely: what does your screen reader announce when the page loads?
        
-
        Every step in this workshop is written three ways - for NVDA, for JAWS, and for VoiceOver. Not as an afterthought. As the default.
        
-
        And the goal is not just "learn GitHub." The goal is to move you from user to maker. From someone who encounters accessibility barriers to someone who files the issue, proposes the fix, reviews the pull request, and ships the solution. That arc - from observer to contributor to product maker - is what the two days are designed to deliver.
        
-
        The curriculum includes 17 chapters, 26 reference appendices, 44 companion podcast episodes, 24 hands-on exercises, a shared practice repository with automated feedback bots, three GitHub Skills modules with a bot that verifies your work in real time, and a live open source project where your contributions are merged on Day 2.
        
-
        All of it is open source. All of it is yours to keep, fork, and share.
        
-
        Frequently Asked Questions
        
-
        Do I need to know how to code?
-No. Many of the most valuable open source contributions are documentation, bug reports, accessibility reviews, and feedback. Code is welcome but never required.
        
-
        What if I have never used GitHub before?
-Perfect. That is exactly who this workshop is for. We start from zero.
        
-
        What if I get stuck during setup?
-Contact us. The whole point of doing setup before Day 1 is so we can troubleshoot together without eating into learning time. We will not let anyone fall behind.
        
-
        Can sighted people attend?
-Yes. Everything is keyboard-navigable. You will gain a new perspective on how software is experienced without a screen, and you will be a better developer for it.
        
-
        What if I cannot attend both days?
-Day 1 stands on its own - you will leave with real GitHub skills. Day 2 builds on Day 1, so attending only Day 2 without Day 1 is not recommended.
        
-
        Is there a cost?
-No. The workshop, all software, and all materials are free.
        
-
        Questions?
        
-
-
        Share This Event
        
-
        Know someone who would benefit from this workshop? Share this page:
        
-
        Workshop site: GIT Going with GitHub workshop site
-GitHub repo: GIT Going with GitHub on GitHub
        
-
        The best way to make open source more accessible is to bring more people who use assistive technology into the room where it is built.
        
-
        Open source is not complete without you. Come build with us.
        
-
        Acknowledgments
        
-
        A sincere thank you to the Visual Studio Code team for their continuous support of the blind and low vision community. It is through action that they empower and convert people from dreamers to creators. Thank you, Visual Studio Code team - and of course, GitHub!
        
-
        All workshop materials are licensed under CC BY 4.0.
        
-
        A Community Access initiative.
        
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/learning-room/docs/CHALLENGES.html b/html/learning-room/docs/CHALLENGES.html
deleted file mode 100644
index cc16ebd..0000000
--- a/html/learning-room/docs/CHALLENGES.html
+++ /dev/null
@@ -1,1022 +0,0 @@
-
-
-
-  
-  
-  
-  Available Challenges - GIT Going with GitHub
-  
-  
-  
-  
-
-
-  
-  
-  
        
-    
        Available Challenges
        
-
        Welcome to the Challenge Hub - your guide to leveling up your GitHub and accessibility skills! 
        
-
        This document is your single source of truth for all workshop challenges. It connects to GitHub issues that are pre-assigned to you by your @username.
        
-
        Quick Start:
        
-
          
-
        1. Go to the Issues tab of this repository
          2. 
-
        2. Look for issues titled Chapter X.Y: [Challenge Name] (@YOUR_USERNAME)
          3. 
-
        3. Click to open YOUR issue
          4. 
-
        4. Follow the steps in the issue description and this hub
          5. 
-
        5. Complete the challenge: comment on the issue (Chapters 4-5, 8-10, 12-14, 16) or open a PR (Chapters 6, 7, 11, 15)
          6. 
-
        6. Close the issue when done - you've leveled up!
          7. 
-
        
-
        Facilitators and Admins
        
-
        Are you managing this workshop? See FACILITATOR_CHALLENGES.md for:
        
-
          
-
        • How to generate challenges for a new cohort
          • 
-
        • Monitoring student progress in real time
          • 
-
        • Understanding bot validation and automation
          • 
-
        • Archiving and refreshing issues between cohorts
          • 
-
        • Pre-workshop setup checklist
          • 
-
        
-
        How to Find Your Challenges
        
-
        Method 1: GitHub Issues Tab (Easiest)
        
-
          
-
        1. Click the Issues tab at the top of this repository
          2. 
-
        2. Your challenges are assigned to you - filter by assignee (click your avatar)
          3. 
-
        3. Each issue title shows the chapter and challenge number
          4. 
-
        4. Click any issue to start
          5. 
-
        
-
        Example: You'll see issues like:
        
-
        Chapter 4.1: Create Your First Issue (@yourname)
-Chapter 4.2: Comment and @Mention (@yourname)
-Chapter 4.3: Add a Sub-Issue (@yourname)
-Chapter 6.1: Create One Small Branch Change (@yourname)
        
-
-
        In the GitHub search bar at the top:
        
-
        is:issue assignee:@yourname label:challenge
        
-
        This shows all challenges assigned to you.
        
-
        Method 3: This Challenge Hub (Below)
        
-
        Expand any chapter section below to see the full instructions. The hub is the detailed reference - issues are the lightweight tracker.
        
-
        Challenge Lifecycle
        
-
        There are two kinds of challenges. The type determines how you complete it.
        
-
        Comment-Based Challenges (Chapters 4, 7-10, 12-14, 16)
        
-
        No branches, no PRs, no file editing. Your work happens entirely in issue threads.
        
-
        1. FIND      → Open your assigned issue in the Issues tab
-2. WORK      → Follow the steps in the issue + this hub
-3. COMMENT   → Post your evidence as an issue comment
-4. CLOSE     → Close the issue when done
        
-
        PR-Based Challenges (Chapters 6, 7, 11, 15)
        
-
        You edit a file, create a branch, and open a pull request that references the issue.
        
-
        1. FIND      → Open your assigned issue in the Issues tab
-2. BRANCH    → Create a branch (naming convention below)
-3. EDIT      → Make the change described in the issue
-4. PR        → Open a PR with "Closes #XX" in the body
-5. VALIDATE  → Bot checks your work (Chapters 6, 7, 11)
-6. FIX       → If bot finds issues, fix and push again
-7. MERGE     → When checks pass, merge your PR
-8. COMPLETE  → Issue auto-closes!
        
-
        Branch Naming Convention
        
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
        ChapterBranch name patternExample
        Chapter 4No branch neededWork happens in issue threads
        Chapter 5No branch neededWork happens in issue threads
        Chapters 6-7fix/yourname-issueXXfix/maria-issue42
        Chapters 8-10No branch neededWork happens in issue threads
        Chapter 11chapter11/yourname-issueXXchapter11/maria-issue55
        Chapters 12-14No branch neededWork happens in issue threads
        Chapter 15templates/yourname-issueXXtemplates/maria-issue60
        Chapter 16No branch needed (optional: agents/yourname-issueXX)agents/maria-issue65
        
-
        
-
        What about your username-practice branch? That branch was created for you in Chapter 3. It becomes useful starting in Chapter 11 when you work locally with Git and VS Code. For Chapters 6-7, use short-lived fix/ branches instead.
        
-
        
-
        Chapter Challenge Map (Chapters 2-16)
        
-
        Use this map for a consistent student experience: safe start, small actions, visible progress.
        
-
        Shared Learning Pattern
        
-
          
-
        1. Learn: short chapter walkthrough.
          2. 
-
        2. Practice: one small, clear action.
          3. 
-
        3. Prove: leave evidence in issue or PR.
          4. 
-
        4. Celebrate: close issue and reflect briefly.
          5. 
-
        
-
        Chapter-by-Chapter Status
        
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
        ChapterChallenge ModelCountEvidenceAutomation
        Chapter 2: Navigating RepositoriesOrientation only0Readiness check with facilitatorNone
        Chapter 3: The Learning RoomSystem orientation only0Can explain issue -> branch -> PR flowNone
        Chapter 4: Working with IssuesMicro issue challenges (no branch needed)3Issue creation + @mention comment + sub-issueManual/facilitator
        Chapter 5: VS Code AccessibilityGuided setup baseline1Completion comment checklistNone
        Chapter 6: Working with Pull RequestsBot-validated PR challenges (first branch + file edit)3Linked PR (Closes #XX) + passing checksPR bot validation
        Chapter 7: Merge ConflictsControlled single drill1Issue-linked PR resolving conflict markersManual by default
        Chapter 8: Culture and EtiquetteGuided reflection1 optionalStructured reflection commentNone
        Chapter 9: Labels/Milestones/ProjectsGuided triage recommendation1Triage recommendation comment (or apply labels if permitted)None by default
        Chapter 10: NotificationsGuided setup walkthrough1Completion comment checklistNone
        Chapter 11: Git & Source ControlBot-validated local Git challenges3Commits + branch + PR with Closes #XXPR bot validation
        Chapter 12: GitHub PR ExtensionGuided PR extension setup2Issue comment with checklistNone
        Chapter 13: GitHub CopilotGuided AI-assisted writing3Issue comment with action checklistNone
        Chapter 14: Accessible Code ReviewGuided PR review practice2Issue comment with review summaryNone
        Chapter 15: Issue TemplatesAnalyze registration template, remix & create2-3Issue/PR comment with template remixed or createdNone
        Chapter 16: Accessibility AgentsGuided agent exploration + capstone feedback3-5 + CapstoneIssue comment with agent evaluation + feedback formNone
        
-
        Confidence Rules
        
-
          
-
        • Keep challenge tasks under 10 minutes.
          • 
-
        • Limit scope to one action and one proof artifact.
          • 
-
        • Prefer issue comments when automation is not reliable.
          • 
-
        • Use PR checks only where technical validation is deterministic.
          • 
-
        • In chapter challenge sections, always include: actionable steps, expected outcomes, "If You Get Stuck," and a short learning moment.
          • 
-
        
-
        Full Challenge Details (Expandable Reference)
        
-
        Students can expand any chapter below to see the complete challenge instructions without leaving this hub. Full chapter documentation is also available in each chapter file.
        
-
        
-Chapter 4: Working with Issues - 3 Micro-Challenges
-
-
        
-
        Branch guidance: Chapter 4 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.
        
-
        
-
        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. Add a sub-issue - break a larger issue into smaller, trackable pieces.
          4. 
-
        
-
        Challenge 4.1: Create Your First Issue
        
-
        Goal: File a new issue in the Learning Room repository.
        
-
          
-
        1. Open the learning-room repository in your browser.
          2. 
-
        2. Navigate to the Issues tab (keyboard shortcut: press G then I).
          3. 
-
        3. Activate the New issue button.
          4. 
-
        4. If a template picker appears, select Open a blank issue.
          5. 
-
        5. Type a clear, specific title (at least 12 characters). Examples:
            
-
          • "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. Write a meaningful description (at least 80 characters). Include what the problem is, where it exists (file name and section), and what a fix might look like.
          7. 
-
        7. Activate Submit new issue.
          8. 
-
        8. 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.
        
-
        Challenge 4.2: Comment and @Mention
        
-
        Goal: Leave a comment on another student's issue and use an @mention to notify them.
        
-
          
-
        1. Open the Issues tab in the learning-room repository.
          2. 
-
        2. Find an issue created by a classmate (look for issues from Challenge 4.1, or browse 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.
          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 will render as a clickable link).
        
-
        Challenge 4.3: Add a Sub-Issue
        
-
        Goal: Break a larger issue into smaller, trackable pieces using GitHub's sub-issue feature.
        
-
        
-
        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 (or any open issue you have permission to edit).
          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
        
-
        Post a comment on your assigned Chapter 4.1 challenge issue 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 actual issue numbers. Then close your Chapter 4 challenge issues.
        
-
        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. 
-
        
-
        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.
        
-
        
-
-
-
        
-Chapter 5: VS Code Accessibility - Guided VS Code Accessibility Baseline (No Bot Check)
-
-
        Goal
        
-
        Confirm students can access VS Code (github.dev or desktop), enable screen reader support, and perform core file navigation.
        
-
        Student Steps
        
-
          
-
        1. Open any repository and launch github.dev with . (period key).
          2. 
-
        2. Screen reader mode setup:
            
-
          • Windows (NVDA/JAWS): enable with Shift+Alt+F1.
            • 
-
          • Mac (VoiceOver): mode is usually already optimized. If needed, run Command Palette and search Toggle Screen Reader Accessibility Mode.
            • 
-
          
-
          3. 
-
        3. Open Explorer with Ctrl+Shift+E (Mac: Cmd+Shift+E).
          4. 
-
        4. Open README.md from the file tree.
          5. 
-
        5. Open outline/symbols with Ctrl+Shift+O (Mac: Cmd+Shift+O).
          6. 
-
        6. Open Command Palette with Ctrl+Shift+P (Mac: Cmd+Shift+P) and run any command.
          7. 
-
        7. Return to your assigned challenge issue and post a completion comment using this format:
          8. 
-
        
-
        Chapter 5 complete:
-- Opened github.dev: yes
-- Screen reader mode enabled: yes
-- Opened file in Explorer: yes
-- Opened outline/symbols: yes
-- Opened Command Palette: yes
        
-
        Expected Outcomes
        
-
          
-
        • Student can launch and navigate github.dev or desktop VS Code.
          • 
-
        • Student can enable screen reader mode and open core navigation surfaces.
          • 
-
        • Student is ready for VS Code-based contribution chapters.
          • 
-
        
-
        If You Get Stuck
        
-
          
-
        1. Confirm you are in a repository page before pressing ..
          2. 
-
        2. Retry screen reader mode toggle once, then verify in settings.
          3. 
-
        3. On Mac with VoiceOver, use Command Palette (Cmd+Shift+P) and run Toggle Screen Reader Accessibility Mode if keyboard navigation feels inconsistent.
          4. 
-
        4. Use Command Palette to run commands when shortcut memory is hard.
          5. 
-
        5. Ask facilitator for a side-by-side demo and repeat the same 5 steps.
          6. 
-
        
-
        Learning Moment
        
-
        Tool setup is part of contribution skill. A stable, accessible editor reduces stress and increases contribution quality.
        
-
        
-
-
        
-Chapter 6: Working with Pull Requests - 3 PR-Validated Challenges
-
-
        
-
        Branch guidance: This is the first chapter where you edit files and create branches.
        
-
          
-
        • Web editor (recommended): When you edit a file on GitHub.com and click "Propose changes," GitHub creates a branch for you. Name it fix/yourname-issueXX.
          • 
-
        • Local Git: Create a branch with git checkout -b fix/yourname-issueXX from main.
          • 
-
        • Do NOT use your username-practice branch yet. That is for Chapter 11 and beyond.
          • 
-
        
-
        
-
        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. 
-
        
-
        Challenge 6.1: Create One Small Branch Change
        
-
        Goal: Edit one of the practice files and save your change on a new branch.
        
-
        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:
        
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
        FileWhat to fix
        docs/welcome.mdThree [TODO] sections where content is missing
        docs/keyboard-shortcuts.mdIntentional errors in shortcut references
        docs/setup-guide.mdBroken links and incomplete steps
        
-
        Using the web editor:
        
-
          
-
        1. Navigate to the file in the learning-room repository.
          2. 
-
        2. Activate the pencil icon (Edit this file).
          3. 
-
        3. Make your change (keep it small and focused).
          4. 
-
        4. Activate Commit changes.
          5. 
-
        5. In the branch name field, type: fix/yourname-issueXX.
          6. 
-
        6. Select Create a new branch for this commit and start a pull request.
          7. 
-
        7. Activate Propose changes.
          8. 
-
        
-
        Challenge 6.2: Open a Linked PR
        
-
          
-
        1. On the "Open a pull request" page, write a descriptive title.
          2. 
-
        2. In the body, include a summary of your change (at least 50 characters) and the line Closes #XX (where XX is your Chapter 6 challenge issue number).
          3. 
-
        3. Verify the base branch is main and the compare branch is your fix/ branch.
          4. 
-
        4. Activate Create pull request.
          5. 
-
        
-
        Challenge 6.3: Pass Required Checks
        
-
          
-
        1. Wait about 30 seconds. The bot posts a validation comment.
          2. 
-
        2. Read the bot feedback. It checks: issue reference, description length, file location, and accessibility.
          3. 
-
        3. If the bot reports failures, edit the file again (directly on your branch via the Files changed tab pencil icon), fix the issue, and commit. The bot re-runs automatically.
          4. 
-
        4. Repeat until all checks show green checkmarks.
          5. 
-
        5. Request a review from a peer or facilitator.
          6. 
-
        
-
        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. 
-
        
-
        Learning Moment
        
-
        A great PR is small, linked to an issue, and easy to review. Faster feedback builds confidence and momentum.
        
-
        
-
-
        
-Chapter 7: Merge Conflicts - 1 Controlled Conflict Drill
-
-
        Challenge: Resolve Conflict Markers
        
-
        Sample file: learning-room/docs/samples/chapter-6-conflict-practice-sample.md
        
-
          
-
        1. Open the assigned merge-conflict practice issue.
          2. 
-
        2. Edit only the designated practice file/section.
          3. 
-
        3. Remove conflict markers (<<<<<<<, =======, >>>>>>>) and keep the intended final content.
          4. 
-
        4. Open PR with Closes #XX and complete with a short issue comment summary.
          5. 
-
        
-
        Expected Outcomes
        
-
          
-
        • Student can identify conflict markers immediately.
          • 
-
        • Student can remove markers and keep intended content.
          • 
-
        • Student can submit a clean, issue-linked PR after resolution.
          • 
-
        
-
        If You Get Stuck
        
-
          
-
        1. Pause and read marker blocks line by line before editing.
          2. 
-
        2. Keep one side, or combine both sides when both lines are valid.
          3. 
-
        3. Delete all marker lines (<<<<<<<, =======, >>>>>>>).
          4. 
-
        4. Ask facilitator to sanity-check final content before opening PR.
          5. 
-
        
-
        Learning Moment
        
-
        Merge conflicts are not failures. They are a normal collaboration checkpoint and a chance to make an intentional content decision.
        
-
        
-
-
        
-Chapter 8: Culture and Etiquette - Optional Guided Reflection
-
-
        Optional Guided Reflection (Issue Comment Evidence)
        
-
        Students can post one short comment on their assigned issue:
        
-
        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:
        
-
        This keeps learning visible without creating a pass/fail pressure point.
        
-
        Completion criteria: Post one sentence for each of the three prompts.
        
-
        Expected Outcomes
        
-
          
-
        • Student can name respectful collaboration behaviors.
          • 
-
        • Student can prepare a constructive feedback style before review work.
          • 
-
        • Student feels safer asking for help in public threads.
          • 
-
        
-
        If You Get Stuck
        
-
          
-
        1. Use one simple sentence per prompt.
          2. 
-
        2. Focus on one real behavior you can do today.
          3. 
-
        3. If writing feels hard, draft bullet points first, then post.
          4. 
-
        4. Ask facilitator for one example response and adapt it.
          5. 
-
        
-
        Learning Moment
        
-
        Technical quality and communication quality work together. Respectful, clear communication helps good code get merged faster.
        
-
        
-
-
        
-Chapter 9: Labels, Milestones, and Projects - 1 Guided Triage Recommendation
-
-
        Challenge: Triage Recommendation Comment
        
-
        Estimated time: 5-10 minutes
        
-
          
-
        1. Open your assigned challenge issue.
          2. 
-
        2. Review issue title, description, and target file.
          3. 
-
        3. Post a triage recommendation comment using this format:
          4. 
-
        
-
        Chapter 9 triage recommendation:
-- Suggested labels:
-- Suggested milestone:
-- Suggested project board column:
-- One-sentence reason:
        
-
          
-
        1. If you have write access, apply the recommended labels/milestone directly.
          2. 
-
        
-
        This keeps the task simple and accessible for all students, including those without triage permissions.
        
-
        Expected Outcomes
        
-
          
-
        • Student can recommend labels/milestone/project placement using issue context.
          • 
-
        • Student understands triage even without maintainer permissions.
          • 
-
        • Student leaves a clear, reusable triage note for maintainers.
          • 
-
        
-
        If You Get Stuck
        
-
          
-
        1. Start with one label only (documentation, bug, or accessibility).
          2. 
-
        2. If milestone is unclear, write none and explain why.
          3. 
-
        3. If project board is unknown, write needs triage and continue.
          4. 
-
        4. Ask facilitator to review your one-sentence reason before posting.
          5. 
-
        
-
        Learning Moment
        
-
        Triage is about clarity, not authority. Good recommendations reduce maintainer effort and speed up collaboration.
        
-
        
-
-
        
-Chapter 10: Notifications - Guided Setup Walkthrough (No Bot Check)
-
-
        Goal
        
-
        Set up a useful notification workflow so students can keep up with reviews, mentions, and assignments without inbox overload.
        
-
        Estimated time: 8-12 minutes
        
-
        Student Steps
        
-
          
-
        1. Open the workshop repository and set Watch to Participating and @mentions.
          2. 
-
        2. Open the notifications inbox: https://github.com/notifications.
          3. 
-
        3. Activate the Review requested filter.
          4. 
-
        4. Activate the Assigned filter.
          5. 
-
        5. Open one notification and return to inbox.
          6. 
-
        6. Perform one inbox action on a non-critical thread:
            
-
          • M to mute, or
            • 
-
          • E to mark done.
            • 
-
          
-
          7. 
-
        
-
        Expected Outcome
        
-
          
-
        • Student can find review requests quickly.
          • 
-
        • Student can find assigned work quickly.
          • 
-
        • Student can reduce noise with one inbox action.
          • 
-
        
-
        If You Get Stuck
        
-
          
-
        1. Reload the notifications page and reapply one filter at a time.
          2. 
-
        2. If inbox is empty, switch to Done and practice action flow there.
          3. 
-
        3. If shortcuts conflict with screen reader mode, focus the notification row and retry.
          4. 
-
        4. Ask facilitator to model one inbox action live, then repeat.
          5. 
-
        
-
        Learning Moment
        
-
        Notification management protects focus. You can stay responsive without drowning in updates.
        
-
        
-
-
-
        
-Chapter 11: Git & Source Control in VS Code - 3 Bot-Validated Local Git Challenges
-
-
        Challenge Set
        
-
        Estimated time: 20-30 minutes
        
-
        Prerequisite checkpoint: Complete Chapter 5 first so VS Code navigation and accessibility settings are already stable.
        
-
          
-
        1. Clone the sci-fi themes repository
          
-
            
-
          • Clone https://github.com/community-access/vscode-sci-fi-themes.git to your local machine using VS Code.
            • 
-
          • Explore the themes and pick one (Star Trek, Hitchhiker's Guide, or Star Wars).
            • 
-
          
-
          2. 
-
        2. Make one small commit
          
-
            
-
          • Edit a file in the cloned repo (or in the learning-room), stage changes, write a clear commit message, and commit locally.
            • 
-
          
-
          3. 
-
        3. Push and open a linked PR
          
-
            
-
          • Push your branch and open a PR that references a challenge issue with Closes #XX.
            • 
-
          
-
          4. 
-
        
-
        Expected Outcomes
        
-
          
-
        • Student can clone a repository using VS Code Command Palette.
          • 
-
        • Student can navigate the Source Control panel and stage files.
          • 
-
        • Student can write a clear commit message and push a branch to GitHub.
          • 
-
        
-
        If You Get Stuck
        
-
          
-
        1. Confirm Command Palette opens with Ctrl+Shift+P (Windows) or Cmd+Shift+P (Mac).
          2. 
-
        2. If Source Control panel doesn't open, use Ctrl+Shift+G (Windows) or Cmd+Shift+G (Mac).
          3. 
-
        3. If push fails, verify authentication: Ctrl+Shift+P → "Git: Fetch" to test connection.
          4. 
-
        4. If branch won't create, confirm VS Code is in the cloned repository folder (status bar shows branch name).
          5. 
-
        5. Ask facilitator to verify your clone location and help with one push.
          6. 
-
        
-
        Fun Fact
        
-
        Once you've cloned the sci-fi themes repo and applied a theme, open Copilot Chat (Ctrl+Shift+I) and ask it a question. While it thinks, watch your custom sci-fi loading phrases appear.
        
-
        Learning Moment
        
-
        Local Git operations give you full control and immediate feedback. You can see your changes before they reach GitHub.
        
-
        
-
-
        
-Chapter 12: GitHub Pull Requests Extension - 2 Guided PR Review Challenges
-
-
        Challenge Set
        
-
        Estimated time: 15-25 minutes
        
-
          
-
        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 challenge PR and post a review
          
-
            
-
          • Download a PR branch locally and write one constructive review comment.
            • 
-
          • If checkout is blocked by permissions, complete the challenge by reviewing the PR in read-only mode and posting one specific comment.
            • 
-
          
-
          3. 
-
        
-
        Expected Outcomes
        
-
          
-
        • Student can install and authenticate the GitHub PR extension.
          • 
-
        • Student can check out a PR branch in VS Code.
          • 
-
        • Student can interactively review changes and post feedback.
          • 
-
        
-
        If You Get Stuck
        
-
          
-
        1. If extension doesn't install, reload VS Code with Ctrl+Shift+P → "Developer: Reload Window".
          2. 
-
        2. If OAuth sign-in fails, verify your GitHub account is active in the browser first, then retry.
          3. 
-
        3. If PR list is empty, switch to "All Open" view in the GitHub section of Explorer.
          4. 
-
        4. If checkout fails, confirm you have write access to the repository or ask facilitator.
          5. 
-
        5. Ask facilitator to verify the GitHub PR view in Explorer and help with one checkout.
          6. 
-
        6. If Activity Bar focus is hard with a screen reader, use Command Palette and run GitHub Pull Requests: Focus on Pull Requests View.
          7. 
-
        
-
        Learning Moment
        
-
        PR tooling multiplies your impact. Reviewing others' work refines your own standards and builds community trust.
        
-
        
-
-
        
-Chapter 13: GitHub Copilot - 3 Guided AI-Assisted Writing Challenges
-
-
        Access note: GitHub Copilot Free tier works for this workshop. Paid plan is not required.
        
-
        Challenge Set
        
-
          
-
        1. Install GitHub Copilot and sign in
          
-
            
-
          • Install the GitHub Copilot Chat extension from Extensions sidebar and authenticate.
            • 
-
          
-
          2. 
-
        2. Clone the sci-fi themes repo and ask Copilot to explain it
          
-
            
-
          • Clone https://github.com/community-access/vscode-sci-fi-themes.git
            • 
-
          • Open Copilot Chat (Ctrl+Shift+I / Mac: Cmd+Shift+I)
            • 
-
          • Ask: "What does the chat.agent.thinking.phrases setting do in VS Code?"
            • 
-
          • Read Copilot's explanation and apply one theme to your settings.json
            • 
-
          • Reload VS Code and see custom sci-fi phrases in Copilot Chat!
            • 
-
          
-
          3. 
-
        3. Create a custom theme with Copilot
          
-
            
-
          • In Copilot Chat, ask: "Create custom GitHub Copilot thinking phrases for [your favorite universe - Dune, Marvel, Studio Ghibli, etc.]"
            • 
-
          • Copilot generates a theme
            • 
-
          • Copy it into your settings.json and reload VS Code
            • 
-
          • Enjoy your personalized Copilot experience!
            • 
-
          
-
          4. 
-
        
-
        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 in fun and creative ways.
          • 
-
        
-
        If You Get Stuck
        
-
          
-
        1. If extension installation fails, reload VS Code with Ctrl+Shift+P → "Developer: Reload Window".
          2. 
-
        2. If OAuth sign-in fails, verify your GitHub account is active in the browser first.
          3. 
-
        3. If Chat panel doesn't open, try Ctrl+Shift+I (Windows) or Cmd+Shift+I (Mac).
          4. 
-
        4. If Chat seems unresponsive, click the model selector at bottom of Chat and confirm you're signed in.
          5. 
-
        5. Ask facilitator to help verify Copilot is activated and show you one prompt.
          6. 
-
        
-
        Learning Moment
        
-
        AI assistance amplifies clarity. Copilot is not just for code. It can also support clear writing and practical customization of your development environment.
        
-
        
-
-
        
-Chapter 14: Accessible Code Review - 2 Guided PR Review Challenges
-
-
        Challenge Set
        
-
          
-
        1. Review a practice PR and leave 2-3 inline comments
          
-
            
-
          • Check out or view an assigned practice PR, read the diff, and post constructive feedback on 2-3 specific lines.
            • 
-
          
-
          2. 
-
        2. Submit a formal review verdict
          
-
            
-
          • Complete your review by submitting an approval, request-changes, or comment-only verdict on the PR.
            • 
-
          
-
          3. 
-
        
-
        Expected Outcomes
        
-
          
-
        • Student can navigate PR diffs with a screen reader.
          • 
-
        • Student can post inline comments on specific lines.
          • 
-
        • Student can write constructive feedback that helps the author improve.
          • 
-
        
-
        If You Get Stuck
        
-
          
-
        1. If Files Changed tab won't open, reload the PR page and retry.
          2. 
-
        2. If inline comment button is hard to find, use the file tree to jump between files (Press 3 in NVDA/JAWS).
          3. 
-
        3. If you're unsure what to comment on, focus on clarity: heading structure, link text, missing steps, or typos.
          4. 
-
        4. If submitting the review fails, check that you're not in draft mode and have write access to the repo.
          5. 
-
        5. Ask facilitator to help you navigate one diff and model one constructive comment.
          6. 
-
        
-
        Learning Moment
        
-
        Constructive review is a gift. Specific, kind feedback helps authors improve and builds trust in the community.
        
-
        
-
-
        
-Chapter 15: Issue Templates - 2-3 Guided Template Design Challenges Using Registration Template
-
-
        Challenge Set
        
-
        Estimated time: 2-2.5 hours (includes YAML learning and remix practice)
        
-
        Sample files used in this challenge:
        
-
-
        The registration template you filled out on Day 1 is your teaching tool. It demonstrates YAML form-based templates with accessibility-first design.
        
-
          
-
        1. Analyze the registration template
          
-
            
-
          • Open: .github/ISSUE_TEMPLATE/workshop-registration.yml
            • 
-
          • Read the YAML structure: frontmatter (name, description, title, labels) and field types
            • 
-
          • Notice field types: input, dropdown, textarea, markdown
            • 
-
          • Observe: each field has a label, description, and validation rule
            • 
-
          • Compare: How is this better than a blank issue form?
            • 
-
          • Evidence: Short comment explaining one way the template improved contributions
            • 
-
          
-
          2. 
-
        2. Remix the registration template for a new context
          
-
            
-
          • Take the registration template structure and adapt it for a different use case
            • 
-
          • Keep the YAML pattern, change the context: (e.g., bug report, workshop feedback, accessibility audit)
            • 
-
          • Update: field names, labels, descriptions, and dropdown options
            • 
-
          • Create: .github/ISSUE_TEMPLATE/my-template.yml in your test repository
            • 
-
          • Commit and push
            • 
-
          • Validate YAML syntax before pushing (for example: https://www.yamllint.com/)
            • 
-
          • Evidence: PR or comment linking to your remixed template
            • 
-
          
-
          3. 
-
        3. Optional: Create a Markdown template
          
-
            
-
          • Create: .github/ISSUE_TEMPLATE/my-markdown-template.md
            • 
-
          • Write YAML frontmatter (same pattern as registration template)
            • 
-
          • Add Markdown body with 3-4 sections and HTML comment instructions
            • 
-
          • Test in the template chooser if your repository supports it
            • 
-
          • Evidence: PR or comment linking to your Markdown template
            • 
-
          
-
          4. 
-
        
-
        Expected Outcomes
        
-
          
-
        • Student can read and understand YAML form template structure
          • 
-
        • Student can adapt a professional template to a new context
          • 
-
        • Student understands why templates improve contribution quality and consistency
          • 
-
        • Student can create both YAML form-based and Markdown templates
          • 
-
        • Student recognizes accessibility-first design in form templates
          • 
-
        
-
        If You Get Stuck
        
-
          
-
        1. Can't find the registration template? Look in .github/ISSUE_TEMPLATE/workshop-registration.yml — that's the form you filled out to join.
          2. 
-
        2. YAML structure confusing? Start by copying the registration template. Modify only the field descriptions and labels first. Leave the structure intact.
          3. 
-
        3. YAML not parsing? Compare your file against the provided remix sample and validate indentation with two spaces per level.
          4. 
-
        4. Not sure what context to remix for? Try: bug report, feature request, workshop feedback, accessibility audit form, or event signup.
          5. 
-
        5. Template doesn't appear in chooser? Verify filename ends in .yml or .md, file is in .github/ISSUE_TEMPLATE/, and you pushed the commit. Try a fresh Issues tab reload.
          6. 
-
        6. Repository permissions issue? Ask facilitator for write access to a shared test repository.
          7. 
-
        7. Want to see how it all works? Ask facilitator to show you a template they created.
          8. 
-
        
-
        Learning Moment
        
-
        The best template is one you've already used. By remixing the registration template, you learned that template design is about pattern recognition and context adaptation, not starting from scratch every time. When you maintain a project later, you'll do this: analyze what worked, adapt it to your new context, then iterate. Professional templates exist because someone did this exercise and discovered what works. Your remix becomes their teachable example.
        
-
        
-
-
        
-Chapter 16: Accessibility Agents - 3-5 Guided Agent Exploration & Validation Challenges
-
-
        Starter Set (Use These First)
        
-
        If 55 agents feels too broad, start with this sequence:
        
-
          
-
        1. @daily-briefing (maps to repository navigation and issue awareness)
          2. 
-
        2. @issue-tracker (maps to Chapter 4 issue workflow)
          3. 
-
        3. @pr-review (maps to Chapter 6 and Chapter 14 review skills)
          4. 
-
        
-
        Once these feel comfortable, expand to specialist agents.
        
-
        Challenge Set
        
-
          
-
        1. Agent Discovery Mapping
          
-
            
-
          • Read Section 3: The Ecosystem (55 agents across 3 teams)
            • 
-
          • Use the discovery framework: Skill you already have -> matching agent -> one safe first prompt
            • 
-
          • Match 3-5 agents to Day 1 skills you already have
            • 
-
          • Answer: "I am ready for this agent because I have already [skill]"
            • 
-
          • Evidence: Issue comment with your mapping (use #16-agent-discovery label)
            • 
-
          • Time: 20 minutes
            • 
-
          
-
          2. 
-
        2. Agent Skill Validation
          
-
            
-
          • Clone your fork of accessibility-agents repo
            • 
-
          • Open Copilot Chat and run one agent from your discovery list
            • 
-
          • Evaluate: Did the output match what you expected from manual experience?
            • 
-
          • Answer three evaluation questions in an issue comment (use #16-agent-validation label)
            • 
-
          • Time: 30 minutes
            • 
-
          
-
          3. 
-
        3. Agent Instructions Deep Dive
          
-
            
-
          • Read one .agent.md or .prompt.md file
            • 
-
          • Answer: What is this agent trying to do? What tools does it have access to?
            • 
-
          • Answer: Could this agent make a mistake? What kind?
            • 
-
          • Evidence: Issue comment with your analysis (use #16-agent-internals label)
            • 
-
          • Time: 15 minutes
            • 
-
          
-
          4. 
-
        
-
        Optional Contribution Challenges (Day 2 Hackathon)
        
-
          
-
        1. Improve an Existing Agent (45 min)
          
-
            
-
          • Find an agent gap or improvement opportunity
            • 
-
          • Edit the agent's instructions
            • 
-
          • Open a PR to accessibility-agents
            • 
-
          • Evidence: Your merged PR
            • 
-
          
-
          2. 
-
        2. Propose a New Agent (60 min)
          
-
            
-
          • Identify an uncovered workflow
            • 
-
          • File an issue with 3 example prompts
            • 
-
          • Discuss with maintainers
            • 
-
          • Evidence: Your issue with community discussion
            • 
-
          
-
          3. 
-
        
-
        Capstone: Workshop Feedback (The Most Important Challenge!)
        
-
        This is not optional. Your feedback directly shapes the next cohort.
        
-
          
-
        1. Share Your Experience - Workshop Feedback Form (15-20 min)
          
-
            
-
          • You've completed (or are working through) two days with us.
            • 
-
          • Your constructive feedback helps us improve, helps future students, and teaches maintainers how to build better tools.
            • 
-
          • This feedback will be read, discussed, and acted on.
            • 
-
          • Open a new issue in git-going-with-github using the Workshop Feedback template
            • 
-
          • Direct link: File Workshop Feedback
            • 
-
          • Fill out as much or as little as you're comfortable sharing
            • 
-
          • No response is "wrong" - honest feedback is the only kind we want
            • 
-
          
-
          What to cover (if you want to):
          
-
            
-
          • Which agents were most useful?
            • 
-
          • Which agents confused you or didn't work as expected?
            • 
-
          • Did the chapter progression feel logical?
            • 
-
          • Was the workshop accessible to you? (screen reader users, keyboard users, neurodivergent learners, all welcome)
            • 
-
          • What concept will you remember in 6 months?
            • 
-
          • What should we change for next time?
            • 
-
          • Anything else? (Facilitator appreciation? Suggestions? Wild ideas?)
            • 
-
          
-
          Evidence: Your submitted feedback issue becomes part of our workshop archive and roadmap.
          2. 
-
        
-
        Expected Outcomes
        
-
          
-
        • Student can map Day 1 manual skills to specific agents in the ecosystem
          • 
-
        • Student understands Skill First, Agent Second principle
          • 
-
        • Student has used at least one agent in Copilot Chat
          • 
-
        • Student can read and evaluate agent instructions
          • 
-
        • (Capstone) Student has shared honest, constructive feedback that helps future cohorts
          • 
-
        • (Optional) Student has contributed an improvement or proposal to the project
          • 
-
        
-
        If You Get Stuck
        
-
          
-
        1. Can't find matching agents? Start with @daily-briefing or @issue-tracker—those build directly on Chapters 2-5.
          2. 
-
        2. Agent output doesn't make sense? That is valuable feedback. Paste it in an issue comment with your question. The error might point to a gap in the agent's instructions.
          3. 
-
        3. Can't see agents in Copilot Chat? Check: Is Copilot Chat extension installed (not just Copilot)? Are you signed in? Does .github/agents/ folder exist in your cloned repo? Run ls -la .github/agents/ to verify.
          4. 
-
        4. Clone failed? Use the terminal: git clone https://github.com/[your-username]/accessibility-agents.git; cd accessibility-agents; code .
          5. 
-
        5. Feedback form feels overwhelming? Answer just one question. Any feedback is valuable. Start with "What confused you the most?" - that's the most actionable for us.
          6. 
-
        6. Still stuck? Show facilitator: the agent you wanted to run, the output you got, and what you expected. They can verify setup.
          7. 
-
        
-
        Learning Moment
        
-
        The 55 agents exist because someone did the manual work first, then automated the repetitive parts. The principle Skill First, Agent Second exists to protect you: it keeps you from treating AI as magic. You already know the limits of automation because you have done the work by hand. That expertise lets you evaluate agents critically, catch their mistakes, and improve them. The agents that will exist in the future will be built by people in this room who saw a gap and filled it.
        
-
        Your feedback is the bridge between this workshop and the next one. Thank you for being honest. We are listening.
        
-
        
-
-
-
        Group Challenges
        
-
        These challenges require collaboration with your study group:
        
-
          
-
        • Group Documentation Sprint: Collaboratively improve docs
          • 
-
        • Peer Review Circle: Everyone reviews everyone
          • 
-
        • Accessibility Workshop: Teach each other a11y topics
          • 
-
        • Challenge Creation: Design new challenges together
          • 
-
        
-
        View Group Challenges →
        
-
        Need Help?
        
-
        Getting Unstuck
        
-
          
-
        1. Read bot feedback (PR chapters only) - it includes specific fixes
          2. 
-
        2. Check the chapter documentation - each chapter file has full walkthroughs
          3. 
-
        3. Ask your peer reviewer - comment on your PR or issue
          4. 
-
        4. Ask your study group - use your group issue thread
          5. 
-
        5. Ask facilitators - @mention them in your issue or PR
          6. 
-
        
-
        Resources
        
-
-
-  
        
-  
-  
-
\ No newline at end of file
diff --git a/html/learning-room/docs/course-roadmap.html b/html/learning-room/docs/course-roadmap.html
new file mode 100644
index 0000000..18b2d7f
--- /dev/null
+++ b/html/learning-room/docs/course-roadmap.html
@@ -0,0 +1,148 @@
+
+
+
+  
+  
+  
+  Course Roadmap - GIT Going with GitHub
+  
+  
+  
+  
+
+
+  
+  
+  
        
+    
        Course Roadmap
        
+
        This roadmap guides you through the full workshop from setup to capstone. Follow it in order.
        
+
        Quick Navigation
        
+
          
+
        1. Before You Start
          2. 
+
        2. Day 1 Path (Challenges 1-9)
          3. 
+
        3. Day 2 Path (Challenges 10-16)
          4. 
+
        4. Bonus Path (A-E)
          5. 
+
        5. How to Use Support Resources
          6. 
+
        6. Completion Checklist
          7. 
+
        
+
        Before You Start
        
+
          
+
        1. Read the Setup Guide.
          2. 
+
        2. Open the Challenge Hub.
          3. 
+
        3. Keep the Keyboard Shortcuts page open if useful.
          4. 
+
        
+
        Day 1 Path (Challenges 1-9)
        
+
        Goal: learn GitHub basics in the browser and complete your first merged pull request.
        
+
          
+
        1. Challenge 1: Find Your Way Around
          2. 
+
        2. Challenge 2: File Your First Issue
          3. 
+
        3. Challenge 3: Join the Conversation
          4. 
+
        4. Challenge 4: Branch Out
          5. 
+
        5. Challenge 5: Make Your Mark
          6. 
+
        6. Challenge 6: Open Your First PR
          7. 
+
        7. Challenge 7: Survive a Merge Conflict
          8. 
+
        8. Challenge 8: The Culture Layer
          9. 
+
        9. Challenge 9: Merge Day
          10. 
+
        
+
        Expected Day 1 outcome:
        
+
          
+
        • You have opened and merged a pull request.
          • 
+
        • You have participated in issue and PR collaboration.
          • 
+
        
+
        Day 2 Path (Challenges 10-16)
        
+
        Goal: work locally, perform code review, and complete the capstone contribution.
        
+
          
+
        1. Challenge 10: Go Local
          2. 
+
        2. Challenge 11: Open a Day 2 PR
          3. 
+
        3. Challenge 12: Review Like a Pro
          4. 
+
        4. Challenge 13: AI as Your Copilot
          5. 
+
        5. Challenge 14: Template Remix
          6. 
+
        6. Challenge 15: Meet the Agents
          7. 
+
        7. Challenge 16: Build Your Agent (Capstone)
          8. 
+
        
+
        Expected Day 2 outcome:
        
+
          
+
        • You can run a local Git workflow end to end.
          • 
+
        • You can give and respond to code review feedback.
          • 
+
        • You can complete a capstone agent contribution.
          • 
+
        
+
        Bonus Path (A-E)
        
+
        Use bonus scenarios after core challenges are complete.
        
+
          
+
        1. Bonus A: Improve an Existing Agent
          2. 
+
        2. Bonus B: Document Your Journey
          3. 
+
        3. Bonus C: Create a Group Challenge
          4. 
+
        4. Bonus D: Notification Mastery
          5. 
+
        5. Bonus E: Explore Git History Visually
          6. 
+
        
+
        For optional advanced practice adapted from GitHub Skills, see Skills-Inspired Bonus Scenarios.
        
+
        How to Use Support Resources
        
+
        Use support in this order:
        
+
          
+
        1. Re-read your current challenge issue instructions.
          2. 
+
        2. Check the Solutions Index.
          3. 
+
        3. Ask for help in your issue or PR comments.
          4. 
+
        4. Ask your facilitator.
          5. 
+
        
+
        Completion Checklist
        
+
        Use this list to track your full journey:
        
+
          
+
        • Completed all Day 1 challenges (1-9)
          • 
+
        • Completed all Day 2 challenges (10-16)
          • 
+
        • Completed capstone challenge (16)
          • 
+
        • Optional: completed bonus challenges (A-E)
          • 
+
        
+
        When in doubt, return to the Challenge Hub. It is the canonical challenge reference.
        
+
+  
        
+  
+
+  
+
diff --git a/html/learning-room/docs/keyboard-shortcuts.html b/html/learning-room/docs/keyboard-shortcuts.html
index 2d0203b..44469c7 100644
--- a/html/learning-room/docs/keyboard-shortcuts.html
+++ b/html/learning-room/docs/keyboard-shortcuts.html
@@ -362,5 +362,6 @@ 
        Common Issues and Workarounds
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/learning-room/docs/samples/agent-file-template.html b/html/learning-room/docs/samples/agent-file-template.html
index 0e11341..1761aaf 100644
--- a/html/learning-room/docs/samples/agent-file-template.html
+++ b/html/learning-room/docs/samples/agent-file-template.html
@@ -112,5 +112,6 @@ 
        Common mistakes to avoid
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/learning-room/docs/samples/chapter-6-conflict-practice-sample.html b/html/learning-room/docs/samples/chapter-6-conflict-practice-sample.html
index 5bd4dde..2c847fc 100644
--- a/html/learning-room/docs/samples/chapter-6-conflict-practice-sample.html
+++ b/html/learning-room/docs/samples/chapter-6-conflict-practice-sample.html
@@ -63,7 +63,7 @@ 
        Chapter 6 Conflict Practice SampleConflict Marker Example
        
 
        <<<<<<< HEAD
 Use Command Palette to open settings.
-=======
+=======
 Open settings from the gear icon.
 >>>>>>> feature/chapter-6-example
        
 
        Resolved Version Example
        
@@ -81,5 +81,6 @@ 
        How This Supports the Challenge
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/learning-room/docs/samples/copilot-improvement-before.html b/html/learning-room/docs/samples/copilot-improvement-before.html
index 4741209..1d3f976 100644
--- a/html/learning-room/docs/samples/copilot-improvement-before.html
+++ b/html/learning-room/docs/samples/copilot-improvement-before.html
@@ -92,5 +92,6 @@ 
        Summary
        
     
        GIT Going with GitHub - A workshop by Community Access
        
     
        View on GitHub · community-access.org
        
   
+
   
-
\ No newline at end of file
+
diff --git a/html/learning-room/docs/samples/fork-workflow-checklist.html b/html/learning-room/docs/samples/fork-workflow-checklist.html
index 0957a1a..d131580 100644
--- a/html/learning-room/docs/samples/fork-workflow-checklist.html
+++ b/html/learning-room/docs/samples/fork-workflow-checklist.html
@@ -62,76 +62,76 @@ 
        Fork Workflow Checklist
        
 
        Use this checklist to complete the fork-clone-branch-push-PR workflow for Challenge 16 (Capstone). Check off each step as you complete it.
        
 
        Phase 1: Fork the repository
        
 
          
-
        •   Go to the original repository on GitHub.com
          • 
-
        •   Select the Fork button (top-right of the page)
          • 
-
        •   Confirm the fork is created under your account (the URL should show github.com/YOUR-USERNAME/repository-name)
          • 
+
        •  Go to the original repository on GitHub.com
          • 
+
        •  Select the Fork button (top-right of the page)
          • 
+
        •  Confirm the fork is created under your account (the URL should show github.com/YOUR-USERNAME/repository-name)
          • 
 
        
 
        Phase 2: Clone your fork
        
 
        Choose your tool:
        
 
        VS Code
        
 
          
-
        •   Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
          • 
-
        •   Type "Git: Clone" and paste your fork's URL
          • 
-
        •   Select a local folder when prompted
          • 
-
        •   Open the cloned repository when VS Code offers
          • 
+
        •  Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
          • 
+
        •  Type "Git: Clone" and paste your fork's URL
          • 
+
        •  Select a local folder when prompted
          • 
+
        •  Open the cloned repository when VS Code offers
          • 
 
        
 
        GitHub Desktop
        
 
          
-
        •   File > Clone Repository
          • 
-
        •   Paste your fork's URL or find it in the list
          • 
-
        •   Select a local path and clone
          • 
+
        •  File > Clone Repository
          • 
+
        •  Paste your fork's URL or find it in the list
          • 
+
        •  Select a local path and clone
          • 
 
        
 
        CLI
        
 
          
-
        •   Run: git clone https://github.com/YOUR-USERNAME/repository-name.git
          • 
-
        •   Run: cd repository-name
          • 
+
        •  Run: git clone https://github.com/YOUR-USERNAME/repository-name.git
          • 
+
        •  Run: cd repository-name
          • 
 
        
 
        Phase 3: Create a branch
        
 
          
-
        •   Create a branch named agent/YOUR-USERNAME
          • 
-
        •   VS Code: Command Palette > "Git: Create Branch"
          • 
-
        •   GitHub Desktop: Branch > New Branch
          • 
-
        •   CLI: git checkout -b agent/YOUR-USERNAME
          • 
+
        •  Create a branch named agent/YOUR-USERNAME
          • 
+
        •  VS Code: Command Palette > "Git: Create Branch"
          • 
+
        •  GitHub Desktop: Branch > New Branch
          • 
+
        •  CLI: git checkout -b agent/YOUR-USERNAME
          • 
 
        
 
        Phase 4: Make your changes
        
 
          
-
        •   Create your agent file in the correct location
          • 
-
        •   Verify the YAML frontmatter is valid (check for --- delimiters)
          • 
-
        •   Verify you have both Responsibilities and Guardrails sections
          • 
+
        •  Create your agent file in the correct location
          • 
+
        •  Verify the YAML frontmatter is valid (check for --- delimiters)
          • 
+
        •  Verify you have both Responsibilities and Guardrails sections
          • 
 
        
 
        Phase 5: Commit and push
        
 
          
-
        •   Stage your changes
          • 
-
        •   Write a meaningful commit message
          • 
-
        •   Commit
          • 
-
        •   Push to your fork
          • 
-
        •   VS Code: Command Palette > "Git: Push"
          • 
-
        •   GitHub Desktop: "Publish branch" or "Push origin"
          • 
-
        •   CLI: git push -u origin agent/YOUR-USERNAME
          • 
+
        •  Stage your changes
          • 
+
        •  Write a meaningful commit message
          • 
+
        •  Commit
          • 
+
        •  Push to your fork
          • 
+
        •  VS Code: Command Palette > "Git: Push"
          • 
+
        •  GitHub Desktop: "Publish branch" or "Push origin"
          • 
+
        •  CLI: git push -u origin agent/YOUR-USERNAME
          • 
 
        
 
        Phase 6: Open a cross-fork pull request
        
 
          
-
        •   Go to the original repository on GitHub.com (not your fork)
          • 
-
        •   You should see a banner offering to create a PR from your recently pushed branch
          • 
-
        •   If no banner: Pull requests > New pull request > "compare across forks"
          • 
-
        •   Set base repository to the original, base branch to main
          • 
-
        •   Set head repository to your fork, compare branch to agent/YOUR-USERNAME
          • 
-
        •   Write a clear PR title and description
          • 
-
        •   Submit the pull request
          • 
+
        •  Go to the original repository on GitHub.com (not your fork)
          • 
+
        •  You should see a banner offering to create a PR from your recently pushed branch
          • 
+
        •  If no banner: Pull requests > New pull request > "compare across forks"
          • 
+
        •  Set base repository to the original, base branch to main
          • 
+
        •  Set head repository to your fork, compare branch to agent/YOUR-USERNAME
          • 
+
        •  Write a clear PR title and description
          • 
+
        •  Submit the pull request
          • 
 
        
 
        Phase 7: Peer review
        
 
          
-
        •   Find a classmate's capstone PR
          • 
-
        •   Review their agent file
          • 
-
        •   Leave at least one constructive comment
          • 
-
        •   Submit your review
          • 
+
        •  Find a classmate's capstone PR
          • 
+
        •  Review their agent file
          • 
+
        •  Leave at least one constructive comment
          • 
+
        •  Submit your review
          • 
 
        
 
        Verification
        
 
        After completing all phases, verify:
        
 
          
-
        •   Your fork exists at github.com/YOUR-USERNAME/repository-name
          • 
-
        •   Your PR appears in the original repository's Pull requests tab
          • 
-
        •   The autograder has run on your PR (look for status checks)
          • 
+
        •  Your fork exists at github.com/YOUR-USERNAME/repository-name
          • 
+
        •  Your PR appears in the original repository's Pull requests tab
          • 
+
        •  The autograder has run on your PR (look for status checks)
          • 
 
        
 
   
    
@@ -139,5 +139,6 @@ 
    Verification
    
     
    GIT Going with GitHub - A workshop by Community Access
    
     
    View on GitHub · community-access.org
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/learning-room/docs/setup-guide.html b/html/learning-room/docs/setup-guide.html
index 672514f..c879546 100644
--- a/html/learning-room/docs/setup-guide.html
+++ b/html/learning-room/docs/setup-guide.html
@@ -61,6 +61,9 @@
     
    Setup Guide
    
 
    Getting Ready to Contribute with a Screen Reader
    
 
    This guide walks you through everything you need to set up before your first GitHub contribution. Complete all steps before the workshop begins.
    
+
    
+
    Workshop practice file: This Learning Room copy intentionally contains a few small issues for students to find and fix during the workshop. Follow your assigned challenge issue before changing any [TODO] marker or broken sample link.
    
+
    
 
    Step 1 - Create a GitHub Account
    
 
    If you don't already have a GitHub account, create one at github.com/join.
    
 
    Account name tips:
    
@@ -126,10 +129,10 @@ 
    Step 6 - Fork the Workshop Reposi
 
    Step 7 - Verify Your Setup
    
 
    Before the workshop begins, confirm that you can:
    
 
      
-
    •   Navigate to github.com and read the page headings with your screen reader
      • 
-
    •   Find and read an issue in the Issues tab of the workshop repository
      • 
-
    •   Read a pull request description
      • 
-
    •   Access your account settings
      • 
+
    •  Navigate to github.com and read the page headings with your screen reader
      • 
+
    •  Find and read an issue in the Issues tab of the workshop repository
      • 
+
    •  Read a pull request description
      • 
+
    •  Access your account settings
      • 
 
    
 
    If any of these steps are difficult, bring your question to the workshop. There will be dedicated setup time at the start of Day 1.
    
 
    Getting Help Before the Workshop
    
@@ -138,12 +141,13 @@ 
    Getting Help Before the Workshop
    
 
  • Open an issue in the workshop repository using the "Feature or Improvement Request" template
    • 
 
  • Ask your question in the issue - be specific about what step you are on and what happens when you try it
    • 
 
-
    Note: Links marked [TODO] in this document need to be updated before the workshop. See the facilitator guide for details.
    
+
    Facilitator note: Links marked [TODO] and the sample broken link in this document are intentional practice targets for student issues and pull requests.
    
 
   
    
   
+
   
-
\ No newline at end of file
+
diff --git a/html/learning-room/docs/skills-bonus-scenarios.html b/html/learning-room/docs/skills-bonus-scenarios.html
new file mode 100644
index 0000000..ff7b15b
--- /dev/null
+++ b/html/learning-room/docs/skills-bonus-scenarios.html
@@ -0,0 +1,141 @@
+
+
+
+  
+  
+  
+  Skills-Inspired Bonus Scenarios - GIT Going with GitHub
+  
+  
+  
+  
+
+
+  
+  
+  
    
+    
    Skills-Inspired Bonus Scenarios
    
+
    These optional scenarios adapt selected GitHub Skills exercises into this Learning Room environment. They are optional because they add value for advanced students without changing the required 21-challenge path.
    
+
    Source Documentation
    
+
    Primary references:
    
+
+
    Selection Criteria
    
+
    A Skills exercise is included only when it:
    
+
      
+
    1. Reinforces an existing workshop learning objective.
      2. 
+
    2. Fits private classroom repositories without external setup overhead.
      3. 
+
    3. Provides additional practice depth without changing progression automation.
      4. 
+
    
+
    Consolidated Scenarios
    
+
    Scenario 1: PR Description Quality Drill
    
+
      
+
    • Mapped challenge: Challenge 6 and Challenge 11
      • 
+
    • Skills source: skills/introduction-to-github (step that checks PR title and description)
      • 
+
    • Value add: students practice writing a precise title and a non-empty, reviewer-ready description.
      • 
+
    
+
    Suggested task:
    
+
      
+
    1. Rewrite your PR description using a three-part structure: what, why, validation.
      2. 
+
    2. Ensure issue linkage uses Closes #N.
      3. 
+
    3. Ask a peer whether they can understand the change without opening files.
      4. 
+
    
+
    Scenario 2: Structured Review Verdict Practice
    
+
      
+
    • Mapped challenge: Challenge 12
      • 
+
    • Skills source: skills/review-pull-requests (review submission flow)
      • 
+
    • Value add: improves feedback quality and confidence in choosing review verdicts.
      • 
+
    
+
    Suggested task:
    
+
      
+
    1. Leave one praise comment and one actionable change request.
      2. 
+
    2. Submit a review verdict and explain it in one sentence.
      3. 
+
    3. Follow up with one response after the author updates the PR.
      4. 
+
    
+
    Scenario 3: Merge Conflict Recovery Replay
    
+
      
+
    • Mapped challenge: Challenge 7
      • 
+
    • Skills source: skills/resolve-merge-conflicts
      • 
+
    • Value add: gives a second controlled repetition for students who need confidence after first conflict resolution.
      • 
+
    
+
    Suggested task:
    
+
      
+
    1. Reproduce a simple conflict on a disposable practice branch.
      2. 
+
    2. Resolve by combining both useful lines and removing markers.
      3. 
+
    3. Document what decision strategy you used.
      4. 
+
    
+
    Scenario 4: Workflow Event Tracing for Advanced Students
    
+
      
+
    • Mapped challenge: Bonus E
      • 
+
    • Skills source: Skills quickstart workflow-event mapping guidance
      • 
+
    • Value add: students learn how actions events drive progression and feedback.
      • 
+
    
+
    Suggested task:
    
+
      
+
    1. Pick one action run from your repository history.
      2. 
+
    2. Identify event type, job, and outcome.
      3. 
+
    3. Explain which student action triggered that run.
      4. 
+
    
+
    Integration Notes
    
+
      
+
    • These scenarios are optional and do not alter the 21 official challenges.
      • 
+
    • Facilitators can assign them to fast finishers as enrichment.
      • 
+
    • Core validation and progression workflows remain unchanged.
      • 
+
    
+
+  
    
+  
+
+  
+
diff --git a/html/learning-room/docs/solutions/index.html b/html/learning-room/docs/solutions/index.html
new file mode 100644
index 0000000..53c9b09
--- /dev/null
+++ b/html/learning-room/docs/solutions/index.html
@@ -0,0 +1,182 @@
+
+
+
+  
+  
+  
+  Learning Room Solutions Index - GIT Going with GitHub
+  
+  
+  
+  
+
+
+  
+  
+  
    
+    
    Learning Room Solutions Index
    
+
    Use this index when you are blocked and need a worked example. Try the challenge first, then compare your approach with the reference.
    
+
    How To Use This Folder
    
+
      
+
    1. Read your assigned challenge issue and attempt the work.
      2. 
+
    2. If you are stuck, check the matching solution link below.
      3. 
+
    3. Compare your result and revise your submission.
      4. 
+
    4. If your approach is different but still valid, that is okay.
      5. 
+
    
+
    Core Challenges (1-16)
    
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    ChallengeSolution
    Challenge 1: Find Your Way Aroundsolution-01-scavenger-hunt.md
    Challenge 2: File Your First Issuesolution-02-first-issue.md
    Challenge 3: Join the Conversationsolution-03-conversation.md
    Challenge 4: Branch Outsolution-04-branch-out.md
    Challenge 5: Make Your Marksolution-05-make-your-mark.md
    Challenge 6: Open Your First Pull Requestsolution-06-first-pr.md
    Challenge 7: Survive a Merge Conflictsolution-07-merge-conflict.md
    Challenge 8: The Culture Layersolution-08-culture.md
    Challenge 9: Merge Daysolution-09-merge-day.md
    Challenge 10: Go Localsolution-10-go-local.md
    Challenge 11: Open a Day 2 PRsolution-11-day2-pr.md
    Challenge 12: Review Like a Prosolution-12-review.md
    Challenge 13: AI as Your Copilotsolution-13-copilot.md
    Challenge 14: Template Remixsolution-14-template.md
    Challenge 15: Meet the Agentssolution-15-agents.md
    Challenge 16: Build Your Agent (Capstone)solution-16-capstone.md
    
+
    Bonus Challenges (A-E)
    
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    Bonus ChallengeSolution
    Bonus A: Improve an Existing Agentsolution-bonus-a.md
    Bonus B: Document Your Journeysolution-bonus-b.md
    Bonus C: Create a Group Challengesolution-bonus-c.md
    Bonus D: Notification Masterysolution-bonus-d.md
    Bonus E: Explore Git History Visuallysolution-bonus-e.md
    
+
+
    For extra scenario practice inspired by GitHub Skills courses, see Skills-Inspired Bonus Scenarios.
    
+
+  
    
+  
+
+  
+
diff --git a/html/learning-room/docs/welcome.html b/html/learning-room/docs/welcome.html
index c3c2a58..176adcb 100644
--- a/html/learning-room/docs/welcome.html
+++ b/html/learning-room/docs/welcome.html
@@ -60,6 +60,9 @@
   
    
     
    Welcome to Open Source Contribution
    
 
    This guide is for people who are new to contributing to open source software. It explains what contribution means, who it is for, and how to get started.
    
+
    
+
    Workshop practice file: This Learning Room copy intentionally includes [TODO] sections for students to complete during the contribution challenges. If you are not working on the assigned challenge, leave the placeholders in place.
    
+
    
 
    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: