diff --git a/admin/qa-bundle/GO-LIVE-QA-GUIDE.md b/admin/qa-bundle/GO-LIVE-QA-GUIDE.md index 5d5b86f..f74079a 100644 --- a/admin/qa-bundle/GO-LIVE-QA-GUIDE.md +++ b/admin/qa-bundle/GO-LIVE-QA-GUIDE.md @@ -2,6 +2,8 @@ Use this guide before a cohort is opened to learners. It is the release gate for curriculum content, GitHub Classroom deployment, Learning Room automation, podcast materials, accessibility, and human test coverage. +For end-to-end execution details, use [admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md](admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md) as the operator procedure. This guide is the release gate summary; the runbook is the required execution playbook. + The goal is simple: a facilitator should be able to create a classroom, seed test repositories, complete every challenge path, validate every generated artifact, and know exactly what remains before students arrive. ## Release Decision @@ -34,9 +36,21 @@ Do not mark a cohort ready until all required items in this section are complete - [ ] Human testers completed the Day 1, Day 2, bonus, accessibility, and content-review passes below. - [ ] Challenge tracking log includes explicit status and evidence for Challenges 1-16 and Bonus A-E. - [ ] Challenge reliability matrix includes happy path, failure path, and recovery evidence for each challenge family. +- [ ] Runbook Phase 8 required checklist is complete in [admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md](admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md). +- [ ] Student recovery Level 2 restore test is completed and evidenced with branch and PR links. - [ ] All in-scope automation workflows and facilitator scripts were validated with expected behavior and evidence. +- [ ] Local non-podcast readiness evidence is recorded in [admin/qa-readiness](admin/qa-readiness/README.md). - [ ] All blocking findings have a fix, owner, or written release exception. +No-go conditions: + +- Any Blocker finding remains open. +- Any required runbook Phase 8 gate is incomplete without explicit release-owner exception. +- Student progression, PR validation, or required autograder behavior is not reproducible in a test student repository. +- Template freshness proof is missing or shows drift from the latest merged template sync. +- Required QA evidence links are missing for release-signoff claims. +- Support channel links point to deprecated destinations and not to `support`. + ## Source Of Truth The following table lists each release artifact and the document that controls it. @@ -88,6 +102,8 @@ Expected results: Record the command output summary in the release notes or QA issue. +Required evidence destination for local readiness: [admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md](admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md) or an equivalent dated report in the same folder. + ## Phase 2: Content Inventory Review Every content file must be reviewed before go-live. Use this checklist to assign coverage. diff --git a/admin/qa-bundle/README.md b/admin/qa-bundle/README.md index c93f67f..ff81689 100644 --- a/admin/qa-bundle/README.md +++ b/admin/qa-bundle/README.md @@ -1,38 +1,297 @@ -# QA Bundle (Grab-and-Go) +# GIT Going with GitHub -This folder is a convenience copy of the files needed to run end-to-end QA for the course (excluding podcast workflows). +License: CC BY 4.0 | [Site](https://community-access.org/git-going-with-github/) | [Discussions](https://github.com/community-access/git-going-with-github/discussions) -## What this bundle is for +## A Workshop by [Community Access](https://community-access.org) -Use this folder when you want quick local access to all key QA artifacts without navigating the full repo. +> **Welcome.** This repository is your complete guide and companion for the two-day GIT Going with GitHub workshop. Every document here is written to be read with or without a screen reader. All steps are keyboard-accessible. You belong here. +> +> **About Community Access:** [Community Access](https://community-access.org) is a community of blind and low vision technology professionals. Visit [community-access.org](https://community-access.org) to learn more. -## Start here +| Detail | Information | +|---|---| +| **Workshop site** | [community-access.org/git-going-with-github](https://community-access.org/git-going-with-github/) | +| **Registration** | [Student opt-in and waitlist workflow](https://community-access.org/git-going-with-github/REGISTER.html) | +| **Discussions** | [Join the conversation](https://github.com/community-access/git-going-with-github/discussions) | +| **Support hub** | [Community-Access/support](https://github.com/Community-Access/support) | +| **Curriculum issues** | [File an issue in this repository](https://github.com/community-access/git-going-with-github/issues) | +| **Dates** | May 21, 2026 & May 22, 2026 | +| **Facilitators** | Jeff Bishop and Michael Babcock | -1. [admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md](admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md) -2. [GO-LIVE-QA-GUIDE.md](GO-LIVE-QA-GUIDE.md) -3. [admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md](admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md) -## Included content sets +> **The Central Project: Accessibility Agents** +> +> 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. 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. -- Registration deployment and QA docs and workflow files. -- Classroom deployment and autograding setup docs. -- Learning Room automation docs, workflows, and issue templates. -- Facilitator scripts for template sync, seeding, conflict setup, and recovery. -- Challenge definitions and student onboarding references. -- Local unit-test readiness evidence. -## HTML copy of E2E runbook +## What Is This Event? -- [admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html](admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html) +During this two-day workshop, you will learn how to confidently navigate and contribute to open source projects on GitHub using: -## Important notes +- A **screen reader** (NVDA on Windows, JAWS on Windows, or VoiceOver on macOS) +- **Keyboard-only navigation** - no mouse required +- **GitHub Copilot** (Day 2) - AI-assisted writing and coding in the browser and in VS Code -- This bundle is a convenience snapshot, not the canonical source of truth. -- Canonical files remain in the repository root paths. -- Rebuild this bundle after significant workflow/challenge/runbook updates. +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. -## Local vs GitHub deployment for unit tests -- Unit tests run locally with `npm run test:automation`. -- GitHub deployment is not required to execute local unit tests. -- Hosted GitHub/Classroom gates are still required for final release readiness. +## Who Is This For? + +This event is designed for: + +- People new to GitHub who use assistive technology +- Developers who use screen readers and want to contribute to open source +- Anyone who is curious about accessible development workflows +- Sighted participants are welcome - all content is keyboard-navigable for everyone + +You do **not** need to know how to code to participate and contribute meaningfully. Documentation improvements, issue filing, accessibility bug reports, and code reviews are all valuable contributions. + + +## Two-Day Overview + +| Day | Focus | What You Will Do | +|-----|-------|-----------------| +| **Day 1** | GitHub Foundations | Set up your environment, learn GitHub navigation with your screen reader, file your first issue, open your first pull request | +| **Day 2** | VS Code + Accessibility Agents | Bridge from the browser to **github.dev** (VS Code in your browser - no install needed), then step into **Visual Studio Code** on the desktop, learn VS Code basics, use GitHub Copilot, activate the Accessibility Agents ecosystem (55 agents, 3 teams, 5 platforms), see agentic workflows in the cloud, and prepare a real upstream contribution path | + +### The Journey Arc + +This is not a two-day course with two separate syllabi. It is one arc. + +``` +Day 1 - Learn the skill in the browser + Navigate → Issue → Pull Request → Review → Merge + + ↓ (bridge: press . on any GitHub repo - VS Code opens right in your browser) + +github.dev - VS Code on the web, no install needed + Same keyboard shortcuts · Same screen reader mode · Edit files · Open PRs + What it cannot do: no terminal, no Copilot agents, no local extensions + + ↓ (you've earned the desktop - now it makes sense) + +Day 2 - Deepen with VS Code + Accessibility Agents + Learn VS Code basics → Copilot inline → Copilot Chat + @daily-briefing → @issue-tracker → @pr-review → @analytics → prepare upstream +``` + +Every skill you build on Day 1 maps directly to an Accessibility Agents command on Day 2. The agent is not a shortcut - it is a multiplier. You have to understand what it is doing to know when it is wrong. + +**By the end of the Day 2 core path, you will have:** +- A fork of `accessibility-agents` with your personalized preferences +- A branch or pull request path for a real open source contribution +- Clear next steps to get your contribution reviewed and merged +- A working set of 55 AI agents across 3 teams that travel with your fork to any repository you apply them to + + +## How to Read These Docs + +All documentation lives in the `docs/` folder. If you are new, start with [Get Going with GitHub](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. + +## Post-Workshop Support + +After the workshop, use the open support repository for questions, troubleshooting, and alumni discussion: + +- [Community-Access/support](https://github.com/Community-Access/support) + +Use this repository for curriculum and platform changes only. + + +## Your Challenges + +**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](docs/CHALLENGES.md) has the full list with instructions, evidence requirements, and links. + +**The workflow:** +1. Open the challenge issue template for the current chapter +2. Follow the instructions in the issue and the corresponding chapter +3. Complete the challenge and post your evidence +4. Open a PR that references your issue with `Closes #N` +5. The validation bot checks your work +6. When it passes, merge and move to the next challenge + +Every chapter has an "If You Get Stuck" section. Every challenge has a [reference solution](docs/solutions/). You do not need to memorize anything. + + +> **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. 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 + +> **Looking for a student-friendly table of contents?** See the [Course Guide](docs/course-guide.md) - a single page with day-by-day chapter tables, grouped appendices, all 24 exercises at a glance, and where to get help. + +**Chapters** + +| # | 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 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 | +| [08](docs/08-open-source-culture.md) | **Open Source Culture** | Community norms, contributing, giving feedback | +| [09](docs/09-labels-milestones-projects.md) | **Labels, Milestones, and Projects** | Organizing and cross-referencing work | +| [10](docs/10-notifications-and-day-1-close.md) | **Notifications and Day 1 Close** | Managing your inbox, merging your work, Day 1 recap | +| [11](docs/11-vscode-interface.md) | **VS Code Interface** | VS Code accessibility, screen reader mode, keyboard navigation | +| [12](docs/12-vscode-accessibility.md) | **VS Code Accessibility** | Accessibility signals, Accessible View, Accessible Diff Viewer | +| [13](docs/13-how-git-works.md) | **How Git Works** | Commits, branches, merges, and the mental model | +| [14](docs/14-git-in-practice.md) | **Git in Practice** | Clone, branch, edit, commit, push using VS Code and terminal | +| [15](docs/15-code-review.md) | **Code Review** | PR extension, diffs, inline comments, review verdicts | +| [16](docs/16-github-copilot.md) | **GitHub Copilot** | Inline suggestions, Copilot Chat, prompting, Accessible View | +| [17](docs/17-issue-templates.md) | **Issue Templates** | Creating and using GitHub issue templates | +| [18](docs/18-fork-and-contribute.md) | **Fork and Contribute** | Fork workflow, upstream sync, cross-repo contributions | +| [19](docs/19-accessibility-agents.md) | **Accessibility Agents** | 55 agents across 3 teams, contributing to the ecosystem | +| [20](docs/20-build-your-agent.md) | **Build Your Own Agent** | Design an agent with responsibilities and guardrails (capstone) | +| [21](docs/21-next-steps.md) | **Next Steps** | Where to go after the workshop | + +**Workshop Agendas** - For facilitators only (not part of learner sequence) + +| Document | What It Covers | +|----------|----------------| +| [DAY1_AGENDA.md](admin/DAY1_AGENDA.md) | Full Day 1 schedule, objectives, and activities | +| [DAY2_AGENDA.md](admin/DAY2_AGENDA.md) | Full Day 2 schedule, objectives, and activities | + +**Appendices** - Reference material; open any time during the workshop + +| Appendix | Document | What It Covers | +|---|---|---| +| [A](docs/appendix-a-glossary.md) | **GitHub Concepts Glossary** | Every term, concept, and piece of jargon explained | +| [B](docs/appendix-b-screen-reader-cheatsheet.md) | **Screen Reader Cheat Sheet** | Complete NVDA, JAWS, and VoiceOver navigation commands - task-based and per-screen-reader - plus the full GitHub built-in keyboard shortcut system | +| [C](docs/appendix-m-accessibility-standards.md) | **Accessibility Standards Reference** | WCAG 2.2 success criteria, ARIA roles and patterns, and a quick-reference PR checklist | +| [D](docs/appendix-d-git-authentication.md) | **Git Authentication** | SSH keys, Personal Access Tokens, credential storage, and commit signing | +| [E](docs/appendix-c-markdown-reference.md) | **GitHub Flavored Markdown** | Alert blocks, collapsible sections, Mermaid diagrams, math, footnotes, heading anchors, and screen reader guidance | +| [F](docs/appendix-u-discussions-and-gists.md) | **GitHub Gists** | Code snippets, sharing, embedding, and cloning | +| [G](docs/appendix-u-discussions-and-gists.md) | **GitHub Discussions** | Forum-style conversations, Q&A, polls, and accessibility navigation for discussion threads | +| [H](docs/appendix-s-releases-tags-insights.md) | **Releases, Tags, and Repository Insights** | Versioned releases, semver, reading release notes, pulse, contributors, traffic, and Insights metrics | +| [I](docs/appendix-r-projects-deep-dive.md) | **GitHub Projects Deep Dive** | Boards, tables, roadmaps, custom fields, automations, iterations, cross-repo projects, and accessible navigation | +| [J](docs/appendix-n-advanced-search.md) | **GitHub Advanced Search** | Complete query language reference for searching issues, PRs, code, commits, and repositories | +| [K](docs/appendix-o-branch-protection.md) | **Branch Protection and Rulesets** | Required reviews, status checks, repository rulesets, and diagnosing why your PR cannot be merged | +| [L](docs/appendix-p-security-features.md) | **GitHub Security Features** | Dependabot alerts and updates, secret scanning, code scanning/CodeQL, private vulnerability reporting, and SBOM | +| [M](docs/appendix-g-vscode-reference.md) | **VS Code Accessibility Reference** | Complete technical reference for all accessibility settings, audio cues, diff viewer, screen reader configurations, keyboard shortcuts | +| [N](docs/appendix-j-cloud-editors.md) | **GitHub Codespaces** | Cloud development environments - setup, accessibility configuration, and screen reader usage | +| [O](docs/appendix-v-github-mobile.md) | **GitHub Mobile** | Accessibility guide for iOS and Android - VoiceOver, TalkBack, notifications, and PR reviews | +| [P](docs/appendix-w-github-pages.md) | **Publishing with GitHub Pages** | Deploy a static site from your repository - branch setup, custom domains, CI workflows, and accessibility checks | +| [Q](docs/appendix-q-actions-workflows.md) | **GitHub Actions and Workflows** | Deep-dive reference - automation, status checks, CI/CD workflows, and the path to agentic cloud | +| [R](docs/appendix-t-community-and-social.md) | **GitHub Profile, Sponsors, and Wikis** | Profile README, GitHub Sponsors, and GitHub Wikis | +| [S](docs/appendix-t-community-and-social.md) | **Organizations, Templates, and Repository Settings** | Organizations, repository templates, visibility, archiving, and contributor-relevant settings | +| [T](docs/08-open-source-culture.md) | **Contributing to Open Source** | A first-timer's guide: finding issues, scoping contributions, writing PRs, and building a contribution habit | +| [U](docs/appendix-x-resources.md) | **Resources** | Every link, tool, and reference from this event | +| [V](docs/appendix-l-agents-reference.md) | **Accessibility Agents Reference** | 55 agents, 3 teams, 5 platforms, slash commands, and workspace configuration | +| [W](docs/appendix-k-copilot-reference.md) | **GitHub Copilot Reference** | Copilot features, chat participants, slash commands, MCP servers, and agentic ecosystem | +| [X](docs/appendix-k-copilot-reference.md) | **GitHub Copilot AI Models** | Model comparison, strengths, plan availability, and selection guidance | +| [Y](docs/appendix-y-workshop-materials.md) | **Accessing and Downloading Workshop Materials** | GitHub Pages, GitHub.com, cloning, ZIP download, offline reading, folder guide | +| [Z](docs/appendix-z-github-skills.md) | **GitHub Skills - Complete Course Catalog** | All 36 GitHub Skills modules organized into six learning paths, with links, prerequisites, and integration guidance | +> **Each guide from Lesson 03 onward includes a "Day 2 Amplifier" callout** that shows how Accessibility Agents extends that skill across three scopes: your VS Code editor → your repository (travels with every fork) → the cloud (GitHub Agentic Workflows running without VS Code). **Learn the manual skill first (Chapter 14), then see how it's automated (Chapter 16).** + + +## This Repository's Structure + +> **One repository, everything included.** Clone or fork this repo and you have the complete workshop - all curriculum guides, Accessibility Agents agents and slash commands, YAML issue forms, PR template, and a practice contribution target in `learning-room/`. GitHub Skills modules cannot be bundled here (each participant activates their own copy on their own account), but links are in `.github/ISSUE_TEMPLATE/config.yml`. + +``` +[repo root]/ +├── README.md -- You are here +├── CONTRIBUTING.md -- How to contribute to this repo +├── CODE_OF_CONDUCT.md -- Community standards +├── admin/FACILITATOR_GUIDE.md -- For workshop organizers only +├── admin/DAY1_AGENDA.md -- Day 1 workshop schedule +├── admin/DAY2_AGENDA.md -- Day 2 workshop schedule +├── .github/ +│ ├── ISSUE_TEMPLATE/ +│ │ ├── config.yml -- Links to GitHub Skills; disables blank issues +│ │ ├── challenge-*.yml -- 16 core challenge templates +│ │ ├── bonus-*.yml -- 5 bonus challenge templates +│ │ ├── accessibility-bug.yml -- Structured accessibility bug form +│ │ └── feature-request.yml -- Feature/improvement request form +│ ├── PULL_REQUEST_TEMPLATE.md -- PR checklist with accessibility section +│ ├── workflows/ -- CI/CD and autograding workflows +│ ├── agents/ -- 55 Accessibility Agents for Copilot Chat +│ └── prompts/ -- 54+ slash commands for Copilot Chat +├── classroom/ -- GitHub Classroom setup artifacts +│ ├── README.md -- Workshop Deployment Guide (unified setup for new cohorts) +│ ├── assignment-day1-you-belong-here.md +│ ├── assignment-day2-you-can-build-this.md +│ ├── autograding-day1.json +│ ├── autograding-day2.json +│ ├── roster-template.csv +│ ├── grading-guide.md +│ └── teardown-checklist.md +├── learning-room/ -- GitHub Classroom template copied into each student's private repo +│ ├── README.md +│ └── docs/ +│ ├── welcome.md -- Has TODO sections for you to complete +│ ├── keyboard-shortcuts.md -- Has intentional accessibility issues to fix +│ └── setup-guide.md -- Has a broken link to find and fix +├── docs/ -- Full workshop curriculum (22 chapters + appendices) +│ ├── course-guide.md -- Student landing page +│ ├── CHALLENGES.md -- Challenge Hub: all 21 challenges +│ ├── 00-pre-workshop-setup.md through 21-next-steps.md +│ ├── appendix-a-glossary.md through appendix-z-github-skills.md +│ └── solutions/ -- Reference solutions for every challenge +├── podcasts/ -- Audio companion episodes +└── PODCASTS.md -- Audio player page +``` + +> *Note: Appendices were renumbered during a February 2026 review. If you encounter external references to "Appendix D" or later letters, subtract one letter (e.g., the former Appendix D is now [Appendix C](docs/appendix-m-accessibility-standards.md)).* + + +## Quick Reference + +These standalone documents provide additional guidance and resources: + +| Document | Description | +|----------|-------------| +| [FAQ](admin/FAQ.md) | Frequently asked questions about the workshop | +| [Quick Reference](admin/QUICK_REFERENCE.md) | Condensed cheat sheet for common tasks | +| [Troubleshooting](admin/TROUBLESHOOTING.md) | Solutions for common setup and workflow issues | +| [Progress Tracker](admin/PROGRESS_TRACKER.md) | Track your learning progress through the workshop | +| [Accessibility Testing](ACCESSIBILITY_TESTING.md) | Accessibility testing procedures and standards | +| [Security](SECURITY.md) | Security policy and vulnerability reporting | +| [GitHub Proposal](GITHUB_PROPOSAL.md) | Original event proposal and curriculum overview (internal reference) | + + +## Screen Reader Users: Start Here + +Before doing anything else, please read [**00 - Pre-Workshop Setup**](docs/00-pre-workshop-setup.md). It will walk you through: + +- Configuring your screen reader for GitHub +- Verifying GitHub's modern interface is working (may already be active - instructions include how to check and enable if needed) +- Turning off settings that make screen reader navigation harder +- Verifying everything works before Day 1 begins + + +## The Goal of This Event + +Open source software is built by people. Accessibility bugs in open source affect millions of people who use assistive technology every day. By learning to contribute - even something as small as filing a clear, detailed accessibility issue - you become part of fixing that. That matters. + +**You don't have to write a single line of code to make open source more accessible.** + +And by the end of Day 2, you will not just be a learner. You will be a product maker - someone who has shipped something real to a project that other people use. + + +## Questions Before the Event? + +- **Discussion Forum:** [Join the conversation](https://github.com/community-access/git-going-with-github/discussions) - ask questions, connect with fellow participants, share ideas +- **File an issue** in this repository if something in these docs is unclear +- **Community:** [GitHub Accessibility Discussions](https://github.com/orgs/community/discussions/categories/accessibility) + + +## License + +All workshop documentation is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) - you are free to share and adapt with attribution. + + +*Last reviewed: May 2026* +*A [Community Access](https://community-access.org) initiative.* diff --git a/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md b/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md index f51cb2a..fe7e5bc 100644 --- a/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md +++ b/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md @@ -33,7 +33,8 @@ Out of scope: ## Canonical Source Files Used by This Runbook -The following table lists the source files this runbook consolidates. + +**Table: Source files consolidated by this runbook** | Area | Source file | |---|---| @@ -50,6 +51,12 @@ The following table lists the source files this runbook consolidates. | Release gate baseline | [GO-LIVE-QA-GUIDE.md](../GO-LIVE-QA-GUIDE.md) | | Support hub operations | [SUPPORT_HUB_OPERATIONS.md](SUPPORT_HUB_OPERATIONS.md) | +**Table: QA validation checkpoints for registration and classroom automation** +**Table: Student journey checkpoints and expected artifacts** +**Table: Label color and purpose for registration automation** +**Table: Screen reader options for workshop setup** +**Table: Accessibility improvements for screen reader users** + ## Required Accounts, Access, and Tools Complete this section before Phase 1. @@ -83,10 +90,6 @@ Complete all items below before any cohort launch actions. - [x] Registration entry configuration exists and is valid: - [x] Issue form template `workshop-registration.yml` exists - [x] Required labels exist: `registration`, `duplicate`, `waitlist` -- [ ] Support hub is ready for student onboarding: - - [ ] `Community-Access/support` is public and reachable - - [ ] Issues and Discussions are enabled - - [ ] Support labels and templates are present - [ ] While signed in as `accesswatch`, opening [classroom.github.com](https://classroom.github.com) shows the `Community-Access-Classroom` classroom organization. If any precondition fails, stop and resolve before proceeding. @@ -521,8 +524,8 @@ Pass criteria: ### Step 1.1 Verify support hub onboarding path 1. Open `Community-Access/support` and confirm Issues and Discussions are enabled. -2. Confirm pinned Start Here onboarding guidance exists in Discussions. -3. Open a test support issue using a template and confirm triage labels apply. +2. Confirm at least one pinned onboarding discussion or Start Here guidance exists. +3. Open a test support issue using a template and confirm labels apply correctly. Pass criteria: diff --git a/admin/qa-bundle/classroom/README.md b/admin/qa-bundle/classroom/README.md index e364436..2638917 100644 --- a/admin/qa-bundle/classroom/README.md +++ b/admin/qa-bundle/classroom/README.md @@ -386,6 +386,7 @@ Follow the [teardown-checklist.md](teardown-checklist.md) for complete post-work 1. **Export grades** from the classroom dashboard 2. **Archive the classroom** in the Classroom UI (this preserves student repos as read-only portfolio pieces) 3. **Review feedback** and update facilitation notes for next cohort +4. **Route ongoing learner support** to [Community-Access/support](https://github.com/Community-Access/support) --- @@ -449,3 +450,4 @@ See [teardown-checklist.md](teardown-checklist.md) for the complete post-worksho - [Challenge Hub](../docs/CHALLENGES.md) -- all 21 challenges with instructions - [Solutions Directory](../docs/solutions/) -- reference solutions for facilitator use - [Grading Guide](grading-guide.md) -- per-challenge rubric and completion levels +- [Support Hub Operations](../admin/SUPPORT_HUB_OPERATIONS.md) -- operating model for async support after the workshop diff --git a/admin/qa-bundle/docs/00-pre-workshop-setup.md b/admin/qa-bundle/docs/00-pre-workshop-setup.md index ed391a9..883a516 100644 --- a/admin/qa-bundle/docs/00-pre-workshop-setup.md +++ b/admin/qa-bundle/docs/00-pre-workshop-setup.md @@ -1,3 +1,7 @@ + +**Table: Screen reader options for workshop setup** + +**Table: Accessibility improvements for screen reader users** # Pre-Workshop Setup - GIT Going with GitHub > > **Listen to Episode 1:** [Pre-Workshop Setup](../admin/PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. @@ -175,7 +179,7 @@ That is it. No tokens to generate, no keys to create, no strings to paste. If yo For this workshop, participants need a GitHub account with 2FA enabled. The browser-based sign-in described above handles all Git authentication automatically - no additional setup is required beyond having a working GitHub account. -If you run into any authentication issues before the workshop, contact the workshop organizers at the email or issue link in this guide so we can help. +If you run into any authentication issues before the workshop, open a support issue at [Community-Access/support/issues](https://github.com/Community-Access/support/issues) or contact the workshop organizers directly. ### Learning Cards: Create Your GitHub Account diff --git a/admin/qa-bundle/learning-room/.github/DEPLOYMENT_VALIDATION.md b/admin/qa-bundle/learning-room/.github/DEPLOYMENT_VALIDATION.md index 764527c..4f9e5e3 100644 --- a/admin/qa-bundle/learning-room/.github/DEPLOYMENT_VALIDATION.md +++ b/admin/qa-bundle/learning-room/.github/DEPLOYMENT_VALIDATION.md @@ -1,3 +1,9 @@ + +**Table: Workflow status and triggers for deployment validation** + +**Table: Error handling scenarios in deployment validation** + +**Table: Metrics for deployment validation and student experience** # Learning Room Automation - Deployment Validation Checklist ## Complete Setup Verification diff --git a/admin/qa-bundle/learning-room/.github/FACILITATOR_GUIDE.md b/admin/qa-bundle/learning-room/.github/FACILITATOR_GUIDE.md index 747b1a2..9e15b7d 100644 --- a/admin/qa-bundle/learning-room/.github/FACILITATOR_GUIDE.md +++ b/admin/qa-bundle/learning-room/.github/FACILITATOR_GUIDE.md @@ -1,3 +1,5 @@ + +**Table: Common facilitator questions and responses** # Learning Room Automation - Facilitator Quick Reference ## What Students See diff --git a/admin/qa-bundle/learning-room/.github/IMPLEMENTATION_GUIDE.md b/admin/qa-bundle/learning-room/.github/IMPLEMENTATION_GUIDE.md index 4657ac8..c7f17f1 100644 --- a/admin/qa-bundle/learning-room/.github/IMPLEMENTATION_GUIDE.md +++ b/admin/qa-bundle/learning-room/.github/IMPLEMENTATION_GUIDE.md @@ -1,3 +1,7 @@ + +**Table: Learning Room workflow automation and triggers** + +**Table: Key documentation files for Learning Room automation** # Learning Room Template: Implementation Guide > **For full workshop deployment instructions, see diff --git a/admin/qa-bundle/learning-room/.github/SETUP_AND_MAINTENANCE.md b/admin/qa-bundle/learning-room/.github/SETUP_AND_MAINTENANCE.md index 06be531..b3c5515 100644 --- a/admin/qa-bundle/learning-room/.github/SETUP_AND_MAINTENANCE.md +++ b/admin/qa-bundle/learning-room/.github/SETUP_AND_MAINTENANCE.md @@ -1,3 +1,7 @@ + +**Table: Workflow automation in the Learning Room** + +**Table: Troubleshooting common issues in Learning Room automation** # Learning Room Automation Setup & Maintenance Guide ## Overview diff --git a/admin/qa-bundle/learning-room/.github/STUDENT_GUIDE.md b/admin/qa-bundle/learning-room/.github/STUDENT_GUIDE.md index 0fe8f47..4a8203b 100644 --- a/admin/qa-bundle/learning-room/.github/STUDENT_GUIDE.md +++ b/admin/qa-bundle/learning-room/.github/STUDENT_GUIDE.md @@ -1,3 +1,5 @@ + +**Table: What the bot does and how it helps students** # How the Learning Room Automation Works - Student Guide ## What Is This Automation? diff --git a/admin/qa-bundle/learning-room/README.md b/admin/qa-bundle/learning-room/README.md index 085cdee..f180f94 100644 --- a/admin/qa-bundle/learning-room/README.md +++ b/admin/qa-bundle/learning-room/README.md @@ -1,3 +1,6 @@ + +**Table: Learning Room folder and file purposes** +**Table: Host voice and character mapping for VibeVoice podcast** # Welcome to the Learning Room This repository is your private Learning Room for the Git Going with GitHub workshop. GitHub Classroom created it from the Learning Room template so you can practice the full contribution workflow safely. In this repository you will: diff --git a/admin/qa-bundle/scripts/classroom/Invoke-LearningRoomEndToEndTest.ps1 b/admin/qa-bundle/scripts/classroom/Invoke-LearningRoomEndToEndTest.ps1 index 54be43c..e91dcc8 100644 --- a/admin/qa-bundle/scripts/classroom/Invoke-LearningRoomEndToEndTest.ps1 +++ b/admin/qa-bundle/scripts/classroom/Invoke-LearningRoomEndToEndTest.ps1 @@ -36,6 +36,11 @@ param( ) $ErrorActionPreference = 'Stop' +# Prevent PowerShell from converting native stderr output into terminating errors. +# Git and gh often emit progress text on stderr even when commands succeed. +if (Get-Variable -Name PSNativeCommandUseErrorActionPreference -ErrorAction SilentlyContinue) { + $PSNativeCommandUseErrorActionPreference = $false +} $script:Results = [System.Collections.Generic.List[object]]::new() $script:CreatedRepository = $false @@ -149,7 +154,10 @@ function Invoke-CheckedCommand { # Generic command execution with special transient-retry support for gh commands. for ($attempt = 1; $attempt -le $Retries; $attempt++) { if ($FilePath -eq 'gh') { + $oldErrorActionPreference = $ErrorActionPreference + $ErrorActionPreference = 'Continue' $output = & gh @Arguments 2>&1 + $ErrorActionPreference = $oldErrorActionPreference $exitCode = $LASTEXITCODE $text = ($output | Out-String).Trim() @@ -191,7 +199,10 @@ function Invoke-GhJson { ) for ($attempt = 1; $attempt -le $Retries; $attempt++) { + $oldErrorActionPreference = $ErrorActionPreference + $ErrorActionPreference = 'Continue' $output = & gh @Arguments 2>&1 + $ErrorActionPreference = $oldErrorActionPreference $exitCode = $LASTEXITCODE $text = ($output | Out-String).Trim() diff --git a/admin/qa-bundle/scripts/classroom/Prepare-LearningRoomTemplate.ps1 b/admin/qa-bundle/scripts/classroom/Prepare-LearningRoomTemplate.ps1 index 310f34f..24a3f4a 100644 --- a/admin/qa-bundle/scripts/classroom/Prepare-LearningRoomTemplate.ps1 +++ b/admin/qa-bundle/scripts/classroom/Prepare-LearningRoomTemplate.ps1 @@ -2,13 +2,20 @@ param( [string]$Owner = 'Community-Access', [string]$TemplateRepo = 'learning-room-template', - [string]$SourcePath = (Join-Path $PSScriptRoot '..\..\learning-room'), + [string]$SourcePath = '', [string]$BranchName = '', - [switch]$NoPush + [switch]$NoPush, + [switch]$SkipSourceValidation ) $ErrorActionPreference = 'Stop' +$scriptDir = if ($PSScriptRoot) { $PSScriptRoot } else { Split-Path -Parent $MyInvocation.MyCommand.Path } + +if (-not $SourcePath) { + $SourcePath = Join-Path $scriptDir '..\..\learning-room' +} + function Invoke-CheckedCommand { param([string]$FilePath, [string[]]$Arguments) & $FilePath @Arguments @@ -25,6 +32,19 @@ if (-not $BranchName) { $BranchName = 'sync/learning-room-template-' + (Get-Date -Format 'yyyyMMddHHmmss') } +if (-not $SkipSourceValidation) { + $validatorPath = Join-Path $scriptDir 'Validate-LearningRoomTemplateSource.ps1' + if (-not (Test-Path -LiteralPath $validatorPath -PathType Leaf)) { + throw "Source validator script was not found: $validatorPath" + } + + Write-Host "Validating Learning Room source before sync..." + & $validatorPath -SourcePath $source.Path +} +else { + Write-Warning "SkipSourceValidation was set. Proceeding without source sanity checks." +} + Write-Host "Checking GitHub CLI authentication..." Invoke-CheckedCommand gh @('auth', 'status', '-h', 'github.com') @@ -56,6 +76,22 @@ try { Push-Location $clonePath try { + $gitEmail = (git config user.email 2>$null) + $gitName = (git config user.name 2>$null) + if (-not $gitEmail -or -not $gitName) { + $login = (& gh api /user --jq '.login' 2>$null) + if (-not $login) { + $login = 'github-actions' + } + $fallbackEmail = "$login@users.noreply.github.com" + if (-not $gitName) { + Invoke-CheckedCommand git @('config', 'user.name', $login) + } + if (-not $gitEmail) { + Invoke-CheckedCommand git @('config', 'user.email', $fallbackEmail) + } + } + Invoke-CheckedCommand git @('add', '-A') $status = git status --short if (-not $status) { @@ -73,8 +109,14 @@ try { Invoke-CheckedCommand git @('commit', '-m', 'chore: sync learning room template') Invoke-CheckedCommand git @('push', '--force', '-u', 'origin', "HEAD:$BranchName") - $existingPr = & gh pr view $BranchName -R $fullRepo --json url --jq .url 2>$null - if ($LASTEXITCODE -eq 0 -and $existingPr) { + $existingPr = $null + try { + $existingPr = & gh pr view $BranchName -R $fullRepo --json url --jq .url 2>$null + } + catch { + $existingPr = $null + } + if ($existingPr) { Write-Host "Updated existing pull request: $existingPr" } else { diff --git a/admin/qa-bundle/scripts/classroom/Test-LearningRoomTemplate.ps1 b/admin/qa-bundle/scripts/classroom/Test-LearningRoomTemplate.ps1 index b2d361e..8ebc6d6 100644 --- a/admin/qa-bundle/scripts/classroom/Test-LearningRoomTemplate.ps1 +++ b/admin/qa-bundle/scripts/classroom/Test-LearningRoomTemplate.ps1 @@ -16,6 +16,38 @@ function Invoke-CheckedCommand { } } +function Wait-ForRepositoryContent { + param( + [string]$Repository, + [int]$MaxAttempts = 12, + [int]$DelaySeconds = 5 + ) + + for ($attempt = 1; $attempt -le $MaxAttempts; $attempt++) { + $isReady = $false + try { + & gh api "repos/$Repository/contents/.github/workflows/student-progression.yml" 1>$null 2>$null + if ($LASTEXITCODE -eq 0) { + $isReady = $true + } + } + catch { + $isReady = $false + } + + if ($isReady) { + return + } + + if ($attempt -lt $MaxAttempts) { + Write-Host "Template contents not ready yet (attempt $attempt/$MaxAttempts). Retrying in $DelaySeconds seconds..." + Start-Sleep -Seconds $DelaySeconds + } + } + + throw "Repository content did not become available in time for $Repository." +} + $template = "$Owner/$TemplateRepo" $smoke = "$Owner/$SmokeRepo" @@ -23,6 +55,9 @@ Write-Host "Creating smoke-test repository $smoke from $template..." Invoke-CheckedCommand gh @('repo', 'create', $smoke, '--private', '--template', $template) try { + Write-Host "Waiting for template content to materialize in smoke repository..." + Wait-ForRepositoryContent -Repository $smoke + Write-Host "Checking expected template files..." Invoke-CheckedCommand gh @('api', "repos/$smoke/contents/.github/workflows/student-progression.yml") Invoke-CheckedCommand gh @('api', "repos/$smoke/contents/.github/ISSUE_TEMPLATE/challenge-01-find-your-way.yml") @@ -37,6 +72,10 @@ try { finally { if (-not $KeepSmokeRepo) { Write-Host "Deleting smoke-test repository $smoke..." - Invoke-CheckedCommand gh @('repo', 'delete', $smoke, '--yes') + & gh repo delete $smoke --yes + if ($LASTEXITCODE -ne 0) { + Write-Warning "Could not delete smoke repository automatically. This does not invalidate smoke validation." + Write-Warning "Delete manually when convenient: gh repo delete $smoke --yes" + } } } diff --git a/html/admin/qa-bundle/GO-LIVE-QA-GUIDE.html b/html/admin/qa-bundle/GO-LIVE-QA-GUIDE.html index 4e6010d..1505d4a 100644 --- a/html/admin/qa-bundle/GO-LIVE-QA-GUIDE.html +++ b/html/admin/qa-bundle/GO-LIVE-QA-GUIDE.html @@ -60,6 +60,7 @@

Git Going with GitHub Go-Live QA Guide

Use this guide before a cohort is opened to learners. It is the release gate for curriculum content, GitHub Classroom deployment, Learning Room automation, podcast materials, accessibility, and human test coverage.

+

For end-to-end execution details, use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md as the operator procedure. This guide is the release gate summary; the runbook is the required execution playbook.

The goal is simple: a facilitator should be able to create a classroom, seed test repositories, complete every challenge path, validate every generated artifact, and know exactly what remains before students arrive.

Release Decision

Do not mark a cohort ready until all required items in this section are complete.

@@ -90,9 +91,21 @@

Release Decision

  • Human testers completed the Day 1, Day 2, bonus, accessibility, and content-review passes below.
  • Challenge tracking log includes explicit status and evidence for Challenges 1-16 and Bonus A-E.
  • Challenge reliability matrix includes happy path, failure path, and recovery evidence for each challenge family.
    • +
  • Runbook Phase 8 required checklist is complete in admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md.
    • +
  • Student recovery Level 2 restore test is completed and evidenced with branch and PR links.
  • All in-scope automation workflows and facilitator scripts were validated with expected behavior and evidence.
    • +
  • Local non-podcast readiness evidence is recorded in admin/qa-readiness.
  • All blocking findings have a fix, owner, or written release exception.
    • +

    No-go conditions:

    +

    Source Of Truth

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

    @@ -173,6 +186,7 @@

    Phase 1: Local Repository Health

  • git diff --check has no trailing-whitespace or conflict-marker errors. On Windows, LF-to-CRLF warnings may appear and are not release blockers by themselves.

    • Record the command output summary in the release notes or QA issue.

    +

    Required evidence destination for local readiness: admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md or an equivalent dated report in the same folder.

    Phase 2: Content Inventory Review

    Every content file must be reviewed before go-live. Use this checklist to assign coverage.

    Canonical Source Files Used by This Runbook

    -

    The following table lists the source files this runbook consolidates.

    +

    Table: Source files consolidated by this runbook

    @@ -143,6 +143,11 @@

    Canonical Source Files Used

    SUPPORT_HUB_OPERATIONS.md
    +

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

    Required Accounts, Access, and Tools

    Complete this section before Phase 1.

    -
  • Support hub is ready for student onboarding: -
  • While signed in as accesswatch, opening classroom.github.com shows the Community-Access-Classroom classroom organization.

    • If any precondition fails, stop and resolve before proceeding.

    @@ -703,8 +702,8 @@

    Step 1. Verify public regi

    Step 1.1 Verify support hub onboarding path

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

    Pass criteria:

    diff --git a/html/admin/qa-bundle/docs/00-pre-workshop-setup.html b/html/admin/qa-bundle/docs/00-pre-workshop-setup.html index 8801d59..c4e48e0 100644 --- a/html/admin/qa-bundle/docs/00-pre-workshop-setup.html +++ b/html/admin/qa-bundle/docs/00-pre-workshop-setup.html @@ -58,7 +58,9 @@
    -

    Pre-Workshop Setup - GIT Going with GitHub

    +

    Table: Screen reader options for workshop setup

    +

    Table: Accessibility improvements for screen reader users

    +

    Pre-Workshop Setup - GIT Going with GitHub

    Listen to Episode 1: Pre-Workshop Setup - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

    @@ -274,7 +276,7 @@

    Authenticati

    Workshop policy

    For this workshop, participants need a GitHub account with 2FA enabled. The browser-based sign-in described above handles all Git authentication automatically - no additional setup is required beyond having a working GitHub account.

    -

    If you run into any authentication issues before the workshop, contact the workshop organizers at the email or issue link in this guide so we can help.

    +

    If you run into any authentication issues before the workshop, open a support issue at Community-Access/support/issues or contact the workshop organizers directly.

    Learning Cards: Create Your GitHub Account

    Screen reader users diff --git a/html/admin/qa-bundle/index.html b/html/admin/qa-bundle/index.html index de6995c..6041f14 100644 --- a/html/admin/qa-bundle/index.html +++ b/html/admin/qa-bundle/index.html @@ -4,7 +4,7 @@ - QA Bundle (Grab-and-Go) - GIT Going with GitHub + GIT Going with GitHub @@ -28,7 +28,7 @@
    -

    QA Bundle (Grab-and-Go)

    -

    This folder is a convenience copy of the files needed to run end-to-end QA for the course (excluding podcast workflows).

    -

    What this bundle is for

    -

    Use this folder when you want quick local access to all key QA artifacts without navigating the full repo.

    -

    Start here

    -
      -
    1. admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md
      2. -
    2. GO-LIVE-QA-GUIDE.md
      3. -
    3. admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md
      4. -
    -

    Included content sets

    +

    GIT Going with GitHub

    +

    License: CC BY 4.0 | Site | Discussions

    +

    A Workshop by Community Access

    +
    +

    Welcome. This repository is your complete guide and companion for the two-day GIT Going with GitHub workshop. Every document here is written to be read with or without a screen reader. All steps are keyboard-accessible. You belong here.

    +

    About Community Access: Community Access is a community of blind and low vision technology professionals. Visit community-access.org to learn more.

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    DetailInformation
    Workshop sitecommunity-access.org/git-going-with-github
    RegistrationStudent opt-in and waitlist workflow
    DiscussionsJoin the conversation
    Support hubCommunity-Access/support
    Curriculum issuesFile an issue in this repository
    DatesMay 21, 2026 & May 22, 2026
    FacilitatorsJeff Bishop and Michael Babcock
    +
    +

    The Central Project: Accessibility Agents

    +

    This workshop is built around a real, live open source project: Accessibility Agents - 55 AI agents across 3 teams and 5 platforms for accessible, agentic repository management. It was built by your facilitator Jeff Bishop and is MIT-licensed.

    +

    You will fork it, understand it, contribute to it, and personalize it. The live workshop prepares you to make a real contribution, and the async continuation path gives you time to polish and submit it well.

    +

    Accessibility Agents does not replace what you learn on Day 1. It amplifies it. The agents only make sense when you already understand the skills they automate. That is why Day 1 comes first - and why every guide in this repository shows you the manual path before it shows you the agent path.

    +
    +

    What Is This Event?

    +

    During this two-day workshop, you will learn how to confidently navigate and contribute to open source projects on GitHub using:

    +
      +
    • A screen reader (NVDA on Windows, JAWS on Windows, or VoiceOver on macOS)
      • +
    • Keyboard-only navigation - no mouse required
      • +
    • GitHub Copilot (Day 2) - AI-assisted writing and coding in the browser and in VS Code
      • +
    +

    By the end of this event, you will have practiced real contribution workflows in a real repository. Some participants will ship during the live event; others will leave with a branch, a pull request path, and clear next steps to finish asynchronously.

    +

    Who Is This For?

    +

    This event is designed for:

    +
      +
    • People new to GitHub who use assistive technology
      • +
    • Developers who use screen readers and want to contribute to open source
      • +
    • Anyone who is curious about accessible development workflows
      • +
    • Sighted participants are welcome - all content is keyboard-navigable for everyone
      • +
    +

    You do not need to know how to code to participate and contribute meaningfully. Documentation improvements, issue filing, accessibility bug reports, and code reviews are all valuable contributions.

    +

    Two-Day Overview

    + + + + + + + + + + + + + + + + + + +
    DayFocusWhat You Will Do
    Day 1GitHub FoundationsSet up your environment, learn GitHub navigation with your screen reader, file your first issue, open your first pull request
    Day 2VS Code + Accessibility AgentsBridge from the browser to github.dev (VS Code in your browser - no install needed), then step into Visual Studio Code on the desktop, learn VS Code basics, use GitHub Copilot, activate the Accessibility Agents ecosystem (55 agents, 3 teams, 5 platforms), see agentic workflows in the cloud, and prepare a real upstream contribution path
    +

    The Journey Arc

    +

    This is not a two-day course with two separate syllabi. It is one arc.

    +
    Day 1 - Learn the skill in the browser
+  Navigate → Issue → Pull Request → Review → Merge
+
+     ↓  (bridge: press . on any GitHub repo - VS Code opens right in your browser)
+
+github.dev - VS Code on the web, no install needed
+  Same keyboard shortcuts · Same screen reader mode · Edit files · Open PRs
+  What it cannot do: no terminal, no Copilot agents, no local extensions
+
+     ↓  (you've earned the desktop - now it makes sense)
+
+Day 2 - Deepen with VS Code + Accessibility Agents
+  Learn VS Code basics → Copilot inline → Copilot Chat
+  @daily-briefing → @issue-tracker → @pr-review → @analytics → prepare upstream
    +

    Every skill you build on Day 1 maps directly to an Accessibility Agents command on Day 2. The agent is not a shortcut - it is a multiplier. You have to understand what it is doing to know when it is wrong.

    +

    By the end of the Day 2 core path, you will have:

      -
    • Registration deployment and QA docs and workflow files.
      • -
    • Classroom deployment and autograding setup docs.
      • -
    • Learning Room automation docs, workflows, and issue templates.
      • -
    • Facilitator scripts for template sync, seeding, conflict setup, and recovery.
      • -
    • Challenge definitions and student onboarding references.
      • -
    • Local unit-test readiness evidence.
      • +
    • A fork of accessibility-agents with your personalized preferences
      • +
    • A branch or pull request path for a real open source contribution
      • +
    • Clear next steps to get your contribution reviewed and merged
      • +
    • A working set of 55 AI agents across 3 teams that travel with your fork to any repository you apply them to
    -

    HTML copy of E2E runbook

    +

    How to Read These Docs

    +

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

    +

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

    +

    Post-Workshop Support

    +

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

    -

    Important notes

    +

    Use this repository for curriculum and platform changes only.

    +

    Your Challenges

    +

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

    +

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

    +

    The workflow:

    +
      +
    1. Open the challenge issue template for the current chapter
      2. +
    2. Follow the instructions in the issue and the corresponding chapter
      3. +
    3. Complete the challenge and post your evidence
      4. +
    4. Open a PR that references your issue with Closes #N
      5. +
    5. The validation bot checks your work
      6. +
    6. When it passes, merge and move to the next challenge
      7. +
    +

    Every chapter has an "If You Get Stuck" section. Every challenge has a reference solution. You do not need to memorize anything.

    +
    +

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

    +
    +

    Looking for a student-friendly table of contents? See the Course Guide - a single page with day-by-day chapter tables, grouped appendices, all 24 exercises at a glance, and where to get help.

    +
    +

    Chapters

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    #DocumentWhat It Covers
    StartGet Going with GitHubGitHub Classroom onboarding, Learning Room first steps, support, and tool choice
    00Pre-Workshop SetupEverything to install and configure before Day 1
    01Choose Your ToolsScreen reader options, tooling decisions, and workflow setup
    02Understanding GitHubHow GitHub is organized, page types, landmark structure, and screen reader orientation
    03Navigating RepositoriesStep-by-step repository navigation with your screen reader
    04The Learning RoomYour private practice repository, branching, committing, and PR workflow
    05Working with IssuesFiling, managing, and participating in issues
    06Working with Pull RequestsCreating, reviewing, and merging pull requests
    07Merge ConflictsUnderstanding, preventing, and resolving merge conflicts
    08Open Source CultureCommunity norms, contributing, giving feedback
    09Labels, Milestones, and ProjectsOrganizing and cross-referencing work
    10Notifications and Day 1 CloseManaging your inbox, merging your work, Day 1 recap
    11VS Code InterfaceVS Code accessibility, screen reader mode, keyboard navigation
    12VS Code AccessibilityAccessibility signals, Accessible View, Accessible Diff Viewer
    13How Git WorksCommits, branches, merges, and the mental model
    14Git in PracticeClone, branch, edit, commit, push using VS Code and terminal
    15Code ReviewPR extension, diffs, inline comments, review verdicts
    16GitHub CopilotInline suggestions, Copilot Chat, prompting, Accessible View
    17Issue TemplatesCreating and using GitHub issue templates
    18Fork and ContributeFork workflow, upstream sync, cross-repo contributions
    19Accessibility Agents55 agents across 3 teams, contributing to the ecosystem
    20Build Your Own AgentDesign an agent with responsibilities and guardrails (capstone)
    21Next StepsWhere to go after the workshop
    +

    Workshop Agendas - For facilitators only (not part of learner sequence)

    + + + + + + + + + + + + + + + +
    DocumentWhat It Covers
    DAY1_AGENDA.mdFull Day 1 schedule, objectives, and activities
    DAY2_AGENDA.mdFull Day 2 schedule, objectives, and activities
    +

    Appendices - Reference material; open any time during the workshop

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AppendixDocumentWhat It Covers
    AGitHub Concepts GlossaryEvery term, concept, and piece of jargon explained
    BScreen Reader Cheat SheetComplete NVDA, JAWS, and VoiceOver navigation commands - task-based and per-screen-reader - plus the full GitHub built-in keyboard shortcut system
    CAccessibility Standards ReferenceWCAG 2.2 success criteria, ARIA roles and patterns, and a quick-reference PR checklist
    DGit AuthenticationSSH keys, Personal Access Tokens, credential storage, and commit signing
    EGitHub Flavored MarkdownAlert blocks, collapsible sections, Mermaid diagrams, math, footnotes, heading anchors, and screen reader guidance
    FGitHub GistsCode snippets, sharing, embedding, and cloning
    GGitHub DiscussionsForum-style conversations, Q&A, polls, and accessibility navigation for discussion threads
    HReleases, Tags, and Repository InsightsVersioned releases, semver, reading release notes, pulse, contributors, traffic, and Insights metrics
    IGitHub Projects Deep DiveBoards, tables, roadmaps, custom fields, automations, iterations, cross-repo projects, and accessible navigation
    JGitHub Advanced SearchComplete query language reference for searching issues, PRs, code, commits, and repositories
    KBranch Protection and RulesetsRequired reviews, status checks, repository rulesets, and diagnosing why your PR cannot be merged
    LGitHub Security FeaturesDependabot alerts and updates, secret scanning, code scanning/CodeQL, private vulnerability reporting, and SBOM
    MVS Code Accessibility ReferenceComplete technical reference for all accessibility settings, audio cues, diff viewer, screen reader configurations, keyboard shortcuts
    NGitHub CodespacesCloud development environments - setup, accessibility configuration, and screen reader usage
    OGitHub MobileAccessibility guide for iOS and Android - VoiceOver, TalkBack, notifications, and PR reviews
    PPublishing with GitHub PagesDeploy a static site from your repository - branch setup, custom domains, CI workflows, and accessibility checks
    QGitHub Actions and WorkflowsDeep-dive reference - automation, status checks, CI/CD workflows, and the path to agentic cloud
    RGitHub Profile, Sponsors, and WikisProfile README, GitHub Sponsors, and GitHub Wikis
    SOrganizations, Templates, and Repository SettingsOrganizations, repository templates, visibility, archiving, and contributor-relevant settings
    TContributing to Open SourceA first-timer's guide: finding issues, scoping contributions, writing PRs, and building a contribution habit
    UResourcesEvery link, tool, and reference from this event
    VAccessibility Agents Reference55 agents, 3 teams, 5 platforms, slash commands, and workspace configuration
    WGitHub Copilot ReferenceCopilot features, chat participants, slash commands, MCP servers, and agentic ecosystem
    XGitHub Copilot AI ModelsModel comparison, strengths, plan availability, and selection guidance
    YAccessing and Downloading Workshop MaterialsGitHub Pages, GitHub.com, cloning, ZIP download, offline reading, folder guide
    ZGitHub Skills - Complete Course CatalogAll 36 GitHub Skills modules organized into six learning paths, with links, prerequisites, and integration guidance
    +
    +

    Each guide from Lesson 03 onward includes a "Day 2 Amplifier" callout that shows how Accessibility Agents extends that skill across three scopes: your VS Code editor → your repository (travels with every fork) → the cloud (GitHub Agentic Workflows running without VS Code). Learn the manual skill first (Chapter 14), then see how it's automated (Chapter 16).

    +
    +

    This Repository's Structure

    +
    +

    One repository, everything included. Clone or fork this repo and you have the complete workshop - all curriculum guides, Accessibility Agents agents and slash commands, YAML issue forms, PR template, and a practice contribution target in learning-room/. GitHub Skills modules cannot be bundled here (each participant activates their own copy on their own account), but links are in .github/ISSUE_TEMPLATE/config.yml.

    +
    +
    [repo root]/
+├── README.md                            -- You are here
+├── CONTRIBUTING.md                      -- How to contribute to this repo
+├── CODE_OF_CONDUCT.md                   -- Community standards
+├── admin/FACILITATOR_GUIDE.md           -- For workshop organizers only
+├── admin/DAY1_AGENDA.md                 -- Day 1 workshop schedule
+├── admin/DAY2_AGENDA.md                 -- Day 2 workshop schedule
+├── .github/
+│   ├── ISSUE_TEMPLATE/
+│   │   ├── config.yml                   -- Links to GitHub Skills; disables blank issues
+│   │   ├── challenge-*.yml              -- 16 core challenge templates
+│   │   ├── bonus-*.yml                  -- 5 bonus challenge templates
+│   │   ├── accessibility-bug.yml        -- Structured accessibility bug form
+│   │   └── feature-request.yml          -- Feature/improvement request form
+│   ├── PULL_REQUEST_TEMPLATE.md         -- PR checklist with accessibility section
+│   ├── workflows/                       -- CI/CD and autograding workflows
+│   ├── agents/                          -- 55 Accessibility Agents for Copilot Chat
+│   └── prompts/                         -- 54+ slash commands for Copilot Chat
+├── classroom/                           -- GitHub Classroom setup artifacts
+│   ├── README.md                        -- Workshop Deployment Guide (unified setup for new cohorts)
+│   ├── assignment-day1-you-belong-here.md
+│   ├── assignment-day2-you-can-build-this.md
+│   ├── autograding-day1.json
+│   ├── autograding-day2.json
+│   ├── roster-template.csv
+│   ├── grading-guide.md
+│   └── teardown-checklist.md
+├── learning-room/                       -- GitHub Classroom template copied into each student's private repo
+│   ├── README.md
+│   └── docs/
+│       ├── welcome.md                   -- Has TODO sections for you to complete
+│       ├── keyboard-shortcuts.md        -- Has intentional accessibility issues to fix
+│       └── setup-guide.md              -- Has a broken link to find and fix
+├── docs/                                -- Full workshop curriculum (22 chapters + appendices)
+│   ├── course-guide.md                  -- Student landing page
+│   ├── CHALLENGES.md                    -- Challenge Hub: all 21 challenges
+│   ├── 00-pre-workshop-setup.md through 21-next-steps.md
+│   ├── appendix-a-glossary.md through appendix-z-github-skills.md
+│   └── solutions/                       -- Reference solutions for every challenge
+├── podcasts/                            -- Audio companion episodes
+└── PODCASTS.md                          -- Audio player page
    +
    +

    Note: Appendices were renumbered during a February 2026 review. If you encounter external references to "Appendix D" or later letters, subtract one letter (e.g., the former Appendix D is now Appendix C).

    +
    +

    Quick Reference

    +

    These standalone documents provide additional guidance and resources:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    DocumentDescription
    FAQFrequently asked questions about the workshop
    Quick ReferenceCondensed cheat sheet for common tasks
    TroubleshootingSolutions for common setup and workflow issues
    Progress TrackerTrack your learning progress through the workshop
    Accessibility TestingAccessibility testing procedures and standards
    SecuritySecurity policy and vulnerability reporting
    GitHub ProposalOriginal event proposal and curriculum overview (internal reference)
    +

    Screen Reader Users: Start Here

    +

    Before doing anything else, please read 00 - Pre-Workshop Setup. It will walk you through:

      -
    • This bundle is a convenience snapshot, not the canonical source of truth.
      • -
    • Canonical files remain in the repository root paths.
      • -
    • Rebuild this bundle after significant workflow/challenge/runbook updates.
      • +
    • Configuring your screen reader for GitHub
      • +
    • Verifying GitHub's modern interface is working (may already be active - instructions include how to check and enable if needed)
      • +
    • Turning off settings that make screen reader navigation harder
      • +
    • Verifying everything works before Day 1 begins
    -

    Local vs GitHub deployment for unit tests

    +

    The Goal of This Event

    +

    Open source software is built by people. Accessibility bugs in open source affect millions of people who use assistive technology every day. By learning to contribute - even something as small as filing a clear, detailed accessibility issue - you become part of fixing that. That matters.

    +

    You don't have to write a single line of code to make open source more accessible.

    +

    And by the end of Day 2, you will not just be a learner. You will be a product maker - someone who has shipped something real to a project that other people use.

    +

    Questions Before the Event?

      -
    • Unit tests run locally with npm run test:automation.
      • -
    • GitHub deployment is not required to execute local unit tests.
      • -
    • Hosted GitHub/Classroom gates are still required for final release readiness.
      • +
    • Discussion Forum: Join the conversation - ask questions, connect with fellow participants, share ideas
      • +
    • File an issue in this repository if something in these docs is unclear
      • +
    • Community: GitHub Accessibility Discussions
    +

    License

    +

    All workshop documentation is licensed under CC BY 4.0 - you are free to share and adapt with attribution.

    +

    Last reviewed: May 2026 +A Community Access initiative.