Skip to content

Commit 924e04d

Browse files
accesswatchGitHub Workshop Botclaude
authored
docs: resolve open issues 221/229/231 and retire stale Classroom seeding references (#241)
- Ch11 (#231): replace the Five Major Regions ASCII diagram with a real markdown table; screen readers were announcing the box-drawing pipes as broken tables. - Ch6 (#229): add a Steps Using the Web Editor subheading plus screen reader and sighted learning cards for the first web-editor challenge: file navigation, the E and period shortcuts, finding the Commit changes button, and a github.dev-is-VS-Code note linking Chapters 11 and 12. - Appendix Z (#221): add GitHub's learning portal (learn.github.com) to Additional Resources with an accessibility note. - HUMAN_TEST_MATRIX, classroom README, GO-LIVE guide, E2E QA runbook: status notes explaining that scripts/classroom/ was removed and that the Student Progression Bot now seeds peer simulation artifacts automatically; seeding steps rewritten as workflow dispatches. - build-html.js: exclude gold.md (private maintainer log) from the public site; validate-authoritative-sources.js: exclude it from content checks; .gitignore it so it never lands in the public repo. - html/ regenerated. Closes #221, closes #229, closes #231. Co-authored-by: GitHub Workshop Bot <workshop@example.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 parent 801e5c6 commit 924e04d

19 files changed

Lines changed: 204 additions & 122 deletions

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,3 +196,6 @@ learning-room-e2e-*.json
196196
# Scratch artifacts - never commit
197197
tmp-*
198198
learning-room-e2e-*.json
199+
200+
# Private maintainer log (contains learner names; never publish)
201+
gold.md

‎GO-LIVE-QA-GUIDE.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Git Going with GitHub Go-Live QA Guide
22

3+
> **Status note (2026-07):** GitHub Classroom and the `scripts/classroom/` PowerShell tooling were removed; provisioning is now the hybrid pipeline in `.github/scripts/provisioning/`, and peer simulation seeding happens automatically via the Student Progression Bot in each learning room. Interpret `scripts/classroom/*.ps1` steps below as the Student Progression Bot workflow dispatch (inputs `start_challenge`, `assignee`).
4+
35
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.
46

57
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.
@@ -241,8 +243,8 @@ Run these checks in disposable student repositories created by GitHub Classroom.
241243

242244
### Seeding Scripts
243245

244-
- [ ] `Seed-LearningRoomChallenge.ps1` creates the requested starting challenge.
245-
- [ ] `Seed-PeerSimulation.ps1` creates the peer simulation issues, branch, file, and PR.
246+
- [ ] Student Progression Bot workflow dispatch creates the requested starting challenge.
247+
- [ ] The progression bot seeds the peer simulation issues, branch, file, and PR automatically alongside the challenge issue.
246248
- [ ] `Start-MergeConflictChallenge.ps1` creates a real conflict against the student branch.
247249
- [ ] `Test-LearningRoomTemplate.ps1` reports the template readiness state.
248250
- [ ] Script failures show a clear error message and do not partially hide the problem.

‎admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Learning Room End-to-End QA Runbook (Registration to Student Completion)
22

3+
> **Status note (2026-07):** GitHub Classroom and the `scripts/classroom/` PowerShell tooling were removed. Provisioning is the hybrid pipeline in `.github/scripts/provisioning/` (workflow `provision-learning-rooms.yml`), and peer simulation artifacts are seeded automatically by the Student Progression Bot in each learning room. Interpret `scripts/classroom/*.ps1` steps below as the Student Progression Bot workflow dispatch (inputs `start_challenge`, `assignee`); `Seed-PeerSimulation.ps1` steps need no action because the bot seeds and self-repairs those artifacts.
4+
35
Use this runbook when you want one operational checklist that covers the full workflow:
46

57
1. Registration intake and validation.

‎classroom/HUMAN_TEST_MATRIX.md‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -17,23 +17,24 @@ Full collaboration test:
1717

1818
## Required Facilitator Setup
1919

20-
After the student repository exists, run:
20+
The old `scripts/classroom/` PowerShell seeding scripts were removed with GitHub Classroom. Seeding now runs through the Student Progression Bot workflow inside the student repository.
2121

22-
```powershell
23-
scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access/learning-room-smoke-a -Challenge 1 -Assignee test-student-a
24-
scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access/learning-room-smoke-a -StudentUsername test-student-a
25-
```
22+
After the student repository exists, open the repo's Actions tab, choose **Student Progression Bot**, select **Run workflow**, and set:
2623

27-
For Day 2-only testing, seed Challenge 10 instead:
24+
- `start_challenge`: `1`
25+
- `assignee`: `test-student-a`
2826

29-
```powershell
30-
scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access/learning-room-smoke-a -Challenge 10 -Assignee test-student-a
31-
scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access/learning-room-smoke-a -StudentUsername test-student-a
27+
For Day 2-only testing, set `start_challenge` to `10` instead.
28+
29+
Equivalent CLI:
30+
31+
```bash
32+
gh workflow run student-progression.yml -R Community-Access/learning-room-smoke-a -f start_challenge=1 -f assignee=test-student-a
3233
```
3334

3435
## What The Peer Simulation Creates
3536

36-
`Seed-PeerSimulation.ps1` creates realistic collaboration artifacts inside the student's private repo:
37+
The progression bot seeds realistic collaboration artifacts inside the student's private repo automatically whenever it creates a challenge issue (and repairs them if any are missing):
3738

3839
- `Peer Simulation: Welcome Link Needs Context` issue
3940
- `Peer Simulation: Review Request for Contribution Guidance` issue

‎classroom/README.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Workshop Deployment Guide
22

3+
> **Status note (2026-07):** GitHub Classroom and the `scripts/classroom/` PowerShell tooling described in this guide have been removed. Current cohorts use hybrid provisioning (`.github/scripts/provisioning/`, triggered by the `provision-learning-rooms.yml` workflow), and peer simulation artifacts are seeded automatically by the Student Progression Bot inside each learning room. Where this guide references a `scripts/classroom/*.ps1` script, use the Student Progression Bot's **Run workflow** dispatch (inputs `start_challenge` and `assignee`) instead. This guide is retained for the parts that are still accurate (challenge flow, bots, grading).
4+
35
> 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.
46
57
> Before sharing invite links with students, complete the [Go-Live QA Guide](../GO-LIVE-QA-GUIDE.md). It is the final release gate for content, workflows, Classroom setup, podcasts, accessibility, and human test coverage.
@@ -265,11 +267,7 @@ For Day 2, use `-Challenge 10`.
265267

266268
### Seeding peer simulation
267269

268-
Because each GitHub Classroom repository is private, students cannot automatically see a classmate's issues or pull requests. To preserve realistic collaboration without exposing private student repos, seed peer-simulation artifacts into each student's repository:
269-
270-
```powershell
271-
scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom/learning-room-studentname -StudentUsername studentname
272-
```
270+
Because each learning room repository is private, students cannot automatically see a classmate's issues or pull requests. To preserve realistic collaboration without exposing private student repos, peer-simulation artifacts are seeded into each student's repository automatically: the Student Progression Bot creates them the first time it opens a challenge issue, and repairs them on later runs if any are missing. No facilitator action is required.
273271

274272
This creates two peer-simulation issues and one peer-simulation pull request. Challenges that ask students to comment, react, review, compare, or practice peer collaboration can use those seeded artifacts. If facilitators intentionally provision real buddy access, students may use real buddy repositories instead.
275273

‎docs/06-working-with-pull-requests.md‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,30 @@ The following table summarizes the practice files in the learning-room, what eac
7575
| `docs/keyboard-shortcuts.md` | Screen reader shortcut reference tables | Intentional errors in shortcut references |
7676
| `docs/setup-guide.md` | Getting-started instructions | Broken links and incomplete steps |
7777

78-
**Steps using the web editor:**
78+
#### Steps Using the Web Editor
79+
80+
This is your first challenge that uses GitHub's web editor, so take a moment with the learning cards below before you start.
81+
82+
**About the web editor:** GitHub offers two browser-based editors. The **file editor** (the pencil icon on any file) edits one file at a time and is what these steps use. The full **github.dev** editor (press `.` (period) from the repository's Code page) is a browser-based version of Visual Studio Code with the same commands, Command Palette, and screen reader mode as the desktop app. Either works for this challenge. If you use github.dev, see [Chapter 11: VS Code Interface](11-vscode-interface.md) and the [VS Code Accessibility Deep Dive](12-vscode-accessibility.md) for full navigation guidance.
83+
84+
<details>
85+
<summary>Screen reader users (NVDA / JAWS / VoiceOver)</summary>
86+
87+
- **Find your file:** On the repository's Code page, the file list is a table. Use your table reading commands to reach the file named in your issue, then press `Enter` to open it. Or press `T` to open "Go to file" and type the file name.
88+
- **Open the editor:** With the file displayed, press `E` to open it directly in the file editor, or press `B` (NVDA/JAWS buttons quick key) to find the "Edit this file" button and press `Enter`. VoiceOver: use the Buttons rotor (`VO+U`) to find "Edit this file" and press `VO+Space`.
89+
- **Alternative - github.dev:** With the file displayed (or from the Code page), press `.` (period) to open the whole repository in github.dev, a web version of VS Code. Enable screen reader mode when prompted.
90+
- **Find the Commit changes button:** After editing, press `B` (or use the Buttons rotor) to find the button named "Commit changes..." - it sits above the editor. Activating it opens a dialog where the branch name field and "Propose changes" button live; the dialog receives focus automatically.
91+
92+
</details>
93+
94+
<details>
95+
<summary>Sighted users</summary>
96+
97+
- Navigate to the file via the file list or the "Go to file" search.
98+
- Select the **pencil icon** (Edit this file) at the top right of the file view.
99+
- After editing, select the green **Commit changes** button above the editor to open the commit dialog.
100+
101+
</details>
79102

80103
1. In your Learning Room repository, navigate to the file specified in your issue. Use the file tree or the "Go to file" button (`T` keyboard shortcut).
81104
2. Open the file and activate the **pencil icon** (Edit this file) button.

‎docs/11-vscode-interface.md‎

Lines changed: 10 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -449,27 +449,16 @@ Before diving into individual features, here is how VS Code is organized. Every
449449

450450
### The Five Major Regions
451451

452-
```text
453-
+----------------------------------------------------------+
454-
| Menu Bar (File, Edit, View, Go, Run, Terminal, Help) |
455-
+------+---------------------------------------------------+
456-
| | |
457-
| A | Editor Area |
458-
| c | (your files open here) |
459-
| t | |
460-
| i | |
461-
| v | |
462-
| i +---------------------------------------------------+
463-
| t | |
464-
| y | Panel (Terminal, Problems, Output, Debug Console) |
465-
| | |
466-
| B +---------------------------------------------------+
467-
| a | Status Bar (line, column, language, Git branch, |
468-
| r | Copilot status, encoding, notifications) |
469-
+------+---------------------------------------------------+
470-
```
471-
472-
**Text description of the layout above:** VS Code has five major regions arranged in a grid. The **Menu Bar** spans the full width across the top. Below it, the **Activity Bar** runs vertically along the left edge (it contains icons for Explorer, Source Control, Search, Extensions, and more). The **Sidebar** appears to the right of the Activity Bar and shows content for the selected activity (file tree, search results, etc.). The **Editor Area** fills the large central region where your files open. Below the Editor Area, the **Panel** stretches across the bottom and contains the Terminal, Problems, Output, and Debug Console tabs. Finally, the **Status Bar** runs along the very bottom showing line number, column, language mode, Git branch, Copilot status, encoding, and notifications.
452+
| Region | Where it sits | What it contains |
453+
| --- | --- | --- |
454+
| Menu Bar | Full width across the top | File, Edit, View, Go, Run, Terminal, Help menus |
455+
| Activity Bar | Vertical strip along the left edge | Icons for Explorer, Source Control, Search, Extensions, Accounts |
456+
| Sidebar | Right of the Activity Bar | Content for the selected activity (file tree, search results, etc.) |
457+
| Editor Area | Large central region | Your open files |
458+
| Panel | Below the Editor Area | Terminal, Problems, Output, Debug Console tabs |
459+
| Status Bar | Very bottom, full width | Line, column, language, Git branch, Copilot status, encoding, notifications |
460+
461+
**How the regions fit together:** VS Code has five major regions arranged in a grid. The **Menu Bar** spans the full width across the top. Below it, the **Activity Bar** runs vertically along the left edge (it contains icons for Explorer, Source Control, Search, Extensions, and more). The **Sidebar** appears to the right of the Activity Bar and shows content for the selected activity (file tree, search results, etc.). The **Editor Area** fills the large central region where your files open. Below the Editor Area, the **Panel** stretches across the bottom and contains the Terminal, Problems, Output, and Debug Console tabs. Finally, the **Status Bar** runs along the very bottom showing line number, column, language mode, Git branch, Copilot status, encoding, and notifications.
473462

474463
### Navigating Between Regions
475464

‎docs/appendix-z-github-skills.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -333,6 +333,7 @@ Path 6: Cloud and Migration
333333
- [GitHub Skills homepage](https://skills.github.com/) - browse all courses with descriptions
334334
- [GitHub Skills organization](https://github.com/skills) - view all course repositories directly
335335
- [GitHub Skills Discussions](https://github.com/orgs/skills/discussions) - ask questions and share feedback with the GitHub Skills community
336+
- [GitHub's learning portal](https://learn.github.com/) - GitHub's broader learning hub, including certification prep and links to Microsoft Learn modules. Accessibility varies by module, but it is a rich way to explore concepts hands-on and Microsoft Learn content is often quite accessible.
336337

337338
---
338339

‎html/GO-LIVE-QA-GUIDE.html‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -235,6 +235,9 @@ <h2 class="onpage-title">On This Page</h2>
235235
</ul>
236236
</nav>
237237
<div id="course-content"><h1 id="git-going-with-github-go-live-qa-guide">Git Going with GitHub Go-Live QA Guide</h1>
238+
<blockquote>
239+
<p><strong>Status note (2026-07):</strong> GitHub Classroom and the <code>scripts/classroom/</code> PowerShell tooling were removed; provisioning is now the hybrid pipeline in <code>.github/scripts/provisioning/</code>, and peer simulation seeding happens automatically via the Student Progression Bot in each learning room. Interpret <code>scripts/classroom/*.ps1</code> steps below as the Student Progression Bot workflow dispatch (inputs <code>start_challenge</code>, <code>assignee</code>).</p>
240+
</blockquote>
238241
<p>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.</p>
239242
<p>For end-to-end execution details, use <a href="admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html">admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md</a> as the operator procedure. This guide is the release gate summary; the runbook is the required execution playbook.</p>
240243
<p>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.</p>
@@ -489,8 +492,8 @@ <h3 id="autograders">Autograders</h3>
489492
</ul>
490493
<h3 id="seeding-scripts">Seeding Scripts</h3>
491494
<ul>
492-
<li><input aria-label="" disabled="" type="checkbox"> <code>Seed-LearningRoomChallenge.ps1</code> creates the requested starting challenge.</li>
493-
<li><input aria-label="" disabled="" type="checkbox"> <code>Seed-PeerSimulation.ps1</code> creates the peer simulation issues, branch, file, and PR.</li>
495+
<li><input aria-label="Student Progression Bot workflow dispatch creates the requested starting challenge." disabled="" type="checkbox"> Student Progression Bot workflow dispatch creates the requested starting challenge.</li>
496+
<li><input aria-label="The progression bot seeds the peer simulation issues, branch, file, and PR automatically alongside the challenge issue." disabled="" type="checkbox"> The progression bot seeds the peer simulation issues, branch, file, and PR automatically alongside the challenge issue.</li>
494497
<li><input aria-label="" disabled="" type="checkbox"> <code>Start-MergeConflictChallenge.ps1</code> creates a real conflict against the student branch.</li>
495498
<li><input aria-label="" disabled="" type="checkbox"> <code>Test-LearningRoomTemplate.ps1</code> reports the template readiness state.</li>
496499
<li><input aria-label="Script failures show a clear error message and do not partially hide the problem." disabled="" type="checkbox"> Script failures show a clear error message and do not partially hide the problem.</li>

‎html/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,9 @@ <h2 class="onpage-title">On This Page</h2>
269269
</ul>
270270
</nav>
271271
<div id="course-content"><h1 id="learning-room-end-to-end-qa-runbook-registration-to-student-completion">Learning Room End-to-End QA Runbook (Registration to Student Completion)</h1>
272+
<blockquote>
273+
<p><strong>Status note (2026-07):</strong> GitHub Classroom and the <code>scripts/classroom/</code> PowerShell tooling were removed. Provisioning is the hybrid pipeline in <code>.github/scripts/provisioning/</code> (workflow <code>provision-learning-rooms.yml</code>), and peer simulation artifacts are seeded automatically by the Student Progression Bot in each learning room. Interpret <code>scripts/classroom/*.ps1</code> steps below as the Student Progression Bot workflow dispatch (inputs <code>start_challenge</code>, <code>assignee</code>); <code>Seed-PeerSimulation.ps1</code> steps need no action because the bot seeds and self-repairs those artifacts.</p>
274+
</blockquote>
272275
<p>Use this runbook when you want one operational checklist that covers the full workflow:</p>
273276
<ol>
274277
<li>Registration intake and validation.</li>

0 commit comments

Comments
 (0)