Git Going with GitHub Go-Live QA Guide

Use this guide before a cohort is opened to learners. It is the release gate for curriculum content, GitHub Classroom deployment, Learning Room automation, accessibility, and human test coverage. Podcast and LLM-generation QA is tracked here as non-blocking unless a podcast release is explicitly in scope.

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

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

Important Note: Email and Notification Handling

This curriculum does NOT depend on email notifications.

  • Account verification emails (GitHub signup, email confirmation) are required by GitHub and are outside our control
  • Notification emails (activity updates, mentions, assignments) are completely optional
  • All challenges complete successfully using only GitHub's web notification inbox at github.com/notifications
  • Students can disable email notifications in their GitHub settings after account setup—this will NOT break the workshop
  • Chapter 10 (Notifications) focuses on managing the web notification inbox, not email delivery

If a student's email delivery is problematic, delayed, or filtered by their ISP, they can still complete all challenges and exercises without any impact. Instructors should inform students that they can check github.com/notifications anytime instead of waiting for emails.

Release Decision

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

  • Automated tests pass locally.
  • HTML documentation builds from the current Markdown sources.
  • Learning Room source has been synced to Community-Access/learning-room-template and merged to main (or validated as no-change).
  • Template smoke validation from Community-Access/learning-room-template succeeded before assignment publishing.
  • Template freshness proof confirms smoke repo content matches latest merged template sync changes.
  • Git diff whitespace check has no actual whitespace or conflict-marker errors.
  • Registration deployment gate completed (issue form template, workflow enablement, required labels, and optional classroom automation settings).
  • Registration comment flow is assignment-link based (no org invite dependency).
  • Registration form smoke test passed on 2026-05-14 (submission accepted, redacted, labeled, and support routing confirmed).
  • Support Hub is provisioned and publicly accessible at Community-Access/support.
  • Registration confirmation and help pathways route support requests to Support Hub issues/discussions.
  • Registration issue form template and labels are configured (workshop-registration.yml, registration, duplicate, waitlist).
  • Smoke repo confirms all required workflow files are present (PR validation, content validation, progression, skills progression, and all autograder workflows: autograder-issue-filed.yml, autograder-branch-commit.yml, autograder-pr-link.yml, autograder-conflicts.yml, autograder-local-commit.yml, autograder-template.yml, autograder-capstone.yml, autograder-watchdog.yml).
  • Day 1 Classroom assignment has been created from the current Learning Room template.
  • Day 2 Classroom assignment has been created from the current Learning Room template.
  • A test student account accepted the Day 1 invite and received a private repository.
  • A test student account accepted the Day 2 invite and received a private repository.
  • A test student can reply ack, then close the enrollment issue as Challenge 0 and retain expected workflow state.
  • A test student can reply day1-complete and receive Day 2 release comment.
  • Challenge 1 can be seeded and completed.
  • Challenge 10 can be seeded and completed.
  • Gandalf posts PR feedback on a test pull request.
  • Student Progression Bot creates the next challenge when a challenge issue is closed.
  • Autograder workflows run inside the student repo and post pass/fail comments on the relevant issues and PRs. (Classroom UI test cases are intentionally not configured -- see admin/classroom/autograding-setup.md.)
  • Peer simulation artifacts can be seeded and used for review practice.
  • Human testers completed the Day 1, Day 2, bonus, accessibility, and content-review passes below.
  • Challenge tracking log includes explicit status and evidence for Challenges 1-16 and Bonus A-E.
  • Challenge reliability matrix includes happy path, failure path, and recovery evidence for each challenge family.
  • Runbook Phase 8 required checklist is complete in admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md.
  • Student recovery Level 2 restore test is completed and evidenced with branch and PR links.
  • All in-scope automation workflows and facilitator scripts were validated with expected behavior and evidence.
  • Local non-podcast readiness evidence is recorded in admin/qa-readiness.
  • If podcast/LLM generation is part of this release, podcast evidence is recorded; otherwise mark Phase 7 as non-blocking by release-owner decision.
  • All blocking findings have a fix, owner, or written release exception.

No-go conditions:

  • Any Blocker finding remains open.
  • Any required runbook Phase 8 gate is incomplete without explicit release-owner exception.
  • Student progression, PR validation, or required autograder behavior is not reproducible in a test student repository.
  • Template freshness proof is missing or shows drift from the latest merged template sync.
  • Required QA evidence links are missing for release-signoff claims.
  • Support channel links point to deprecated destinations and not to support.

Source Of Truth

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

Area Source document
Classroom deployment classroom/README.md
Classroom copy-paste setup pack admin/classroom/README.md
End-to-end operator runbook (registration to completion, podcast excluded) admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md
Human challenge walkthrough classroom/HUMAN_TEST_MATRIX.md
Facilitator operations admin/FACILITATOR_OPERATIONS.md
Facilitator guide admin/FACILITATOR_GUIDE.md
Support hub operations admin/SUPPORT_HUB_OPERATIONS.md
Student challenge hub docs/CHALLENGES.md
Podcast pipeline podcasts/README.md
Podcast regeneration runbook podcasts/REGENERATION.md
Post-workshop cleanup classroom/teardown-checklist.md

Roles

  • Release owner: owns the final go or no-go decision.
  • Classroom tester: creates assignments, accepts invites with a test student account, and validates repository creation.
  • Automation tester: checks workflows, seeding scripts, Aria feedback, progression, and autograding.
  • Accessibility tester: tests with NVDA, JAWS, VoiceOver, keyboard-only navigation, zoom, 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.

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.

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.
  • Leave the Day 1 assignment's autograding tests area empty. Confirm autograder workflows are present in the template repo instead (see admin/classroom/autograding-setup.md).
  • 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.
  • Leave the Day 2 assignment's autograding tests area empty. Confirm autograder workflows are present in the template repo instead (see admin/classroom/autograding-setup.md).
  • 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.

Gandalf 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 @gandalf-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 (Non-blocking for Learning Room go-live)

Use this section when podcast or LLM regeneration is in scope. For Learning Room go-live quality gating, this phase is advisory and does not block release unless release owner marks it in-scope.

  • LLM durable execution report exists for the current generation pass at podcasts/llm-podcast-generator-review/generated/execution/reports/.
  • If OpenRouter was used, durable sync fallback behavior and completion status are documented in the run evidence.
  • Scripts/transcripts publication summary is recorded with selected, published, and failed counts.
  • 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 Gandalf 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.

## 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 Gandalf, 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.

Authoritative Sources

Use these official references when you need the current source of truth for facts in this chapter.

Section-Level Source Map

Use this map to verify facts for each major section in this file.