From 4d017d6e7289319787f9305de73d65217cf8439e Mon Sep 17 00:00:00 2001 From: GitHub Workshop Bot Date: Tue, 12 May 2026 12:23:02 -0700 Subject: [PATCH 1/4] docs: migrate Day 1 and Day 2 autograding to workflows - Delete legacy classroom/autograding-day1.json and autograding-day2.json (workflows in learning-room/.github/workflows/autograder-*.yml are now the only source of truth for what each automated check verifies) - Update all facilitator docs (admin/classroom/, classroom/, GO-LIVE, runbook) to instruct leaving the GitHub Classroom autograding tests area empty for both Day 1 and Day 2 assignments - Document autograder-watchdog.yml behavior accurately in admin/classroom/autograding-setup.md (workflow_run-triggered fallback that only fires when a sibling autograder reports conclusion=failure and no challenge result comment was posted) - Extend scripts/classroom/Test-LearningRoomTemplate.ps1 to assert all twelve required workflow files exist in the smoke-test repo (catches half-finished template syncs) - Sync admin/qa-bundle/ copies from canonical sources so the QA pack matches the new flow --- GO-LIVE-QA-GUIDE.md | 11 +- README.md | 2 - admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md | 97 +++----- admin/classroom/README.md | 18 +- admin/classroom/autograding-setup.md | 223 +++--------------- admin/classroom/live-facilitation-flow.md | 35 +-- admin/qa-bundle/GO-LIVE-QA-GUIDE.md | 11 +- admin/qa-bundle/README.md | 2 - .../admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md | 97 +++----- admin/qa-bundle/admin/classroom/README.md | 18 +- .../admin/classroom/autograding-setup.md | 223 +++--------------- .../admin/classroom/live-facilitation-flow.md | 35 +-- admin/qa-bundle/classroom/README.md | 18 +- .../assignment-day1-you-belong-here.md | 8 +- .../assignment-day2-you-can-build-this.md | 8 +- admin/qa-bundle/classroom/grading-guide.md | 6 +- .../classroom/Test-LearningRoomTemplate.ps1 | 18 +- classroom/README.md | 18 +- classroom/assignment-day1-you-belong-here.md | 8 +- .../assignment-day2-you-can-build-this.md | 8 +- classroom/autograding-day1.json | 42 ---- classroom/autograding-day2.json | 62 ----- classroom/grading-guide.md | 6 +- .../classroom/Test-LearningRoomTemplate.ps1 | 18 +- 24 files changed, 270 insertions(+), 722 deletions(-) delete mode 100644 classroom/autograding-day1.json delete mode 100644 classroom/autograding-day2.json diff --git a/GO-LIVE-QA-GUIDE.md b/GO-LIVE-QA-GUIDE.md index f74079a..8d9f8e3 100644 --- a/GO-LIVE-QA-GUIDE.md +++ b/GO-LIVE-QA-GUIDE.md @@ -16,22 +16,25 @@ Do not mark a cohort ready until all required items in this section are complete - [ ] RSS feed validation passes for the current audio state. - [ ] Git diff whitespace check has no actual whitespace or conflict-marker errors. - [ ] Registration deployment gate completed (issue form template, workflow enablement, required labels, and optional classroom automation settings). +- [ ] Registration comment flow is assignment-link based (no org invite dependency). - [ ] Support Hub is provisioned and publicly accessible at `Community-Access/support`. - [ ] Registration confirmation and help pathways route support requests to Support Hub issues/discussions. - [ ] Registration issue form template and labels are configured (`workshop-registration.yml`, `registration`, `duplicate`, `waitlist`). - [ ] Learning Room source has been synced to `Community-Access/learning-room-template` and merged to `main` (or validated as no-change). - [ ] Template smoke validation from `Community-Access/learning-room-template` succeeded before assignment publishing. - [ ] Template freshness proof confirms smoke repo content matches latest merged template sync changes. -- [ ] Smoke repo confirms all required workflow files are present (PR validation, content validation, progression, skills progression, and all autograders). +- [ ] 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` in enrollment issue 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. - [ ] Aria posts PR feedback on a test pull request. - [ ] Student Progression Bot creates the next challenge when a challenge issue is closed. -- [ ] Autograding runs and reports results in GitHub Classroom. +- [ ] 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](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. @@ -155,7 +158,7 @@ Use a real GitHub Classroom with disposable test accounts. Do not use a facilita - [ ] Create the Day 1 assignment using [classroom/assignment-day1-you-belong-here.md](classroom/assignment-day1-you-belong-here.md). - [ ] Use private individual repositories. - [ ] Enable feedback pull requests. -- [ ] Add every Day 1 autograding test from [classroom/autograding-day1.json](classroom/autograding-day1.json). +- [ ] 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](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. @@ -174,7 +177,7 @@ scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Cl - [ ] Create the Day 2 assignment using [classroom/assignment-day2-you-can-build-this.md](classroom/assignment-day2-you-can-build-this.md). - [ ] Use private individual repositories. - [ ] Enable feedback pull requests. -- [ ] Add every Day 2 autograding test from [classroom/autograding-day2.json](classroom/autograding-day2.json). +- [ ] 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](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. diff --git a/README.md b/README.md index ff81689..d8a3fab 100644 --- a/README.md +++ b/README.md @@ -223,8 +223,6 @@ Every chapter has an "If You Get Stuck" section. Every challenge has a [referenc │ ├── 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 diff --git a/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md b/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md index fe7e5bc..d87241a 100644 --- a/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md +++ b/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md @@ -85,8 +85,7 @@ Complete all items below before any cohort launch actions. - [x] `GITHUB_TOKEN` default workflow permissions include write where required - [x] `Allow GitHub Actions to create and approve pull requests` enabled - [ ] Registration automation settings are correct when using registration-to-classroom handoff: - - [ ] Secret `CLASSROOM_ORG_ADMIN_TOKEN` is set in `Community-Access/git-going-with-github` - - [ ] Variables `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL` are set in `Community-Access/git-going-with-github` + - [ ] Variables `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` are set in `Community-Access/git-going-with-github` - [x] Registration entry configuration exists and is valid: - [x] Issue form template `workshop-registration.yml` exists - [x] Required labels exist: `registration`, `duplicate`, `waitlist` @@ -142,14 +141,14 @@ You must be signed in to GitHub as `accesswatch` for the following steps. - **Grant students admin access**: No - **Enable feedback pull requests**: Yes - Paste the Day 1 assignment description from [classroom/assignment-day1-you-belong-here.md](../classroom/assignment-day1-you-belong-here.md) - - Add autograding from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) -- Day 1 requires exactly 4 tests totaling 50 points + - **Skip the autograding tests area.** Autograded checks run as GitHub Actions workflows in the template repo (see [admin/classroom/autograding-setup.md](classroom/autograding-setup.md)). Leave the Classroom test cases section empty. - Select **Create assignment** 5. After saving, the assignment page shows an invite link at the top labeled something like **Invite link**. It will be in the format `https://classroom.github.com/a/`. Copy this full URL and paste it somewhere safe (for example, a scratch notepad). This is your `CLASSROOM_DAY1_ASSIGNMENT_URL`. 6. Repeat for the Day 2 assignment: - **Title**: `You Can Build This` - Same base settings as Day 1 - Paste description from [classroom/assignment-day2-you-can-build-this.md](../classroom/assignment-day2-you-can-build-this.md) - - Add Day 2 autograding: exactly 6 tests totaling 75 points + - **Skip the autograding tests area** for the same reason as Day 1. - Copy the resulting invite URL. This is your `CLASSROOM_DAY2_ASSIGNMENT_URL`. 7. Keep both URLs available. You will paste them into repository variables in section B step 4. @@ -157,62 +156,33 @@ Why this matters: - The repository variables `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` cannot be filled in until the assignments exist and their invite URLs are known. The short code in the URL is unique to each assignment and is not predictable in advance. -#### B. Configure registration automation key and variables +#### B. Configure registration automation variables Repository target: `Community-Access/git-going-with-github` You must be signed in as `accesswatch` for all steps in this section. -**Step B.1 -- Generate the personal access token (PAT)** - -The `CLASSROOM_ORG_ADMIN_TOKEN` secret must be a GitHub personal access token generated by `accesswatch` (or another Owner-level account for `Community-Access-Classroom`). This token is what allows the registration workflow to invite students to the `Community-Access-Classroom` organization automatically. - -1. While signed in as `accesswatch`, go to [github.com/settings/tokens](https://github.com/settings/tokens). -2. Select **Generate new token**, then select **Generate new token (classic)**. - - Do not use fine-grained tokens for this purpose. The `admin:org` scope is only available on classic tokens. -3. In the **Note** field enter a descriptive name such as `Community-Access registration automation`. -4. In the **Expiration** field, set a date that covers your cohort timeline plus a buffer (for example, 90 days). -5. Under **Select scopes**, check `admin:org`. This is the only scope required. It gives the token permission to list and create organization invitations for `Community-Access-Classroom`. -6. Scroll to the bottom and select **Generate token**. -7. GitHub will display the token exactly once immediately after generation. It begins with `ghp_`. Copy it now and paste it somewhere safe (a local scratch notepad, not a repository file). You will not be able to view it again. -8. Do not close the token page until you have completed section B.2 and confirmed the secret was saved. - -**Step B.2 -- Add the token as a repository secret** - -1. Go to [github.com/Community-Access/git-going-with-github/settings/secrets/actions](https://github.com/Community-Access/git-going-with-github/settings/secrets/actions). -2. Select **New repository secret**. -3. In the **Name** field, enter exactly: `CLASSROOM_ORG_ADMIN_TOKEN` - - Capitalization and underscores must match exactly. -4. In the **Secret** field, paste the token you copied in step B.1. -5. Select **Add secret**. -6. Re-open the secret entry and confirm the name shows `CLASSROOM_ORG_ADMIN_TOKEN`. GitHub does not display the value again, but confirming the name is correct is sufficient. - -**Step B.3 -- Add the repository variables** +**Step B.1 -- Add the repository variables** 1. At the same settings page, select the **Variables** tab (next to Secrets). 2. Select **New repository variable** for each of the following. Add them one at a time. Variable 1: - - **Name**: `CLASSROOM_ORG` - - **Value**: `Community-Access-Classroom` - - This is the exact GitHub organization name where students are invited. The capitalization and hyphens must match exactly. - - Variable 2: - **Name**: `CLASSROOM_DAY1_ASSIGNMENT_URL` - **Value**: paste the Day 1 invite URL you copied in section A.1 step 5 (format: `https://classroom.github.com/a/`) - Variable 3: + Variable 2: - **Name**: `CLASSROOM_DAY2_ASSIGNMENT_URL` - **Value**: paste the Day 2 invite URL you copied in section A.1 step 6 (format: `https://classroom.github.com/a/`) -3. After adding all three, re-open each variable entry and confirm: +3. After adding both, re-open each variable entry and confirm: - The name is exactly as listed above (no typos, no extra characters). - The value has no leading or trailing spaces. Paste into a plain text editor first if you are unsure, and trim whitespace before re-pasting. 4. Run one registration test and confirm welcome comment contains assignment links. Why this matters: -- These values drive invite and assignment-link injection in registration responses. A single typo in the org name or a trailing space in a variable value will silently break automation without a clear error message. +- These values drive assignment-link injection in registration responses. A trailing space in a variable value will silently break automation without a clear error message. #### C. Configure template repository Actions permissions @@ -282,7 +252,7 @@ Collect the following evidence while running QA. - Screenshots of registration confirmation and waitlist behavior. - Screenshot of Day 1 and Day 2 assignment configuration pages. -- Screenshot of Day 1 and Day 2 autograding test lists with correct counts. +- Screenshot of Day 1 and Day 2 assignment pages showing the autograding tests area is intentionally empty, plus a screenshot of the template repo's `.github/workflows/` folder listing the eight autograder workflows. - Link to Learning Room template sync PR (or explicit no-change output) before cohort launch. - Evidence of template smoke validation from a repo created from `Community-Access/learning-room-template`. - Links to test student Day 1 and Day 2 repositories. @@ -340,7 +310,7 @@ Use this section as the operational standard for every phase. | Content validation feedback | Test student PR checks/comments and Actions | Within approximately 60 seconds after PR open/update | Include link/markdown/accessibility issues and inspect output | Required fixes and suggestions are clear and tied to changed files | | Progression behavior | Test student Issues tab and Actions for student progression | After each challenge issue closure | Close challenge issue sequentially | Next challenge opens automatically with correct number/title | | Skills progression behavior | PR merged event and resulting comment/workflow output | After PR merge | Merge test PR and inspect workflow output | Achievement/progress feedback posts without workflow failure | -| Autograder behavior | Classroom grading panel, PR checks, and Actions logs | On relevant challenge events | Trigger known pass and known fail for each autograded challenge | Failing scenarios are understandable and pass after correct fix | +| Autograder behavior | Student-repo Actions tab and the bot comment posted on each relevant issue or PR | On relevant challenge events | Trigger known pass and known fail for each autograded challenge | Failing scenarios are understandable and pass after correct fix | | Chapter content consistency | Markdown files under [docs](../docs/README.md) | During curriculum review phase before sign-off | Execute full chapter and appendix checklist | All required docs reviewed and discrepancies logged | | Challenge coverage completeness | Challenge tracking table in this runbook | During student journey execution | Fill all rows for 1-16 and A-E | No challenge row is left blank or untracked | @@ -436,38 +406,34 @@ Pass criteria: ### Step 0.2 Deploy optional registration-to-classroom automation settings -Goal: enable automatic org invite and assignment-link injection in registration confirmation comments. +Goal: enable assignment-link injection and Day 2 release signaling in registration confirmation comments. The fastest path is `Initialize-WorkshopSetup.ps1`, which sets the secret, all three variables, verifies labels, and runs template prep in a single command. See the setup script section below. **Using the setup script (recommended):** ```powershell -scripts/classroom/Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere +scripts/classroom/Initialize-WorkshopSetup.ps1 ``` The script will: -- Prompt you if the PAT is missing or invalid - Resolve Day 1 and Day 2 assignment URLs automatically from the GitHub Classroom API (if assignments exist in the `GIT Going with Github` classroom) -- Set `CLASSROOM_ORG_ADMIN_TOKEN` secret and all three variables in `Community-Access/git-going-with-github` +- Set `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` in `Community-Access/git-going-with-github` - Verify all three required labels exist, creating any that are missing - Confirm read-back values have no leading or trailing spaces - Run `Prepare-LearningRoomTemplate.ps1` and `Test-LearningRoomTemplate.ps1` unless skipped **If running manually instead:** -1. Generate a classic PAT with `admin:org` scope at [github.com/settings/tokens](https://github.com/settings/tokens) (see section B of the setup steps above for exact steps). -2. Go to [github.com/Community-Access/git-going-with-github/settings/secrets/actions](https://github.com/Community-Access/git-going-with-github/settings/secrets/actions). -3. Create secret `CLASSROOM_ORG_ADMIN_TOKEN` with the PAT value. -4. On the Variables tab, create: - - `CLASSROOM_ORG` = `Community-Access-Classroom` +1. Go to [github.com/Community-Access/git-going-with-github/settings/variables/actions](https://github.com/Community-Access/git-going-with-github/settings/variables/actions). +2. On the Variables tab, create: - `CLASSROOM_DAY1_ASSIGNMENT_URL` = invite URL from assignment A.1 step 5 - `CLASSROOM_DAY2_ASSIGNMENT_URL` = invite URL from assignment A.1 step 6 -5. Re-open each value and verify no leading or trailing spaces. +3. Re-open each value and verify no leading or trailing spaces. Pass criteria: -- Secret and variables are present with correct values. +- Variables are present with correct values. - `Initialize-WorkshopSetup.ps1` reported no failures, or manual verification confirms all values. - Configuration aligns with [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md). @@ -542,13 +508,12 @@ gh secret list -R Community-Access/git-going-with-github gh variable list -R Community-Access/git-going-with-github ``` -Expected output: `CLASSROOM_ORG_ADMIN_TOKEN` appears in secrets, and `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL` appear in variables. +Expected output: `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` appear in variables. If any are missing, run `Initialize-WorkshopSetup.ps1` again or follow the manual steps in section B of the setup instructions. For full reference, see [REGISTRATION-QUICKSTART.md](REGISTRATION-QUICKSTART.md) and [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md). Pass criteria: -- `CLASSROOM_ORG_ADMIN_TOKEN` secret is present. -- All 3 variables are present with correct values and no leading or trailing spaces. +- Both assignment URL variables are present with correct values and no leading or trailing spaces. ### Step 3. Execute registration happy-path test @@ -560,7 +525,7 @@ Use the non-admin test student account. 4. Confirm the welcome comment includes: - Zoom registration information. - Day 1 and Day 2 assignment links (if variables are set). - - Organization invitation status when classroom org automation is active. + - Guidance to reply `ack` after Day 1 link verification. 5. Confirm `registration` label is applied. Pass criteria: @@ -660,10 +625,14 @@ Pass criteria: - `content-validation.yml` - `student-progression.yml` - `skills-progression.yml` + - `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` ### Step 8. Prove template freshness (latest release content is live) @@ -743,13 +712,13 @@ If the assignment exists and its `invite_link` is already in the `CLASSROOM_DAY1 6. Grant students admin access: No 7. Enable feedback pull requests: Yes 8. Paste description from [classroom/assignment-day1-you-belong-here.md](../classroom/assignment-day1-you-belong-here.md) -9. Add autograding from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) -- Day 1 requires exactly 4 tests totaling 50 points +9. **Skip the autograding tests area.** Autograded checks run as GitHub Actions workflows in the template repo (see [admin/classroom/autograding-setup.md](classroom/autograding-setup.md)). Leave the Classroom test cases section empty. 10. Save and copy the invite URL from the assignment page 11. If `Initialize-WorkshopSetup.ps1` has not been run yet, paste the URL into `CLASSROOM_DAY1_ASSIGNMENT_URL`. If it has been run, re-run it to pick up the new URL automatically. Pass criteria: - Day 1 assignment exists with title `You Belong Here`. -- Test count is 4, total points is 50. +- The Classroom autograding tests area is empty (checks run from template workflows instead). - Feedback pull request is enabled. - `CLASSROOM_DAY1_ASSIGNMENT_URL` variable matches the assignment invite link. @@ -770,13 +739,13 @@ If the assignment exists and its `invite_link` is already in `CLASSROOM_DAY2_ASS 3. Apply same base settings as Day 1 (individual, private, no admin access, feedback PR enabled) 4. Template: `Community-Access/learning-room-template` 5. Paste description from [classroom/assignment-day2-you-can-build-this.md](../classroom/assignment-day2-you-can-build-this.md) -6. Add Day 2 autograding from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) -- 6 tests totaling 75 points +6. **Skip the autograding tests area** for the same reason as Day 1 (see [admin/classroom/autograding-setup.md](classroom/autograding-setup.md)). 7. Save and copy the invite URL 8. Update `CLASSROOM_DAY2_ASSIGNMENT_URL` or re-run `Initialize-WorkshopSetup.ps1` to pick it up automatically Pass criteria: - Day 2 assignment exists with title `You Can Build This`. -- Test count is 6, total points is 75. +- The Classroom autograding tests area is empty (checks run from template workflows instead). - Feedback pull request is enabled. - `CLASSROOM_DAY2_ASSIGNMENT_URL` variable matches the assignment invite link. @@ -1439,9 +1408,9 @@ Use this checklist for final decision. For every item, complete the listed verif Use this section when a blocker appears during QA. 1. Registration invite automation issue: - - Step 1: Confirm `CLASSROOM_ORG_ADMIN_TOKEN` and `CLASSROOM_ORG` values are present and correctly scoped. - - Step 2: If automation is still failing, disable org invite automation by clearing `CLASSROOM_ORG`. - - Step 3: Continue registration flow with manual classroom invite process. + - Step 1: Confirm `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` are present and valid links. + - Step 2: If automation is still failing, clear the affected assignment URL variable and continue with manual link sharing. + - Step 3: Continue registration flow with manual classroom assignment guidance. - Verify: registration workflow still posts welcome response and assignment links as configured. 2. Seeding failure: @@ -1457,7 +1426,7 @@ Use this section when a blocker appears during QA. - Verify: next challenge issue appears with correct numbering. 4. Autograder mismatch: - - Step 1: Re-check exact autograder command/settings definitions in [admin/classroom/autograding-setup.md](classroom/autograding-setup.md). + - Step 1: Open the affected `autograder-*.yml` workflow file in `learning-room/.github/workflows/` and confirm its logic matches the documented behavior in [admin/classroom/autograding-setup.md](classroom/autograding-setup.md). - Step 2: Trigger known-fail and known-pass scenarios for the affected autograder. - Step 3: Compare observed output with expected rubric behavior. - Verify: fail messages are actionable and pass state is reachable with correct student behavior. @@ -1617,5 +1586,5 @@ Archive destination: `https://github.com/Community-Access/git-going-student-succ - [x] Registration issues deleted from source repository (count now 0). - [x] Discussions deleted from source repository (count now 0). - [x] Learning Room template sync PR merged: `Community-Access/learning-room-template#11`. -- [ ] Registration secret and variable values set for next cohort (`CLASSROOM_ORG_ADMIN_TOKEN`, `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL`). +- [ ] Registration variable values set for next cohort (`CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL`). - [ ] Day 1 and Day 2 classroom assignments created for next cohort. \ No newline at end of file diff --git a/admin/classroom/README.md b/admin/classroom/README.md index e4ddb6e..bed25dd 100644 --- a/admin/classroom/README.md +++ b/admin/classroom/README.md @@ -8,19 +8,18 @@ Use these files when you need to quickly configure assignments without jumping b - `day1-assignment-copy-paste.md` - Day 1 assignment body ready to paste into Classroom. - `day2-assignment-copy-paste.md` - Day 2 assignment body ready to paste into Classroom. -- `autograding-setup.md` - Exact Day 1 and Day 2 autograding entries, validation steps, and troubleshooting. +- `autograding-setup.md` - **Deprecated.** Explains that autograding now runs as workflows in the template repo and that no Classroom UI test cases are needed. - `seeding-ops.md` - Post-acceptance scripts to seed challenges and peer simulation content. -- `live-facilitation-flow.md` - Single-run checklist for creating assignments, enabling autograding, publishing, seeding, and validating. +- `live-facilitation-flow.md` - Single-run checklist for creating assignments, verifying autograder workflows, publishing, seeding, and validating. ## Recommended Setup Order 1. Create the Classroom and import roster from `classroom/README.md`. -2. Create Day 1 assignment and paste content from `day1-assignment-copy-paste.md`. -3. Configure Day 1 tests using `autograding-setup.md`. -4. Create Day 2 assignment and paste content from `day2-assignment-copy-paste.md`. -5. Configure Day 2 tests using `autograding-setup.md`. -6. After each student accepts, run seeding commands from `seeding-ops.md`. -7. Use `live-facilitation-flow.md` during setup day to execute the full flow without missing steps. +2. Create Day 1 assignment and paste content from `day1-assignment-copy-paste.md`. Leave the autograding tests area empty. +3. Create Day 2 assignment and paste content from `day2-assignment-copy-paste.md`. Leave the autograding tests area empty. +4. Confirm the autograder workflows are present in `Community-Access/learning-room-template` (see `autograding-setup.md` for the full list). +5. After each student accepts, run seeding commands from `seeding-ops.md`. +6. Use `live-facilitation-flow.md` during setup day to execute the full flow without missing steps. ## Source of Truth @@ -28,8 +27,7 @@ This pack is derived from: - `classroom/assignment-day1-you-belong-here.md` - `classroom/assignment-day2-you-can-build-this.md` -- `classroom/autograding-day1.json` -- `classroom/autograding-day2.json` +- `learning-room/.github/workflows/autograder-*.yml` (the workflows that replaced Classroom test cases) - `scripts/classroom/*.ps1` If those source files change, update this folder to keep the copy-paste flow accurate. diff --git a/admin/classroom/autograding-setup.md b/admin/classroom/autograding-setup.md index 036f14a..7e26d3b 100644 --- a/admin/classroom/autograding-setup.md +++ b/admin/classroom/autograding-setup.md @@ -1,211 +1,48 @@ -# Autograding Setup and Verification +# Autograding Setup -- Not Required -This guide makes Classroom autograding setup repeatable and reliable for facilitators. +> **Status: deprecated as of May 2026.** You do **not** need to configure any test cases in the GitHub Classroom autograding UI for this workshop. Skip that step entirely when creating Day 1 and Day 2 assignments. -## Scope +## Why this changed -- Day 1 tests come from `classroom/autograding-day1.json` -- Day 2 tests come from `classroom/autograding-day2.json` -- All entries below are copy-accurate from those files +GitHub Classroom's "test cases" panel intermittently fails to save edits (the modal closes with no error and the test list comes back empty). Rather than fight a broken UI on every cohort, every autograded check has been re-implemented as a normal GitHub Actions workflow inside `Community-Access/learning-room-template`. Those workflows are copied into each student repo automatically when GitHub Classroom creates the repo from the template -- no Classroom configuration required. -## UI Entry Rules (Use for Every Test) +## Where the checks live now -For each test you add in Classroom: +Each check below runs as its own workflow in the student repo. Results are posted as a single PR or issue comment that updates in place on each push. -- Set **Test name** exactly as shown below -- Set **Run command** exactly as shown below -- Set **Comparison** to `exact` -- Leave **Setup**, **Input**, and **Expected output** empty unless noted -- Set **Timeout** and **Points** exactly as shown below +### Day 1 checks -Do not paste raw JSON into the UI. Add tests one by one. +| Challenge | What it verifies | Workflow file | +|---|---|---| +| 2: Issue Filed | Student has opened at least one issue in their repo | `.github/workflows/autograder-issue-filed.yml` | +| 5: Commit on a branch | At least one commit on a non-default branch | `.github/workflows/autograder-branch-commit.yml` | +| 6: PR links to an issue | PR body contains `Closes`, `Fixes`, or `Resolves #N` | `.github/workflows/autograder-pr-link.yml` | +| 7: No conflict markers | No `<<<<<<<`, `=======`, or `>>>>>>>` markers in `docs/` | `.github/workflows/autograder-conflicts.yml` | -## Day 1 Autograding Tests +### Day 2 checks -### Test 1 +| Challenge | What it verifies | Workflow file | +|---|---|---| +| 10: Local commit | At least one commit on a non-default branch | `.github/workflows/autograder-local-commit.yml` | +| 14: Custom issue template | A non-challenge YAML template under `.github/ISSUE_TEMPLATE/` with `name:` and `description:` fields | `.github/workflows/autograder-template.yml` | +| 16: Capstone agent file | Agent markdown file with frontmatter, responsibilities, and guardrails | `.github/workflows/autograder-capstone.yml` | -- Test name: `Challenge 2: Issue Filed` -- Run command: +A separate workflow, `.github/workflows/autograder-watchdog.yml`, listens for `workflow_run` completion of every autograder above. If one of them ends with `conclusion: failure` and no challenge-result comment has been posted on the open PR for that branch, the watchdog posts a single fallback notice telling the student the check could not complete and to ping a facilitator. If the in-job error handler already posted a comment, the watchdog is a no-op. This is a safety net only -- the seven primary workflows remain the source of truth for pass/fail. -```bash -gh issue list --repo $GITHUB_REPOSITORY --author $GITHUB_ACTOR --state all --json number --jq 'length' | xargs test 0 -lt -``` +## What to do during cohort setup -- Comparison: `exact` -- Timeout: `10` -- Points: `10` +When creating Day 1 and Day 2 assignments in GitHub Classroom: -### Test 2 +1. Paste the assignment description as usual. +2. **Skip the autograding tests section.** Leave it empty. Do not click `Add test`. +3. Save the assignment and copy the invite URL. -- Test name: `Challenge 5: Commit Exists` -- Run command: +That is the entire change. Everything else in `live-facilitation-flow.md` still applies. -```bash -git log --oneline --all --author=$GITHUB_ACTOR | head -1 | grep -q '.' -``` +## Verifying the checks work -- Comparison: `exact` -- Timeout: `10` -- Points: `10` +Before sharing invite links, use a test student account to verify each workflow posts its comment. The procedure is in `live-facilitation-flow.md` (Phase 3: Verify Autograder Workflows). -### Test 3 +## Historical reference -- Test name: `Challenge 6: PR with Issue Link` -- Run command: - -```bash -gh pr list --repo $GITHUB_REPOSITORY --author $GITHUB_ACTOR --state all --json body --jq '.[0].body' | grep -iq 'closes\|fixes\|resolves' -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `15` - -### Test 4 - -- Test name: `Challenge 7: No Conflict Markers` -- Run command: - -```bash -! grep -rn '<<<<<<< \|======= \|>>>>>>> ' docs/ 2>/dev/null -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `15` - -## Day 2 Autograding Tests - -### Test 1 - -- Test name: `Challenge 10: Go Local - Commit on Branch` -- Run command: - -```bash -git log --oneline origin/main..HEAD 2>/dev/null | head -1 | grep -q '.' || git branch -r --list 'origin/*' | grep -v main | head -1 | xargs -I{} git log --oneline origin/main..{} | head -1 | grep -q '.' -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `15` - -### Test 2 - -- Test name: `Challenge 14: Template Remix - Custom Issue Template Exists` -- Run command: - -```bash -find .github/ISSUE_TEMPLATE -name '*.yml' ! -name 'challenge-*.yml' ! -name 'bonus-*.yml' ! -name 'config.yml' 2>/dev/null | head -1 | grep -q '.' -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `15` - -### Test 3 - -- Test name: `Challenge 14: Template Remix - Template Has Required Fields` -- Run command: - -```bash -TEMPLATE=$(find .github/ISSUE_TEMPLATE -name '*.yml' ! -name 'challenge-*.yml' ! -name 'bonus-*.yml' ! -name 'config.yml' 2>/dev/null | head -1); grep -q '^name:' "$TEMPLATE" && grep -q '^description:' "$TEMPLATE" -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `10` - -### Test 4 - -- Test name: `Challenge 16: Build Your Agent - Agent File Exists` -- Run command: - -```bash -find agents community-agents -name '*.md' 2>/dev/null | head -1 | grep -q '.' -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `10` - -### Test 5 - -- Test name: `Challenge 16: Build Your Agent - Agent Has Frontmatter` -- Run command: - -```bash -AGENT=$(find agents community-agents -name '*.md' 2>/dev/null | head -1); head -1 "$AGENT" | grep -q '^---' -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `10` - -### Test 6 - -- Test name: `Challenge 16: Build Your Agent - Agent Has Responsibilities and Guardrails` -- Run command: - -```bash -AGENT=$(find agents community-agents -name '*.md' 2>/dev/null | head -1); grep -qi '## responsibilities\|## what this agent does' "$AGENT" && grep -qi '## guardrails\|## limitations\|## boundaries' "$AGENT" -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `15` - -## Hardening Checklist Before Cohort Start - -1. Add all tests and save assignment. -2. Confirm test count: - - Day 1 has 4 tests - - Day 2 has 6 tests -3. Confirm point totals: - - Day 1 total = 50 - - Day 2 total = 75 -4. Use a test student account to accept each assignment. -5. Trigger one known pass on each assignment. -6. Trigger one known fail on each assignment and confirm feedback appears. -7. Confirm rerun passes after fix. -8. Capture one screenshot of pass and one of fail for facilitator reference. - -## Fast Validation Scenarios - -### Day 1 quick checks - -- Pass check: open an issue, make a commit, open a PR with `Closes #`, ensure no conflict markers remain in `docs/`. -- Fail check: open a PR without `Closes`, `Fixes`, or `Resolves` in the body. - -### Day 2 quick checks - -- Pass check: create one non-main commit, add a custom issue template with `name:` and `description:`, add an agent markdown file with frontmatter and required sections. -- Fail check: create an agent file without a `## Responsibilities` section. - -## Troubleshooting - -### Test stays red after student fix - -1. Confirm student pushed a new commit to the same PR branch. -2. Open PR checks and inspect the failing command output. -3. Verify required text is in the file body, not only in issue comments. - -### Challenge 14 tests fail unexpectedly - -- Verify template filename is `.yml`. -- Verify it is under `.github/ISSUE_TEMPLATE`. -- Verify filename does not match `challenge-*.yml`, `bonus-*.yml`, or `config.yml`. - -### Challenge 16 section check fails - -- Ensure headings use markdown heading syntax (for example `## Responsibilities`). -- Ensure guardrail heading uses one accepted form: - - `## Guardrails` - - `## Limitations` - - `## Boundaries` - -## Keep This Guide Synced - -If autograding JSON changes, update this file in the same pull request: - -- `classroom/autograding-day1.json` -- `classroom/autograding-day2.json` +The Classroom test-case definitions that used to live in `classroom/autograding-day1.json` and `classroom/autograding-day2.json` were deleted in May 2026 along with this workflow migration. The autograder workflow files (`learning-room/.github/workflows/autograder-*.yml`) are the only remaining source of truth for what each check verifies. Git history retains the old JSONs if you ever need to read them. diff --git a/admin/classroom/live-facilitation-flow.md b/admin/classroom/live-facilitation-flow.md index ea811d7..de3b795 100644 --- a/admin/classroom/live-facilitation-flow.md +++ b/admin/classroom/live-facilitation-flow.md @@ -21,12 +21,20 @@ Use this checklist when setting up a new cohort so you can run the full Classroo - [ ] Set deadline for your cohort. - [ ] Copy description from `day1-assignment-copy-paste.md` and paste into Classroom. -## Phase 3: Configure Day 1 Autograding - -- [ ] Open `autograding-setup.md`. -- [ ] Add all Day 1 tests exactly as listed. -- [ ] Verify Day 1 test count is 4. -- [ ] Verify Day 1 point total is 50. +## Phase 3: Verify Autograder Workflows (no Classroom configuration) + +Autograded checks are GitHub Actions workflows shipped inside the template repo. **Do not configure any test cases in the Classroom UI** -- leave that section empty when you save the assignment. See [autograding-setup.md](autograding-setup.md) for the full rationale. + +- [ ] Confirm `Community-Access/learning-room-template` contains all of the following workflow files under `.github/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` +- [ ] In the Day 1 assignment editor, leave the **Add test** / autograding tests area empty. - [ ] Save assignment. ## Phase 4: Create Day 2 Assignment @@ -41,12 +49,12 @@ Use this checklist when setting up a new cohort so you can run the full Classroo - [ ] Set deadline for your cohort. - [ ] Copy description from `day2-assignment-copy-paste.md` and paste into Classroom. -## Phase 5: Configure Day 2 Autograding +## Phase 5: Verify Day 2 Autograder Workflows (no Classroom configuration) + +Same model as Phase 3 -- the Day 2 checks (Challenges 10, 14, 16) run from the same template workflows. Do not enter any tests in the Classroom UI. -- [ ] Open `autograding-setup.md`. -- [ ] Add all Day 2 tests exactly as listed. -- [ ] Verify Day 2 test count is 6. -- [ ] Verify Day 2 point total is 75. +- [ ] Confirm the Day 2 autograder workflows are present in the template (`autograder-local-commit.yml`, `autograder-template.yml`, `autograder-capstone.yml`). +- [ ] In the Day 2 assignment editor, leave the **Add test** / autograding tests area empty. - [ ] Save assignment. ## Phase 6: Publish and Share @@ -83,14 +91,13 @@ scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom - [ ] Confirm challenge issue exists after seeding. - [ ] Confirm Student Progression workflow run appears in Actions. -- [ ] Confirm one autograding failure scenario is detected correctly. -- [ ] Confirm one fixed rerun passes. +- [ ] Confirm at least one autograder workflow posts a fail comment for a known-bad state, and a pass comment after the fix is pushed. - [ ] Confirm peer simulation artifacts exist (2 issues + 1 PR). ## Phase 9: Cohort Readiness Sign-Off - [ ] Day 1 and Day 2 assignments published. - [ ] Invite links validated. -- [ ] Autograding configured and tested. +- [ ] Autograder workflows verified to post comments in a test student repo. - [ ] Seeding scripts verified against a test student repo. - [ ] Facilitator notes updated with links and fallback instructions. diff --git a/admin/qa-bundle/GO-LIVE-QA-GUIDE.md b/admin/qa-bundle/GO-LIVE-QA-GUIDE.md index f74079a..8d9f8e3 100644 --- a/admin/qa-bundle/GO-LIVE-QA-GUIDE.md +++ b/admin/qa-bundle/GO-LIVE-QA-GUIDE.md @@ -16,22 +16,25 @@ Do not mark a cohort ready until all required items in this section are complete - [ ] RSS feed validation passes for the current audio state. - [ ] Git diff whitespace check has no actual whitespace or conflict-marker errors. - [ ] Registration deployment gate completed (issue form template, workflow enablement, required labels, and optional classroom automation settings). +- [ ] Registration comment flow is assignment-link based (no org invite dependency). - [ ] Support Hub is provisioned and publicly accessible at `Community-Access/support`. - [ ] Registration confirmation and help pathways route support requests to Support Hub issues/discussions. - [ ] Registration issue form template and labels are configured (`workshop-registration.yml`, `registration`, `duplicate`, `waitlist`). - [ ] Learning Room source has been synced to `Community-Access/learning-room-template` and merged to `main` (or validated as no-change). - [ ] Template smoke validation from `Community-Access/learning-room-template` succeeded before assignment publishing. - [ ] Template freshness proof confirms smoke repo content matches latest merged template sync changes. -- [ ] Smoke repo confirms all required workflow files are present (PR validation, content validation, progression, skills progression, and all autograders). +- [ ] 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` in enrollment issue 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. - [ ] Aria posts PR feedback on a test pull request. - [ ] Student Progression Bot creates the next challenge when a challenge issue is closed. -- [ ] Autograding runs and reports results in GitHub Classroom. +- [ ] 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](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. @@ -155,7 +158,7 @@ Use a real GitHub Classroom with disposable test accounts. Do not use a facilita - [ ] Create the Day 1 assignment using [classroom/assignment-day1-you-belong-here.md](classroom/assignment-day1-you-belong-here.md). - [ ] Use private individual repositories. - [ ] Enable feedback pull requests. -- [ ] Add every Day 1 autograding test from [classroom/autograding-day1.json](classroom/autograding-day1.json). +- [ ] 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](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. @@ -174,7 +177,7 @@ scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Cl - [ ] Create the Day 2 assignment using [classroom/assignment-day2-you-can-build-this.md](classroom/assignment-day2-you-can-build-this.md). - [ ] Use private individual repositories. - [ ] Enable feedback pull requests. -- [ ] Add every Day 2 autograding test from [classroom/autograding-day2.json](classroom/autograding-day2.json). +- [ ] 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](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. diff --git a/admin/qa-bundle/README.md b/admin/qa-bundle/README.md index ff81689..d8a3fab 100644 --- a/admin/qa-bundle/README.md +++ b/admin/qa-bundle/README.md @@ -223,8 +223,6 @@ Every chapter has an "If You Get Stuck" section. Every challenge has a [referenc │ ├── 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 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 fe7e5bc..d87241a 100644 --- a/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md +++ b/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md @@ -85,8 +85,7 @@ Complete all items below before any cohort launch actions. - [x] `GITHUB_TOKEN` default workflow permissions include write where required - [x] `Allow GitHub Actions to create and approve pull requests` enabled - [ ] Registration automation settings are correct when using registration-to-classroom handoff: - - [ ] Secret `CLASSROOM_ORG_ADMIN_TOKEN` is set in `Community-Access/git-going-with-github` - - [ ] Variables `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL` are set in `Community-Access/git-going-with-github` + - [ ] Variables `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` are set in `Community-Access/git-going-with-github` - [x] Registration entry configuration exists and is valid: - [x] Issue form template `workshop-registration.yml` exists - [x] Required labels exist: `registration`, `duplicate`, `waitlist` @@ -142,14 +141,14 @@ You must be signed in to GitHub as `accesswatch` for the following steps. - **Grant students admin access**: No - **Enable feedback pull requests**: Yes - Paste the Day 1 assignment description from [classroom/assignment-day1-you-belong-here.md](../classroom/assignment-day1-you-belong-here.md) - - Add autograding from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) -- Day 1 requires exactly 4 tests totaling 50 points + - **Skip the autograding tests area.** Autograded checks run as GitHub Actions workflows in the template repo (see [admin/classroom/autograding-setup.md](classroom/autograding-setup.md)). Leave the Classroom test cases section empty. - Select **Create assignment** 5. After saving, the assignment page shows an invite link at the top labeled something like **Invite link**. It will be in the format `https://classroom.github.com/a/`. Copy this full URL and paste it somewhere safe (for example, a scratch notepad). This is your `CLASSROOM_DAY1_ASSIGNMENT_URL`. 6. Repeat for the Day 2 assignment: - **Title**: `You Can Build This` - Same base settings as Day 1 - Paste description from [classroom/assignment-day2-you-can-build-this.md](../classroom/assignment-day2-you-can-build-this.md) - - Add Day 2 autograding: exactly 6 tests totaling 75 points + - **Skip the autograding tests area** for the same reason as Day 1. - Copy the resulting invite URL. This is your `CLASSROOM_DAY2_ASSIGNMENT_URL`. 7. Keep both URLs available. You will paste them into repository variables in section B step 4. @@ -157,62 +156,33 @@ Why this matters: - The repository variables `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` cannot be filled in until the assignments exist and their invite URLs are known. The short code in the URL is unique to each assignment and is not predictable in advance. -#### B. Configure registration automation key and variables +#### B. Configure registration automation variables Repository target: `Community-Access/git-going-with-github` You must be signed in as `accesswatch` for all steps in this section. -**Step B.1 -- Generate the personal access token (PAT)** - -The `CLASSROOM_ORG_ADMIN_TOKEN` secret must be a GitHub personal access token generated by `accesswatch` (or another Owner-level account for `Community-Access-Classroom`). This token is what allows the registration workflow to invite students to the `Community-Access-Classroom` organization automatically. - -1. While signed in as `accesswatch`, go to [github.com/settings/tokens](https://github.com/settings/tokens). -2. Select **Generate new token**, then select **Generate new token (classic)**. - - Do not use fine-grained tokens for this purpose. The `admin:org` scope is only available on classic tokens. -3. In the **Note** field enter a descriptive name such as `Community-Access registration automation`. -4. In the **Expiration** field, set a date that covers your cohort timeline plus a buffer (for example, 90 days). -5. Under **Select scopes**, check `admin:org`. This is the only scope required. It gives the token permission to list and create organization invitations for `Community-Access-Classroom`. -6. Scroll to the bottom and select **Generate token**. -7. GitHub will display the token exactly once immediately after generation. It begins with `ghp_`. Copy it now and paste it somewhere safe (a local scratch notepad, not a repository file). You will not be able to view it again. -8. Do not close the token page until you have completed section B.2 and confirmed the secret was saved. - -**Step B.2 -- Add the token as a repository secret** - -1. Go to [github.com/Community-Access/git-going-with-github/settings/secrets/actions](https://github.com/Community-Access/git-going-with-github/settings/secrets/actions). -2. Select **New repository secret**. -3. In the **Name** field, enter exactly: `CLASSROOM_ORG_ADMIN_TOKEN` - - Capitalization and underscores must match exactly. -4. In the **Secret** field, paste the token you copied in step B.1. -5. Select **Add secret**. -6. Re-open the secret entry and confirm the name shows `CLASSROOM_ORG_ADMIN_TOKEN`. GitHub does not display the value again, but confirming the name is correct is sufficient. - -**Step B.3 -- Add the repository variables** +**Step B.1 -- Add the repository variables** 1. At the same settings page, select the **Variables** tab (next to Secrets). 2. Select **New repository variable** for each of the following. Add them one at a time. Variable 1: - - **Name**: `CLASSROOM_ORG` - - **Value**: `Community-Access-Classroom` - - This is the exact GitHub organization name where students are invited. The capitalization and hyphens must match exactly. - - Variable 2: - **Name**: `CLASSROOM_DAY1_ASSIGNMENT_URL` - **Value**: paste the Day 1 invite URL you copied in section A.1 step 5 (format: `https://classroom.github.com/a/`) - Variable 3: + Variable 2: - **Name**: `CLASSROOM_DAY2_ASSIGNMENT_URL` - **Value**: paste the Day 2 invite URL you copied in section A.1 step 6 (format: `https://classroom.github.com/a/`) -3. After adding all three, re-open each variable entry and confirm: +3. After adding both, re-open each variable entry and confirm: - The name is exactly as listed above (no typos, no extra characters). - The value has no leading or trailing spaces. Paste into a plain text editor first if you are unsure, and trim whitespace before re-pasting. 4. Run one registration test and confirm welcome comment contains assignment links. Why this matters: -- These values drive invite and assignment-link injection in registration responses. A single typo in the org name or a trailing space in a variable value will silently break automation without a clear error message. +- These values drive assignment-link injection in registration responses. A trailing space in a variable value will silently break automation without a clear error message. #### C. Configure template repository Actions permissions @@ -282,7 +252,7 @@ Collect the following evidence while running QA. - Screenshots of registration confirmation and waitlist behavior. - Screenshot of Day 1 and Day 2 assignment configuration pages. -- Screenshot of Day 1 and Day 2 autograding test lists with correct counts. +- Screenshot of Day 1 and Day 2 assignment pages showing the autograding tests area is intentionally empty, plus a screenshot of the template repo's `.github/workflows/` folder listing the eight autograder workflows. - Link to Learning Room template sync PR (or explicit no-change output) before cohort launch. - Evidence of template smoke validation from a repo created from `Community-Access/learning-room-template`. - Links to test student Day 1 and Day 2 repositories. @@ -340,7 +310,7 @@ Use this section as the operational standard for every phase. | Content validation feedback | Test student PR checks/comments and Actions | Within approximately 60 seconds after PR open/update | Include link/markdown/accessibility issues and inspect output | Required fixes and suggestions are clear and tied to changed files | | Progression behavior | Test student Issues tab and Actions for student progression | After each challenge issue closure | Close challenge issue sequentially | Next challenge opens automatically with correct number/title | | Skills progression behavior | PR merged event and resulting comment/workflow output | After PR merge | Merge test PR and inspect workflow output | Achievement/progress feedback posts without workflow failure | -| Autograder behavior | Classroom grading panel, PR checks, and Actions logs | On relevant challenge events | Trigger known pass and known fail for each autograded challenge | Failing scenarios are understandable and pass after correct fix | +| Autograder behavior | Student-repo Actions tab and the bot comment posted on each relevant issue or PR | On relevant challenge events | Trigger known pass and known fail for each autograded challenge | Failing scenarios are understandable and pass after correct fix | | Chapter content consistency | Markdown files under [docs](../docs/README.md) | During curriculum review phase before sign-off | Execute full chapter and appendix checklist | All required docs reviewed and discrepancies logged | | Challenge coverage completeness | Challenge tracking table in this runbook | During student journey execution | Fill all rows for 1-16 and A-E | No challenge row is left blank or untracked | @@ -436,38 +406,34 @@ Pass criteria: ### Step 0.2 Deploy optional registration-to-classroom automation settings -Goal: enable automatic org invite and assignment-link injection in registration confirmation comments. +Goal: enable assignment-link injection and Day 2 release signaling in registration confirmation comments. The fastest path is `Initialize-WorkshopSetup.ps1`, which sets the secret, all three variables, verifies labels, and runs template prep in a single command. See the setup script section below. **Using the setup script (recommended):** ```powershell -scripts/classroom/Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere +scripts/classroom/Initialize-WorkshopSetup.ps1 ``` The script will: -- Prompt you if the PAT is missing or invalid - Resolve Day 1 and Day 2 assignment URLs automatically from the GitHub Classroom API (if assignments exist in the `GIT Going with Github` classroom) -- Set `CLASSROOM_ORG_ADMIN_TOKEN` secret and all three variables in `Community-Access/git-going-with-github` +- Set `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` in `Community-Access/git-going-with-github` - Verify all three required labels exist, creating any that are missing - Confirm read-back values have no leading or trailing spaces - Run `Prepare-LearningRoomTemplate.ps1` and `Test-LearningRoomTemplate.ps1` unless skipped **If running manually instead:** -1. Generate a classic PAT with `admin:org` scope at [github.com/settings/tokens](https://github.com/settings/tokens) (see section B of the setup steps above for exact steps). -2. Go to [github.com/Community-Access/git-going-with-github/settings/secrets/actions](https://github.com/Community-Access/git-going-with-github/settings/secrets/actions). -3. Create secret `CLASSROOM_ORG_ADMIN_TOKEN` with the PAT value. -4. On the Variables tab, create: - - `CLASSROOM_ORG` = `Community-Access-Classroom` +1. Go to [github.com/Community-Access/git-going-with-github/settings/variables/actions](https://github.com/Community-Access/git-going-with-github/settings/variables/actions). +2. On the Variables tab, create: - `CLASSROOM_DAY1_ASSIGNMENT_URL` = invite URL from assignment A.1 step 5 - `CLASSROOM_DAY2_ASSIGNMENT_URL` = invite URL from assignment A.1 step 6 -5. Re-open each value and verify no leading or trailing spaces. +3. Re-open each value and verify no leading or trailing spaces. Pass criteria: -- Secret and variables are present with correct values. +- Variables are present with correct values. - `Initialize-WorkshopSetup.ps1` reported no failures, or manual verification confirms all values. - Configuration aligns with [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md). @@ -542,13 +508,12 @@ gh secret list -R Community-Access/git-going-with-github gh variable list -R Community-Access/git-going-with-github ``` -Expected output: `CLASSROOM_ORG_ADMIN_TOKEN` appears in secrets, and `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL` appear in variables. +Expected output: `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` appear in variables. If any are missing, run `Initialize-WorkshopSetup.ps1` again or follow the manual steps in section B of the setup instructions. For full reference, see [REGISTRATION-QUICKSTART.md](REGISTRATION-QUICKSTART.md) and [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md). Pass criteria: -- `CLASSROOM_ORG_ADMIN_TOKEN` secret is present. -- All 3 variables are present with correct values and no leading or trailing spaces. +- Both assignment URL variables are present with correct values and no leading or trailing spaces. ### Step 3. Execute registration happy-path test @@ -560,7 +525,7 @@ Use the non-admin test student account. 4. Confirm the welcome comment includes: - Zoom registration information. - Day 1 and Day 2 assignment links (if variables are set). - - Organization invitation status when classroom org automation is active. + - Guidance to reply `ack` after Day 1 link verification. 5. Confirm `registration` label is applied. Pass criteria: @@ -660,10 +625,14 @@ Pass criteria: - `content-validation.yml` - `student-progression.yml` - `skills-progression.yml` + - `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` ### Step 8. Prove template freshness (latest release content is live) @@ -743,13 +712,13 @@ If the assignment exists and its `invite_link` is already in the `CLASSROOM_DAY1 6. Grant students admin access: No 7. Enable feedback pull requests: Yes 8. Paste description from [classroom/assignment-day1-you-belong-here.md](../classroom/assignment-day1-you-belong-here.md) -9. Add autograding from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) -- Day 1 requires exactly 4 tests totaling 50 points +9. **Skip the autograding tests area.** Autograded checks run as GitHub Actions workflows in the template repo (see [admin/classroom/autograding-setup.md](classroom/autograding-setup.md)). Leave the Classroom test cases section empty. 10. Save and copy the invite URL from the assignment page 11. If `Initialize-WorkshopSetup.ps1` has not been run yet, paste the URL into `CLASSROOM_DAY1_ASSIGNMENT_URL`. If it has been run, re-run it to pick up the new URL automatically. Pass criteria: - Day 1 assignment exists with title `You Belong Here`. -- Test count is 4, total points is 50. +- The Classroom autograding tests area is empty (checks run from template workflows instead). - Feedback pull request is enabled. - `CLASSROOM_DAY1_ASSIGNMENT_URL` variable matches the assignment invite link. @@ -770,13 +739,13 @@ If the assignment exists and its `invite_link` is already in `CLASSROOM_DAY2_ASS 3. Apply same base settings as Day 1 (individual, private, no admin access, feedback PR enabled) 4. Template: `Community-Access/learning-room-template` 5. Paste description from [classroom/assignment-day2-you-can-build-this.md](../classroom/assignment-day2-you-can-build-this.md) -6. Add Day 2 autograding from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) -- 6 tests totaling 75 points +6. **Skip the autograding tests area** for the same reason as Day 1 (see [admin/classroom/autograding-setup.md](classroom/autograding-setup.md)). 7. Save and copy the invite URL 8. Update `CLASSROOM_DAY2_ASSIGNMENT_URL` or re-run `Initialize-WorkshopSetup.ps1` to pick it up automatically Pass criteria: - Day 2 assignment exists with title `You Can Build This`. -- Test count is 6, total points is 75. +- The Classroom autograding tests area is empty (checks run from template workflows instead). - Feedback pull request is enabled. - `CLASSROOM_DAY2_ASSIGNMENT_URL` variable matches the assignment invite link. @@ -1439,9 +1408,9 @@ Use this checklist for final decision. For every item, complete the listed verif Use this section when a blocker appears during QA. 1. Registration invite automation issue: - - Step 1: Confirm `CLASSROOM_ORG_ADMIN_TOKEN` and `CLASSROOM_ORG` values are present and correctly scoped. - - Step 2: If automation is still failing, disable org invite automation by clearing `CLASSROOM_ORG`. - - Step 3: Continue registration flow with manual classroom invite process. + - Step 1: Confirm `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` are present and valid links. + - Step 2: If automation is still failing, clear the affected assignment URL variable and continue with manual link sharing. + - Step 3: Continue registration flow with manual classroom assignment guidance. - Verify: registration workflow still posts welcome response and assignment links as configured. 2. Seeding failure: @@ -1457,7 +1426,7 @@ Use this section when a blocker appears during QA. - Verify: next challenge issue appears with correct numbering. 4. Autograder mismatch: - - Step 1: Re-check exact autograder command/settings definitions in [admin/classroom/autograding-setup.md](classroom/autograding-setup.md). + - Step 1: Open the affected `autograder-*.yml` workflow file in `learning-room/.github/workflows/` and confirm its logic matches the documented behavior in [admin/classroom/autograding-setup.md](classroom/autograding-setup.md). - Step 2: Trigger known-fail and known-pass scenarios for the affected autograder. - Step 3: Compare observed output with expected rubric behavior. - Verify: fail messages are actionable and pass state is reachable with correct student behavior. @@ -1617,5 +1586,5 @@ Archive destination: `https://github.com/Community-Access/git-going-student-succ - [x] Registration issues deleted from source repository (count now 0). - [x] Discussions deleted from source repository (count now 0). - [x] Learning Room template sync PR merged: `Community-Access/learning-room-template#11`. -- [ ] Registration secret and variable values set for next cohort (`CLASSROOM_ORG_ADMIN_TOKEN`, `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL`). +- [ ] Registration variable values set for next cohort (`CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL`). - [ ] Day 1 and Day 2 classroom assignments created for next cohort. \ No newline at end of file diff --git a/admin/qa-bundle/admin/classroom/README.md b/admin/qa-bundle/admin/classroom/README.md index e4ddb6e..bed25dd 100644 --- a/admin/qa-bundle/admin/classroom/README.md +++ b/admin/qa-bundle/admin/classroom/README.md @@ -8,19 +8,18 @@ Use these files when you need to quickly configure assignments without jumping b - `day1-assignment-copy-paste.md` - Day 1 assignment body ready to paste into Classroom. - `day2-assignment-copy-paste.md` - Day 2 assignment body ready to paste into Classroom. -- `autograding-setup.md` - Exact Day 1 and Day 2 autograding entries, validation steps, and troubleshooting. +- `autograding-setup.md` - **Deprecated.** Explains that autograding now runs as workflows in the template repo and that no Classroom UI test cases are needed. - `seeding-ops.md` - Post-acceptance scripts to seed challenges and peer simulation content. -- `live-facilitation-flow.md` - Single-run checklist for creating assignments, enabling autograding, publishing, seeding, and validating. +- `live-facilitation-flow.md` - Single-run checklist for creating assignments, verifying autograder workflows, publishing, seeding, and validating. ## Recommended Setup Order 1. Create the Classroom and import roster from `classroom/README.md`. -2. Create Day 1 assignment and paste content from `day1-assignment-copy-paste.md`. -3. Configure Day 1 tests using `autograding-setup.md`. -4. Create Day 2 assignment and paste content from `day2-assignment-copy-paste.md`. -5. Configure Day 2 tests using `autograding-setup.md`. -6. After each student accepts, run seeding commands from `seeding-ops.md`. -7. Use `live-facilitation-flow.md` during setup day to execute the full flow without missing steps. +2. Create Day 1 assignment and paste content from `day1-assignment-copy-paste.md`. Leave the autograding tests area empty. +3. Create Day 2 assignment and paste content from `day2-assignment-copy-paste.md`. Leave the autograding tests area empty. +4. Confirm the autograder workflows are present in `Community-Access/learning-room-template` (see `autograding-setup.md` for the full list). +5. After each student accepts, run seeding commands from `seeding-ops.md`. +6. Use `live-facilitation-flow.md` during setup day to execute the full flow without missing steps. ## Source of Truth @@ -28,8 +27,7 @@ This pack is derived from: - `classroom/assignment-day1-you-belong-here.md` - `classroom/assignment-day2-you-can-build-this.md` -- `classroom/autograding-day1.json` -- `classroom/autograding-day2.json` +- `learning-room/.github/workflows/autograder-*.yml` (the workflows that replaced Classroom test cases) - `scripts/classroom/*.ps1` If those source files change, update this folder to keep the copy-paste flow accurate. diff --git a/admin/qa-bundle/admin/classroom/autograding-setup.md b/admin/qa-bundle/admin/classroom/autograding-setup.md index 036f14a..7e26d3b 100644 --- a/admin/qa-bundle/admin/classroom/autograding-setup.md +++ b/admin/qa-bundle/admin/classroom/autograding-setup.md @@ -1,211 +1,48 @@ -# Autograding Setup and Verification +# Autograding Setup -- Not Required -This guide makes Classroom autograding setup repeatable and reliable for facilitators. +> **Status: deprecated as of May 2026.** You do **not** need to configure any test cases in the GitHub Classroom autograding UI for this workshop. Skip that step entirely when creating Day 1 and Day 2 assignments. -## Scope +## Why this changed -- Day 1 tests come from `classroom/autograding-day1.json` -- Day 2 tests come from `classroom/autograding-day2.json` -- All entries below are copy-accurate from those files +GitHub Classroom's "test cases" panel intermittently fails to save edits (the modal closes with no error and the test list comes back empty). Rather than fight a broken UI on every cohort, every autograded check has been re-implemented as a normal GitHub Actions workflow inside `Community-Access/learning-room-template`. Those workflows are copied into each student repo automatically when GitHub Classroom creates the repo from the template -- no Classroom configuration required. -## UI Entry Rules (Use for Every Test) +## Where the checks live now -For each test you add in Classroom: +Each check below runs as its own workflow in the student repo. Results are posted as a single PR or issue comment that updates in place on each push. -- Set **Test name** exactly as shown below -- Set **Run command** exactly as shown below -- Set **Comparison** to `exact` -- Leave **Setup**, **Input**, and **Expected output** empty unless noted -- Set **Timeout** and **Points** exactly as shown below +### Day 1 checks -Do not paste raw JSON into the UI. Add tests one by one. +| Challenge | What it verifies | Workflow file | +|---|---|---| +| 2: Issue Filed | Student has opened at least one issue in their repo | `.github/workflows/autograder-issue-filed.yml` | +| 5: Commit on a branch | At least one commit on a non-default branch | `.github/workflows/autograder-branch-commit.yml` | +| 6: PR links to an issue | PR body contains `Closes`, `Fixes`, or `Resolves #N` | `.github/workflows/autograder-pr-link.yml` | +| 7: No conflict markers | No `<<<<<<<`, `=======`, or `>>>>>>>` markers in `docs/` | `.github/workflows/autograder-conflicts.yml` | -## Day 1 Autograding Tests +### Day 2 checks -### Test 1 +| Challenge | What it verifies | Workflow file | +|---|---|---| +| 10: Local commit | At least one commit on a non-default branch | `.github/workflows/autograder-local-commit.yml` | +| 14: Custom issue template | A non-challenge YAML template under `.github/ISSUE_TEMPLATE/` with `name:` and `description:` fields | `.github/workflows/autograder-template.yml` | +| 16: Capstone agent file | Agent markdown file with frontmatter, responsibilities, and guardrails | `.github/workflows/autograder-capstone.yml` | -- Test name: `Challenge 2: Issue Filed` -- Run command: +A separate workflow, `.github/workflows/autograder-watchdog.yml`, listens for `workflow_run` completion of every autograder above. If one of them ends with `conclusion: failure` and no challenge-result comment has been posted on the open PR for that branch, the watchdog posts a single fallback notice telling the student the check could not complete and to ping a facilitator. If the in-job error handler already posted a comment, the watchdog is a no-op. This is a safety net only -- the seven primary workflows remain the source of truth for pass/fail. -```bash -gh issue list --repo $GITHUB_REPOSITORY --author $GITHUB_ACTOR --state all --json number --jq 'length' | xargs test 0 -lt -``` +## What to do during cohort setup -- Comparison: `exact` -- Timeout: `10` -- Points: `10` +When creating Day 1 and Day 2 assignments in GitHub Classroom: -### Test 2 +1. Paste the assignment description as usual. +2. **Skip the autograding tests section.** Leave it empty. Do not click `Add test`. +3. Save the assignment and copy the invite URL. -- Test name: `Challenge 5: Commit Exists` -- Run command: +That is the entire change. Everything else in `live-facilitation-flow.md` still applies. -```bash -git log --oneline --all --author=$GITHUB_ACTOR | head -1 | grep -q '.' -``` +## Verifying the checks work -- Comparison: `exact` -- Timeout: `10` -- Points: `10` +Before sharing invite links, use a test student account to verify each workflow posts its comment. The procedure is in `live-facilitation-flow.md` (Phase 3: Verify Autograder Workflows). -### Test 3 +## Historical reference -- Test name: `Challenge 6: PR with Issue Link` -- Run command: - -```bash -gh pr list --repo $GITHUB_REPOSITORY --author $GITHUB_ACTOR --state all --json body --jq '.[0].body' | grep -iq 'closes\|fixes\|resolves' -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `15` - -### Test 4 - -- Test name: `Challenge 7: No Conflict Markers` -- Run command: - -```bash -! grep -rn '<<<<<<< \|======= \|>>>>>>> ' docs/ 2>/dev/null -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `15` - -## Day 2 Autograding Tests - -### Test 1 - -- Test name: `Challenge 10: Go Local - Commit on Branch` -- Run command: - -```bash -git log --oneline origin/main..HEAD 2>/dev/null | head -1 | grep -q '.' || git branch -r --list 'origin/*' | grep -v main | head -1 | xargs -I{} git log --oneline origin/main..{} | head -1 | grep -q '.' -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `15` - -### Test 2 - -- Test name: `Challenge 14: Template Remix - Custom Issue Template Exists` -- Run command: - -```bash -find .github/ISSUE_TEMPLATE -name '*.yml' ! -name 'challenge-*.yml' ! -name 'bonus-*.yml' ! -name 'config.yml' 2>/dev/null | head -1 | grep -q '.' -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `15` - -### Test 3 - -- Test name: `Challenge 14: Template Remix - Template Has Required Fields` -- Run command: - -```bash -TEMPLATE=$(find .github/ISSUE_TEMPLATE -name '*.yml' ! -name 'challenge-*.yml' ! -name 'bonus-*.yml' ! -name 'config.yml' 2>/dev/null | head -1); grep -q '^name:' "$TEMPLATE" && grep -q '^description:' "$TEMPLATE" -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `10` - -### Test 4 - -- Test name: `Challenge 16: Build Your Agent - Agent File Exists` -- Run command: - -```bash -find agents community-agents -name '*.md' 2>/dev/null | head -1 | grep -q '.' -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `10` - -### Test 5 - -- Test name: `Challenge 16: Build Your Agent - Agent Has Frontmatter` -- Run command: - -```bash -AGENT=$(find agents community-agents -name '*.md' 2>/dev/null | head -1); head -1 "$AGENT" | grep -q '^---' -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `10` - -### Test 6 - -- Test name: `Challenge 16: Build Your Agent - Agent Has Responsibilities and Guardrails` -- Run command: - -```bash -AGENT=$(find agents community-agents -name '*.md' 2>/dev/null | head -1); grep -qi '## responsibilities\|## what this agent does' "$AGENT" && grep -qi '## guardrails\|## limitations\|## boundaries' "$AGENT" -``` - -- Comparison: `exact` -- Timeout: `10` -- Points: `15` - -## Hardening Checklist Before Cohort Start - -1. Add all tests and save assignment. -2. Confirm test count: - - Day 1 has 4 tests - - Day 2 has 6 tests -3. Confirm point totals: - - Day 1 total = 50 - - Day 2 total = 75 -4. Use a test student account to accept each assignment. -5. Trigger one known pass on each assignment. -6. Trigger one known fail on each assignment and confirm feedback appears. -7. Confirm rerun passes after fix. -8. Capture one screenshot of pass and one of fail for facilitator reference. - -## Fast Validation Scenarios - -### Day 1 quick checks - -- Pass check: open an issue, make a commit, open a PR with `Closes #`, ensure no conflict markers remain in `docs/`. -- Fail check: open a PR without `Closes`, `Fixes`, or `Resolves` in the body. - -### Day 2 quick checks - -- Pass check: create one non-main commit, add a custom issue template with `name:` and `description:`, add an agent markdown file with frontmatter and required sections. -- Fail check: create an agent file without a `## Responsibilities` section. - -## Troubleshooting - -### Test stays red after student fix - -1. Confirm student pushed a new commit to the same PR branch. -2. Open PR checks and inspect the failing command output. -3. Verify required text is in the file body, not only in issue comments. - -### Challenge 14 tests fail unexpectedly - -- Verify template filename is `.yml`. -- Verify it is under `.github/ISSUE_TEMPLATE`. -- Verify filename does not match `challenge-*.yml`, `bonus-*.yml`, or `config.yml`. - -### Challenge 16 section check fails - -- Ensure headings use markdown heading syntax (for example `## Responsibilities`). -- Ensure guardrail heading uses one accepted form: - - `## Guardrails` - - `## Limitations` - - `## Boundaries` - -## Keep This Guide Synced - -If autograding JSON changes, update this file in the same pull request: - -- `classroom/autograding-day1.json` -- `classroom/autograding-day2.json` +The Classroom test-case definitions that used to live in `classroom/autograding-day1.json` and `classroom/autograding-day2.json` were deleted in May 2026 along with this workflow migration. The autograder workflow files (`learning-room/.github/workflows/autograder-*.yml`) are the only remaining source of truth for what each check verifies. Git history retains the old JSONs if you ever need to read them. diff --git a/admin/qa-bundle/admin/classroom/live-facilitation-flow.md b/admin/qa-bundle/admin/classroom/live-facilitation-flow.md index ea811d7..de3b795 100644 --- a/admin/qa-bundle/admin/classroom/live-facilitation-flow.md +++ b/admin/qa-bundle/admin/classroom/live-facilitation-flow.md @@ -21,12 +21,20 @@ Use this checklist when setting up a new cohort so you can run the full Classroo - [ ] Set deadline for your cohort. - [ ] Copy description from `day1-assignment-copy-paste.md` and paste into Classroom. -## Phase 3: Configure Day 1 Autograding - -- [ ] Open `autograding-setup.md`. -- [ ] Add all Day 1 tests exactly as listed. -- [ ] Verify Day 1 test count is 4. -- [ ] Verify Day 1 point total is 50. +## Phase 3: Verify Autograder Workflows (no Classroom configuration) + +Autograded checks are GitHub Actions workflows shipped inside the template repo. **Do not configure any test cases in the Classroom UI** -- leave that section empty when you save the assignment. See [autograding-setup.md](autograding-setup.md) for the full rationale. + +- [ ] Confirm `Community-Access/learning-room-template` contains all of the following workflow files under `.github/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` +- [ ] In the Day 1 assignment editor, leave the **Add test** / autograding tests area empty. - [ ] Save assignment. ## Phase 4: Create Day 2 Assignment @@ -41,12 +49,12 @@ Use this checklist when setting up a new cohort so you can run the full Classroo - [ ] Set deadline for your cohort. - [ ] Copy description from `day2-assignment-copy-paste.md` and paste into Classroom. -## Phase 5: Configure Day 2 Autograding +## Phase 5: Verify Day 2 Autograder Workflows (no Classroom configuration) + +Same model as Phase 3 -- the Day 2 checks (Challenges 10, 14, 16) run from the same template workflows. Do not enter any tests in the Classroom UI. -- [ ] Open `autograding-setup.md`. -- [ ] Add all Day 2 tests exactly as listed. -- [ ] Verify Day 2 test count is 6. -- [ ] Verify Day 2 point total is 75. +- [ ] Confirm the Day 2 autograder workflows are present in the template (`autograder-local-commit.yml`, `autograder-template.yml`, `autograder-capstone.yml`). +- [ ] In the Day 2 assignment editor, leave the **Add test** / autograding tests area empty. - [ ] Save assignment. ## Phase 6: Publish and Share @@ -83,14 +91,13 @@ scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access-Classroom - [ ] Confirm challenge issue exists after seeding. - [ ] Confirm Student Progression workflow run appears in Actions. -- [ ] Confirm one autograding failure scenario is detected correctly. -- [ ] Confirm one fixed rerun passes. +- [ ] Confirm at least one autograder workflow posts a fail comment for a known-bad state, and a pass comment after the fix is pushed. - [ ] Confirm peer simulation artifacts exist (2 issues + 1 PR). ## Phase 9: Cohort Readiness Sign-Off - [ ] Day 1 and Day 2 assignments published. - [ ] Invite links validated. -- [ ] Autograding configured and tested. +- [ ] Autograder workflows verified to post comments in a test student repo. - [ ] Seeding scripts verified against a test student repo. - [ ] Facilitator notes updated with links and fallback instructions. diff --git a/admin/qa-bundle/classroom/README.md b/admin/qa-bundle/classroom/README.md index 2638917..3278fa0 100644 --- a/admin/qa-bundle/classroom/README.md +++ b/admin/qa-bundle/classroom/README.md @@ -62,8 +62,6 @@ Day-2-only participants skip Assignment 1 entirely. They verify readiness using |---|---| | [assignment-day1-you-belong-here.md](assignment-day1-you-belong-here.md) | Assignment description for Day 1 (paste into Classroom UI) | | [assignment-day2-you-can-build-this.md](assignment-day2-you-can-build-this.md) | Assignment description for Day 2 (paste into Classroom UI) | -| [autograding-day1.json](autograding-day1.json) | Test definitions for Day 1 autograder | -| [autograding-day2.json](autograding-day2.json) | Test definitions for Day 2 autograder | | [grading-guide.md](grading-guide.md) | Facilitator rubric for all 21 challenges | | [roster-template.csv](roster-template.csv) | Starter CSV for importing student roster | | [student-progression.yml](student-progression.yml) | Reference copy of the progression bot workflow | @@ -155,7 +153,7 @@ From the classroom dashboard, click **New assignment** and fill in the assignmen Then complete the remaining fields: 1. **Assignment description:** Open [assignment-day1-you-belong-here.md](assignment-day1-you-belong-here.md), copy everything below the HTML metadata comment, and paste it into the description field -2. **Autograding tests:** Open [autograding-day1.json](autograding-day1.json) and add each test entry manually -- for each test in the JSON array, click **Add test**, set the **Test name**, **Run command**, **Comparison**, and **Points** to match the JSON values, and set timeout to 60 seconds per test unless otherwise specified +2. **Autograding tests:** Leave this section empty. Day 1 autograded checks (Challenges 2, 5, 6, 7) run as GitHub Actions workflows inside the template repo, so no Classroom test cases are required. See [admin/classroom/autograding-setup.md](../admin/classroom/autograding-setup.md) for the full list of workflows. 3. Click **Create assignment** -- this generates your Day 1 invite link ### What the student experiences (Day 1) @@ -192,7 +190,7 @@ Click **New assignment** again and fill in the settings: Then complete the remaining fields: 1. **Assignment description:** Use [assignment-day2-you-can-build-this.md](assignment-day2-you-can-build-this.md) -2. **Autograding tests:** Use [autograding-day2.json](autograding-day2.json) +2. **Autograding tests:** Leave this section empty. Day 2 autograded checks (Challenges 10, 14, 16) run as GitHub Actions workflows inside the template repo. See [admin/classroom/autograding-setup.md](../admin/classroom/autograding-setup.md). 3. Click **Create assignment** -- this generates your Day 2 invite link ### What the student experiences (Day 2) @@ -285,15 +283,15 @@ scripts/classroom/Start-MergeConflictChallenge.ps1 -Repository Community-Access- The script changes the same TODO area on `main`, which should cause the student's pull request to report a merge conflict if they edited that TODO on their branch. -### Autograding verification +### Autograder workflow verification -To test specific autograding checks: +All autograded checks now run as GitHub Actions workflows inside each student repo (not as Classroom test cases). To verify they work: 1. In the test student repo, create a branch and make a change that should pass a check 2. Open a PR -3. Go to the **Actions** tab and verify the autograding workflow ran -4. Check the workflow output -- each test should report pass or fail correctly -5. Try a change that should fail a check and verify it catches the problem +3. Go to the **Actions** tab and verify the relevant `autograder-*` workflow ran +4. On the PR (or relevant issue) confirm a comment was posted reporting pass or fail +5. Push a change that should fail a check and verify the comment updates in place ### Aria verification @@ -323,7 +321,7 @@ To test specific autograding checks: |---|---| | "I cannot find the invite link" | Reshare the link; post it in the workshop chat channel | | "My next challenge did not appear" | The student may not have closed the previous issue; check their Issues tab | -| "Autograding says I failed" | Check the workflow output; often a formatting issue; use it as a teaching moment | +| "The autograder bot says I failed" | Open the Actions tab in the student repo and read the failing `autograder-*` workflow log; the bot comment links to the run | | "I do not see the feedback PR" | It appears after the first push; have them make any commit and push | | "Aria did not comment on my PR" | Check the Actions tab in the student repo; workflows may need to be enabled | | "Assignment not showing my work" | Student may have pushed to the wrong branch; check their repo's branches | diff --git a/admin/qa-bundle/classroom/assignment-day1-you-belong-here.md b/admin/qa-bundle/classroom/assignment-day1-you-belong-here.md index b8f9710..5d414c9 100644 --- a/admin/qa-bundle/classroom/assignment-day1-you-belong-here.md +++ b/admin/qa-bundle/classroom/assignment-day1-you-belong-here.md @@ -6,7 +6,7 @@ Grant admin access: No Deadline: [Set per cohort - one week after Day 1] Group assignment: No (individual) Enable feedback pull requests: Yes -Autograding: See autograding-day1.json +Autograding: None to configure in the Classroom UI. Automated checks run as GitHub Actions workflows inside the template repo. See admin/classroom/autograding-setup.md. Supported editor: Browser, GitHub Desktop, CLI --> @@ -44,16 +44,16 @@ Complete these challenges in order. Each one builds on the previous. When you cl | 8. The Culture Layer | Reflect on community norms and communication | [Chapter 8](https://github.com/Community-Access/git-going-with-github/blob/main/docs/08-open-source-culture.md) | | 9. Merge Day | Get your PR reviewed, approved, and merged | [Chapter 10](https://github.com/Community-Access/git-going-with-github/blob/main/docs/10-notifications-and-day-1-close.md) | -## Autograded Challenges +## Automated Checks -Challenges 2, 5, 6, and 7 have automated checks that run when you push or open a PR: +Challenges 2, 5, 6, and 7 have automated checks that run as GitHub Actions inside your repo: - **Challenge 2:** Verifies you have filed at least one issue - **Challenge 5:** Verifies at least one commit exists on a non-default branch - **Challenge 6:** Verifies your PR body contains `Closes`, `Fixes`, or `Resolves` - **Challenge 7:** Verifies no merge conflict markers remain in `docs/` -The autograder posts feedback as a PR comment. If a check fails, read the feedback and push an update. +Each check posts a single comment on the relevant issue or pull request and updates it whenever you push a new change. If a check fails, read the comment and push an update. ## Evidence diff --git a/admin/qa-bundle/classroom/assignment-day2-you-can-build-this.md b/admin/qa-bundle/classroom/assignment-day2-you-can-build-this.md index 3252487..b278330 100644 --- a/admin/qa-bundle/classroom/assignment-day2-you-can-build-this.md +++ b/admin/qa-bundle/classroom/assignment-day2-you-can-build-this.md @@ -6,7 +6,7 @@ Grant admin access: No Deadline: [Set per cohort - one week after Day 2] Group assignment: No (individual) Enable feedback pull requests: Yes -Autograding: See autograding-day2.json +Autograding: None to configure in the Classroom UI. Automated checks run as GitHub Actions workflows inside the template repo. See admin/classroom/autograding-setup.md. Supported editor: VS Code (required for Day 2), GitHub Desktop, CLI --> @@ -47,15 +47,15 @@ Complete these challenges in order. Each one builds on the previous. The live ag | 15. Meet the Agents | Explore and run agents from the accessibility-agents repo | [Chapter 19](https://github.com/Community-Access/git-going-with-github/blob/main/docs/19-accessibility-agents.md) | | 16. Build Your Agent (Capstone) | Design and submit an original agent with responsibilities and guardrails | [Chapter 20](https://github.com/Community-Access/git-going-with-github/blob/main/docs/20-build-your-agent.md) | -## Autograded Challenges +## Automated Checks -Challenges 10, 14, and 16 have automated checks that run when you open a PR: +Challenges 10, 14, and 16 have automated checks that run as GitHub Actions inside your repo: - **Challenge 10:** Verifies at least one commit exists on a non-default branch - **Challenge 14:** Verifies your YAML template has required `name` and `description` fields - **Challenge 16:** Verifies your agent file has valid frontmatter, responsibilities, and guardrails -The autograder posts feedback as a PR comment. If a check fails, read the feedback and push an update. +Each check posts a single comment on the relevant pull request and updates it whenever you push a new change. If a check fails, read the comment and push an update. ## Evidence diff --git a/admin/qa-bundle/classroom/grading-guide.md b/admin/qa-bundle/classroom/grading-guide.md index a133550..f218f61 100644 --- a/admin/qa-bundle/classroom/grading-guide.md +++ b/admin/qa-bundle/classroom/grading-guide.md @@ -12,7 +12,7 @@ This is a learning workshop, not a competitive course. The grading system measur ## Automated Checks -The autograding JSON files define automated tests that run on student PRs. These check for: +Automated checks run as GitHub Actions workflows shipped inside each student repo (from `Community-Access/learning-room-template`). They check for: - Existence of files, branches, and commits - Presence of required fields in templates @@ -20,12 +20,12 @@ The autograding JSON files define automated tests that run on student PRs. These Automated checks handle the objective criteria. Facilitator judgment handles everything else. -**What is auto-checked today** (see [autograding-day1.json](autograding-day1.json) and [autograding-day2.json](autograding-day2.json)): +**What is auto-checked today** (see workflow files under `.github/workflows/autograder-*.yml` in the template repo, and [admin/classroom/autograding-setup.md](../admin/classroom/autograding-setup.md) for the full mapping): - Day 1: Challenges **2, 5, 6, 7** (issue filed, commit on branch, PR with `Closes/Fixes/Resolves`, no conflict markers) - Day 2: Challenges **10, 14, 16** (local commit on branch, custom issue template with `name`/`description`, agent file with frontmatter and required sections) -The `(auto)` tag in the per-challenge tables below marks rows where the autograder will post pass/fail results as a PR comment. All other rows require facilitator review. +The `(auto)` tag in the per-challenge tables below marks rows where an autograder workflow will post pass/fail results as an issue or PR comment. All other rows require facilitator review. ## Per-Challenge Grading diff --git a/admin/qa-bundle/scripts/classroom/Test-LearningRoomTemplate.ps1 b/admin/qa-bundle/scripts/classroom/Test-LearningRoomTemplate.ps1 index 8ebc6d6..ee2f2ed 100644 --- a/admin/qa-bundle/scripts/classroom/Test-LearningRoomTemplate.ps1 +++ b/admin/qa-bundle/scripts/classroom/Test-LearningRoomTemplate.ps1 @@ -59,7 +59,23 @@ try { Wait-ForRepositoryContent -Repository $smoke Write-Host "Checking expected template files..." - Invoke-CheckedCommand gh @('api', "repos/$smoke/contents/.github/workflows/student-progression.yml") + $requiredWorkflows = @( + 'pr-validation-bot.yml', + 'content-validation.yml', + 'student-progression.yml', + 'skills-progression.yml', + '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' + ) + foreach ($wf in $requiredWorkflows) { + Invoke-CheckedCommand gh @('api', "repos/$smoke/contents/.github/workflows/$wf") + } Invoke-CheckedCommand gh @('api', "repos/$smoke/contents/.github/ISSUE_TEMPLATE/challenge-01-find-your-way.yml") Invoke-CheckedCommand gh @('api', "repos/$smoke/contents/.github/scripts/challenge-progression.js") diff --git a/classroom/README.md b/classroom/README.md index 2638917..3278fa0 100644 --- a/classroom/README.md +++ b/classroom/README.md @@ -62,8 +62,6 @@ Day-2-only participants skip Assignment 1 entirely. They verify readiness using |---|---| | [assignment-day1-you-belong-here.md](assignment-day1-you-belong-here.md) | Assignment description for Day 1 (paste into Classroom UI) | | [assignment-day2-you-can-build-this.md](assignment-day2-you-can-build-this.md) | Assignment description for Day 2 (paste into Classroom UI) | -| [autograding-day1.json](autograding-day1.json) | Test definitions for Day 1 autograder | -| [autograding-day2.json](autograding-day2.json) | Test definitions for Day 2 autograder | | [grading-guide.md](grading-guide.md) | Facilitator rubric for all 21 challenges | | [roster-template.csv](roster-template.csv) | Starter CSV for importing student roster | | [student-progression.yml](student-progression.yml) | Reference copy of the progression bot workflow | @@ -155,7 +153,7 @@ From the classroom dashboard, click **New assignment** and fill in the assignmen Then complete the remaining fields: 1. **Assignment description:** Open [assignment-day1-you-belong-here.md](assignment-day1-you-belong-here.md), copy everything below the HTML metadata comment, and paste it into the description field -2. **Autograding tests:** Open [autograding-day1.json](autograding-day1.json) and add each test entry manually -- for each test in the JSON array, click **Add test**, set the **Test name**, **Run command**, **Comparison**, and **Points** to match the JSON values, and set timeout to 60 seconds per test unless otherwise specified +2. **Autograding tests:** Leave this section empty. Day 1 autograded checks (Challenges 2, 5, 6, 7) run as GitHub Actions workflows inside the template repo, so no Classroom test cases are required. See [admin/classroom/autograding-setup.md](../admin/classroom/autograding-setup.md) for the full list of workflows. 3. Click **Create assignment** -- this generates your Day 1 invite link ### What the student experiences (Day 1) @@ -192,7 +190,7 @@ Click **New assignment** again and fill in the settings: Then complete the remaining fields: 1. **Assignment description:** Use [assignment-day2-you-can-build-this.md](assignment-day2-you-can-build-this.md) -2. **Autograding tests:** Use [autograding-day2.json](autograding-day2.json) +2. **Autograding tests:** Leave this section empty. Day 2 autograded checks (Challenges 10, 14, 16) run as GitHub Actions workflows inside the template repo. See [admin/classroom/autograding-setup.md](../admin/classroom/autograding-setup.md). 3. Click **Create assignment** -- this generates your Day 2 invite link ### What the student experiences (Day 2) @@ -285,15 +283,15 @@ scripts/classroom/Start-MergeConflictChallenge.ps1 -Repository Community-Access- The script changes the same TODO area on `main`, which should cause the student's pull request to report a merge conflict if they edited that TODO on their branch. -### Autograding verification +### Autograder workflow verification -To test specific autograding checks: +All autograded checks now run as GitHub Actions workflows inside each student repo (not as Classroom test cases). To verify they work: 1. In the test student repo, create a branch and make a change that should pass a check 2. Open a PR -3. Go to the **Actions** tab and verify the autograding workflow ran -4. Check the workflow output -- each test should report pass or fail correctly -5. Try a change that should fail a check and verify it catches the problem +3. Go to the **Actions** tab and verify the relevant `autograder-*` workflow ran +4. On the PR (or relevant issue) confirm a comment was posted reporting pass or fail +5. Push a change that should fail a check and verify the comment updates in place ### Aria verification @@ -323,7 +321,7 @@ To test specific autograding checks: |---|---| | "I cannot find the invite link" | Reshare the link; post it in the workshop chat channel | | "My next challenge did not appear" | The student may not have closed the previous issue; check their Issues tab | -| "Autograding says I failed" | Check the workflow output; often a formatting issue; use it as a teaching moment | +| "The autograder bot says I failed" | Open the Actions tab in the student repo and read the failing `autograder-*` workflow log; the bot comment links to the run | | "I do not see the feedback PR" | It appears after the first push; have them make any commit and push | | "Aria did not comment on my PR" | Check the Actions tab in the student repo; workflows may need to be enabled | | "Assignment not showing my work" | Student may have pushed to the wrong branch; check their repo's branches | diff --git a/classroom/assignment-day1-you-belong-here.md b/classroom/assignment-day1-you-belong-here.md index b8f9710..5d414c9 100644 --- a/classroom/assignment-day1-you-belong-here.md +++ b/classroom/assignment-day1-you-belong-here.md @@ -6,7 +6,7 @@ Grant admin access: No Deadline: [Set per cohort - one week after Day 1] Group assignment: No (individual) Enable feedback pull requests: Yes -Autograding: See autograding-day1.json +Autograding: None to configure in the Classroom UI. Automated checks run as GitHub Actions workflows inside the template repo. See admin/classroom/autograding-setup.md. Supported editor: Browser, GitHub Desktop, CLI --> @@ -44,16 +44,16 @@ Complete these challenges in order. Each one builds on the previous. When you cl | 8. The Culture Layer | Reflect on community norms and communication | [Chapter 8](https://github.com/Community-Access/git-going-with-github/blob/main/docs/08-open-source-culture.md) | | 9. Merge Day | Get your PR reviewed, approved, and merged | [Chapter 10](https://github.com/Community-Access/git-going-with-github/blob/main/docs/10-notifications-and-day-1-close.md) | -## Autograded Challenges +## Automated Checks -Challenges 2, 5, 6, and 7 have automated checks that run when you push or open a PR: +Challenges 2, 5, 6, and 7 have automated checks that run as GitHub Actions inside your repo: - **Challenge 2:** Verifies you have filed at least one issue - **Challenge 5:** Verifies at least one commit exists on a non-default branch - **Challenge 6:** Verifies your PR body contains `Closes`, `Fixes`, or `Resolves` - **Challenge 7:** Verifies no merge conflict markers remain in `docs/` -The autograder posts feedback as a PR comment. If a check fails, read the feedback and push an update. +Each check posts a single comment on the relevant issue or pull request and updates it whenever you push a new change. If a check fails, read the comment and push an update. ## Evidence diff --git a/classroom/assignment-day2-you-can-build-this.md b/classroom/assignment-day2-you-can-build-this.md index 3252487..b278330 100644 --- a/classroom/assignment-day2-you-can-build-this.md +++ b/classroom/assignment-day2-you-can-build-this.md @@ -6,7 +6,7 @@ Grant admin access: No Deadline: [Set per cohort - one week after Day 2] Group assignment: No (individual) Enable feedback pull requests: Yes -Autograding: See autograding-day2.json +Autograding: None to configure in the Classroom UI. Automated checks run as GitHub Actions workflows inside the template repo. See admin/classroom/autograding-setup.md. Supported editor: VS Code (required for Day 2), GitHub Desktop, CLI --> @@ -47,15 +47,15 @@ Complete these challenges in order. Each one builds on the previous. The live ag | 15. Meet the Agents | Explore and run agents from the accessibility-agents repo | [Chapter 19](https://github.com/Community-Access/git-going-with-github/blob/main/docs/19-accessibility-agents.md) | | 16. Build Your Agent (Capstone) | Design and submit an original agent with responsibilities and guardrails | [Chapter 20](https://github.com/Community-Access/git-going-with-github/blob/main/docs/20-build-your-agent.md) | -## Autograded Challenges +## Automated Checks -Challenges 10, 14, and 16 have automated checks that run when you open a PR: +Challenges 10, 14, and 16 have automated checks that run as GitHub Actions inside your repo: - **Challenge 10:** Verifies at least one commit exists on a non-default branch - **Challenge 14:** Verifies your YAML template has required `name` and `description` fields - **Challenge 16:** Verifies your agent file has valid frontmatter, responsibilities, and guardrails -The autograder posts feedback as a PR comment. If a check fails, read the feedback and push an update. +Each check posts a single comment on the relevant pull request and updates it whenever you push a new change. If a check fails, read the comment and push an update. ## Evidence diff --git a/classroom/autograding-day1.json b/classroom/autograding-day1.json deleted file mode 100644 index 5c5fa77..0000000 --- a/classroom/autograding-day1.json +++ /dev/null @@ -1,42 +0,0 @@ -[ - { - "test_name": "Challenge 2: Issue Filed", - "setup": "", - "run": "gh issue list --repo $GITHUB_REPOSITORY --author $GITHUB_ACTOR --state all --json number --jq 'length' | xargs test 0 -lt", - "input": "", - "expected_output": "", - "comparison": "exact", - "timeout": 10, - "points": 10 - }, - { - "test_name": "Challenge 5: Commit Exists", - "setup": "", - "run": "git log --oneline --all --author=$GITHUB_ACTOR | head -1 | grep -q '.'", - "input": "", - "expected_output": "", - "comparison": "exact", - "timeout": 10, - "points": 10 - }, - { - "test_name": "Challenge 6: PR with Issue Link", - "setup": "", - "run": "gh pr list --repo $GITHUB_REPOSITORY --author $GITHUB_ACTOR --state all --json body --jq '.[0].body' | grep -iq 'closes\\|fixes\\|resolves'", - "input": "", - "expected_output": "", - "comparison": "exact", - "timeout": 10, - "points": 15 - }, - { - "test_name": "Challenge 7: No Conflict Markers", - "setup": "", - "run": "! grep -rn '<<<<<<< \\|======= \\|>>>>>>> ' docs/ 2>/dev/null", - "input": "", - "expected_output": "", - "comparison": "exact", - "timeout": 10, - "points": 15 - } -] diff --git a/classroom/autograding-day2.json b/classroom/autograding-day2.json deleted file mode 100644 index ac6d3b5..0000000 --- a/classroom/autograding-day2.json +++ /dev/null @@ -1,62 +0,0 @@ -[ - { - "test_name": "Challenge 10: Go Local - Commit on Branch", - "setup": "", - "run": "git log --oneline origin/main..HEAD 2>/dev/null | head -1 | grep -q '.' || git branch -r --list 'origin/*' | grep -v main | head -1 | xargs -I{} git log --oneline origin/main..{} | head -1 | grep -q '.'", - "input": "", - "expected_output": "", - "comparison": "exact", - "timeout": 10, - "points": 15 - }, - { - "test_name": "Challenge 14: Template Remix - Custom Issue Template Exists", - "setup": "", - "run": "find .github/ISSUE_TEMPLATE -name '*.yml' ! -name 'challenge-*.yml' ! -name 'bonus-*.yml' ! -name 'config.yml' 2>/dev/null | head -1 | grep -q '.'", - "input": "", - "expected_output": "", - "comparison": "exact", - "timeout": 10, - "points": 15 - }, - { - "test_name": "Challenge 14: Template Remix - Template Has Required Fields", - "setup": "", - "run": "TEMPLATE=$(find .github/ISSUE_TEMPLATE -name '*.yml' ! -name 'challenge-*.yml' ! -name 'bonus-*.yml' ! -name 'config.yml' 2>/dev/null | head -1); grep -q '^name:' \"$TEMPLATE\" && grep -q '^description:' \"$TEMPLATE\"", - "input": "", - "expected_output": "", - "comparison": "exact", - "timeout": 10, - "points": 10 - }, - { - "test_name": "Challenge 16: Build Your Agent - Agent File Exists", - "setup": "", - "run": "find agents community-agents -name '*.md' 2>/dev/null | head -1 | grep -q '.'", - "input": "", - "expected_output": "", - "comparison": "exact", - "timeout": 10, - "points": 10 - }, - { - "test_name": "Challenge 16: Build Your Agent - Agent Has Frontmatter", - "setup": "", - "run": "AGENT=$(find agents community-agents -name '*.md' 2>/dev/null | head -1); head -1 \"$AGENT\" | grep -q '^---'", - "input": "", - "expected_output": "", - "comparison": "exact", - "timeout": 10, - "points": 10 - }, - { - "test_name": "Challenge 16: Build Your Agent - Agent Has Responsibilities and Guardrails", - "setup": "", - "run": "AGENT=$(find agents community-agents -name '*.md' 2>/dev/null | head -1); grep -qi '## responsibilities\\|## what this agent does' \"$AGENT\" && grep -qi '## guardrails\\|## limitations\\|## boundaries' \"$AGENT\"", - "input": "", - "expected_output": "", - "comparison": "exact", - "timeout": 10, - "points": 15 - } -] diff --git a/classroom/grading-guide.md b/classroom/grading-guide.md index a133550..f218f61 100644 --- a/classroom/grading-guide.md +++ b/classroom/grading-guide.md @@ -12,7 +12,7 @@ This is a learning workshop, not a competitive course. The grading system measur ## Automated Checks -The autograding JSON files define automated tests that run on student PRs. These check for: +Automated checks run as GitHub Actions workflows shipped inside each student repo (from `Community-Access/learning-room-template`). They check for: - Existence of files, branches, and commits - Presence of required fields in templates @@ -20,12 +20,12 @@ The autograding JSON files define automated tests that run on student PRs. These Automated checks handle the objective criteria. Facilitator judgment handles everything else. -**What is auto-checked today** (see [autograding-day1.json](autograding-day1.json) and [autograding-day2.json](autograding-day2.json)): +**What is auto-checked today** (see workflow files under `.github/workflows/autograder-*.yml` in the template repo, and [admin/classroom/autograding-setup.md](../admin/classroom/autograding-setup.md) for the full mapping): - Day 1: Challenges **2, 5, 6, 7** (issue filed, commit on branch, PR with `Closes/Fixes/Resolves`, no conflict markers) - Day 2: Challenges **10, 14, 16** (local commit on branch, custom issue template with `name`/`description`, agent file with frontmatter and required sections) -The `(auto)` tag in the per-challenge tables below marks rows where the autograder will post pass/fail results as a PR comment. All other rows require facilitator review. +The `(auto)` tag in the per-challenge tables below marks rows where an autograder workflow will post pass/fail results as an issue or PR comment. All other rows require facilitator review. ## Per-Challenge Grading diff --git a/scripts/classroom/Test-LearningRoomTemplate.ps1 b/scripts/classroom/Test-LearningRoomTemplate.ps1 index 8ebc6d6..ee2f2ed 100644 --- a/scripts/classroom/Test-LearningRoomTemplate.ps1 +++ b/scripts/classroom/Test-LearningRoomTemplate.ps1 @@ -59,7 +59,23 @@ try { Wait-ForRepositoryContent -Repository $smoke Write-Host "Checking expected template files..." - Invoke-CheckedCommand gh @('api', "repos/$smoke/contents/.github/workflows/student-progression.yml") + $requiredWorkflows = @( + 'pr-validation-bot.yml', + 'content-validation.yml', + 'student-progression.yml', + 'skills-progression.yml', + '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' + ) + foreach ($wf in $requiredWorkflows) { + Invoke-CheckedCommand gh @('api', "repos/$smoke/contents/.github/workflows/$wf") + } Invoke-CheckedCommand gh @('api', "repos/$smoke/contents/.github/ISSUE_TEMPLATE/challenge-01-find-your-way.yml") Invoke-CheckedCommand gh @('api', "repos/$smoke/contents/.github/scripts/challenge-progression.js") From 56862e1cc19c849b8e119b5b0a2fe3fb42ab4b07 Mon Sep 17 00:00:00 2001 From: GitHub Workshop Bot Date: Tue, 12 May 2026 12:32:20 -0700 Subject: [PATCH 2/4] feat(autograder): add Challenge 2/5/6 workflows and extend watchdog - Add autograder-issue-filed.yml: acknowledges first issue (Challenge 2) with a friendly comment and a count-based follow-up on later issues - Add autograder-branch-commit.yml: verifies at least one commit on a non-default branch (Challenge 5) on push events - Add autograder-pr-link.yml: verifies the PR body contains a closing keyword followed by an issue number (Challenge 6) - Extend autograder-watchdog.yml workflow_run listener and the in-job challengeMarkers array to cover Challenges 2, 5, and 6 alongside the existing 7, 10, 14, and 16 entries All three new workflows post deterministic, hard-coded English feedback as PR/issue comments (no AI, no Copilot subscription required) and use a marker-based update-in-place pattern so the comment thread stays readable for screen readers. --- .../workflows/autograder-branch-commit.yml | 136 ++++++++++++++++++ .../workflows/autograder-issue-filed.yml | 115 +++++++++++++++ .../.github/workflows/autograder-pr-link.yml | 133 +++++++++++++++++ .../.github/workflows/autograder-watchdog.yml | 6 + 4 files changed, 390 insertions(+) create mode 100644 learning-room/.github/workflows/autograder-branch-commit.yml create mode 100644 learning-room/.github/workflows/autograder-issue-filed.yml create mode 100644 learning-room/.github/workflows/autograder-pr-link.yml diff --git a/learning-room/.github/workflows/autograder-branch-commit.yml b/learning-room/.github/workflows/autograder-branch-commit.yml new file mode 100644 index 0000000..2705870 --- /dev/null +++ b/learning-room/.github/workflows/autograder-branch-commit.yml @@ -0,0 +1,136 @@ +name: "Challenge 5: Branch Commit Check" +# Validates that the student has at least one commit on a non-default branch. +# Replaces the GitHub Classroom autograding "test case" for Challenge 5 so the +# check still runs even when the Classroom UI cannot save test cases. + +on: + push: + branches-ignore: + - main + pull_request: + types: [opened, synchronize, reopened] + branches: + - main + +permissions: + contents: read + pull-requests: write + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + check-commit-on-branch: + name: Verify commit on non-default branch + runs-on: ubuntu-latest + + steps: + - name: Checkout full history + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Inspect branch and commits + id: check + run: | + if [ "${{ github.event_name }}" = "pull_request" ]; then + BRANCH="${{ github.head_ref }}" + COMMITS=$(git log --oneline origin/main..HEAD | wc -l) + else + BRANCH="${GITHUB_REF#refs/heads/}" + COMMITS=$(git log --oneline origin/main..HEAD 2>/dev/null | wc -l || echo 0) + fi + echo "branch=$BRANCH" >> "$GITHUB_OUTPUT" + echo "count=$COMMITS" >> "$GITHUB_OUTPUT" + if [ "$BRANCH" = "main" ]; then + echo "on_main=true" >> "$GITHUB_OUTPUT" + else + echo "on_main=false" >> "$GITHUB_OUTPUT" + fi + + - name: Post result on PR + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const onMain = '${{ steps.check.outputs.on_main }}' === 'true'; + const count = parseInt('${{ steps.check.outputs.count }}', 10); + const branch = '${{ steps.check.outputs.branch }}'; + let body; + if (onMain) { + body = [ + '## Challenge 5: PR is from the main branch', + '', + 'This challenge asks you to create a **feature branch** and commit your edit there. ', + 'Your PR appears to come from main itself.', + '', + 'See [Chapter 4: The Learning Room](https://github.com/Community-Access/git-going-with-github/blob/main/docs/04-the-learning-room.md) for branching instructions.' + ].join('\n'); + } else if (count === 0) { + body = [ + '## Challenge 5: No new commits on this branch', + '', + 'Branch `' + branch + '` has no commits ahead of main. ', + 'Edit a file, commit with a clear message, and push again.' + ].join('\n'); + } else { + body = [ + '## Challenge 5: Branch commit verified!', + '', + 'Found ' + count + ' commit(s) on branch `' + branch + '`. ', + 'You committed your work on a feature branch -- exactly the workflow real contributors use.' + ].join('\n'); + } + const MARKER = '## Challenge 5:'; + try { + const { data: comments } = await github.rest.issues.listComments({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number + }); + const existing = comments.find(c => c.user.type === 'Bot' && c.body.includes(MARKER)); + if (existing) { + await github.rest.issues.updateComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: existing.id, + body + }); + } else { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body + }); + } + } catch (error) { + console.error('Could not post Challenge 5 result:', error.message); + } + + - name: Post workflow error notice + if: failure() && github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const MARKER = '## Challenge 5:'; + const body = [ + '## Challenge 5: Check could not complete', + '', + 'The automated branch commit check ran into an unexpected error. Your work is not affected.', + 'Keep going and ask your facilitator, or mention @facilitator in a comment.', + '', + '---', + '*Automated message from Learning Room Bot.*' + ].join('\n'); + try { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body + }); + } catch (err) { + console.error('Could not post error notice:', err.message); + } diff --git a/learning-room/.github/workflows/autograder-issue-filed.yml b/learning-room/.github/workflows/autograder-issue-filed.yml new file mode 100644 index 0000000..79397c7 --- /dev/null +++ b/learning-room/.github/workflows/autograder-issue-filed.yml @@ -0,0 +1,115 @@ +name: "Challenge 2: Issue Filed Check" +# Validates that the student has filed at least one issue in their Learning Room. +# Replaces the GitHub Classroom autograding "test case" for Challenge 2 so the +# check still runs even when the Classroom UI cannot save test cases. + +on: + issues: + types: [opened] + workflow_dispatch: + +permissions: + contents: read + issues: write + +concurrency: + group: ${{ github.workflow }}-${{ github.event.issue.number || github.run_id }} + cancel-in-progress: true + +jobs: + acknowledge-issue: + name: Acknowledge first issue + runs-on: ubuntu-latest + # Only react when the author is the student (not a bot or facilitator pre-seeded issue). + if: github.event_name == 'workflow_dispatch' || (github.event.issue.user.login == github.actor && github.event.issue.user.type == 'User') + + steps: + - name: Count issues authored by this student + id: count + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + COUNT=$(gh issue list \ + --repo "$GITHUB_REPOSITORY" \ + --author "$GITHUB_ACTOR" \ + --state all \ + --json number \ + --jq 'length') + echo "count=$COUNT" >> "$GITHUB_OUTPUT" + + - name: Post acknowledgement + if: github.event_name == 'issues' + uses: actions/github-script@v7 + with: + script: | + const count = parseInt('${{ steps.count.outputs.count }}', 10); + const isFirst = count === 1; + const body = isFirst + ? [ + '## Challenge 2: First issue filed!', + '', + 'Nice work -- this is the first issue you have opened in your Learning Room. ', + 'Filing issues is how contributors describe work that needs to happen.', + '', + 'Next up: try @mentioning a teammate or `@aria-bot` in a comment (Challenge 3), ', + 'then move on to branching and committing.', + '', + 'See [Chapter 5: Working with Issues](https://github.com/Community-Access/git-going-with-github/blob/main/docs/05-working-with-issues.md).' + ].join('\n') + : [ + '## Challenge 2: Another issue filed', + '', + 'You have now filed ' + count + ' issues in this Learning Room. Keep going!' + ].join('\n'); + const MARKER = '## Challenge 2:'; + try { + const { data: comments } = await github.rest.issues.listComments({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number + }); + const existing = comments.find(c => c.user.type === 'Bot' && c.body.includes(MARKER)); + if (existing) { + await github.rest.issues.updateComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: existing.id, + body + }); + } else { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body + }); + } + } catch (error) { + console.error('Could not post Challenge 2 acknowledgement:', error.message); + } + + - name: Post workflow error notice + if: failure() && github.event_name == 'issues' + uses: actions/github-script@v7 + with: + script: | + const MARKER = '## Challenge 2:'; + const body = [ + '## Challenge 2: Check could not complete', + '', + 'The automated issue check ran into an unexpected error. Your work is not affected.', + 'Keep going and ask your facilitator, or mention @facilitator in a comment.', + '', + '---', + '*Automated message from Learning Room Bot.*' + ].join('\n'); + try { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body + }); + } catch (err) { + console.error('Could not post error notice:', err.message); + } diff --git a/learning-room/.github/workflows/autograder-pr-link.yml b/learning-room/.github/workflows/autograder-pr-link.yml new file mode 100644 index 0000000..74122ef --- /dev/null +++ b/learning-room/.github/workflows/autograder-pr-link.yml @@ -0,0 +1,133 @@ +name: "Challenge 6: PR Linked to Issue Check" +# Validates that the student's PR body contains a closing keyword +# (Closes/Fixes/Resolves) so the PR is linked to an issue. +# Replaces the GitHub Classroom autograding "test case" for Challenge 6 so the +# check still runs even when the Classroom UI cannot save test cases. + +on: + pull_request: + types: [opened, edited, synchronize, reopened] + branches: + - main + +permissions: + contents: read + pull-requests: write + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + check-pr-link: + name: Verify PR closes an issue + runs-on: ubuntu-latest + + steps: + - name: Inspect PR body + id: check + uses: actions/github-script@v7 + with: + script: | + const body = context.payload.pull_request.body || ''; + // Match GitHub's accepted closing keywords (case-insensitive), + // followed by a #N reference. Avoid matching the word inside other words. + const pattern = /\b(closes|closed|close|fixes|fixed|fix|resolves|resolved|resolve)\b\s*#\d+/i; + const linked = pattern.test(body); + core.setOutput('linked', linked ? 'true' : 'false'); + core.setOutput('empty', body.trim().length === 0 ? 'true' : 'false'); + + - name: Post result + if: always() + uses: actions/github-script@v7 + with: + script: | + const linked = '${{ steps.check.outputs.linked }}' === 'true'; + const empty = '${{ steps.check.outputs.empty }}' === 'true'; + let body; + if (linked) { + body = [ + '## Challenge 6: PR linked to an issue!', + '', + 'Your PR description includes a closing keyword (`Closes`, `Fixes`, or `Resolves`) ', + 'followed by an issue number. When this PR merges, GitHub will close that issue automatically.', + '', + 'This is the habit professional contributors use on every PR.' + ].join('\n'); + } else if (empty) { + body = [ + '## Challenge 6: PR description is empty', + '', + 'Add a description to this PR that includes `Closes #N` (where `N` is your challenge issue number). ', + 'You can edit the PR description from the PR page.', + '', + 'See [Chapter 6: Working with Pull Requests](https://github.com/Community-Access/git-going-with-github/blob/main/docs/06-working-with-pull-requests.md).' + ].join('\n'); + } else { + body = [ + '## Challenge 6: No issue link found', + '', + 'Your PR description does not contain a closing keyword followed by an issue number. ', + 'Edit the description to include one of:', + '', + '- `Closes #N`', + '- `Fixes #N`', + '- `Resolves #N`', + '', + 'where `N` is the number of the issue this PR completes.', + '', + 'See [Chapter 6: Working with Pull Requests](https://github.com/Community-Access/git-going-with-github/blob/main/docs/06-working-with-pull-requests.md).' + ].join('\n'); + } + const MARKER = '## Challenge 6:'; + try { + const { data: comments } = await github.rest.issues.listComments({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number + }); + const existing = comments.find(c => c.user.type === 'Bot' && c.body.includes(MARKER)); + if (existing) { + await github.rest.issues.updateComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: existing.id, + body + }); + } else { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body + }); + } + } catch (error) { + console.error('Could not post Challenge 6 result:', error.message); + } + + - name: Post workflow error notice + if: failure() + uses: actions/github-script@v7 + with: + script: | + const MARKER = '## Challenge 6:'; + const body = [ + '## Challenge 6: Check could not complete', + '', + 'The automated PR-link check ran into an unexpected error. Your work is not affected.', + 'Keep going and ask your facilitator, or mention @facilitator in a comment.', + '', + '---', + '*Automated message from Learning Room Bot.*' + ].join('\n'); + try { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body + }); + } catch (err) { + console.error('Could not post error notice:', err.message); + } diff --git a/learning-room/.github/workflows/autograder-watchdog.yml b/learning-room/.github/workflows/autograder-watchdog.yml index e5e77a0..8202a96 100644 --- a/learning-room/.github/workflows/autograder-watchdog.yml +++ b/learning-room/.github/workflows/autograder-watchdog.yml @@ -8,6 +8,9 @@ name: Autograder Failure Watchdog on: workflow_run: workflows: + - "Challenge 2: Issue Filed Check" + - "Challenge 5: Branch Commit Check" + - "Challenge 6: PR Linked to Issue Check" - "Challenge 7: Merge Conflict Resolution Check" - "Challenge 10: Local Commit Check" - "Challenge 14: Issue Template Validation" @@ -55,6 +58,9 @@ jobs: }); const challengeMarkers = [ + '## Challenge 2:', + '## Challenge 5:', + '## Challenge 6:', '## Challenge 7:', '## Challenge 10:', '## Challenge 14:', From 6d39eb31e21cd925189c7248a584681c4182f15e Mon Sep 17 00:00:00 2001 From: GitHub Workshop Bot Date: Tue, 12 May 2026 12:32:45 -0700 Subject: [PATCH 3/4] build(html): regenerate static site to reflect autograding migration Regenerates html/ via 'npm run build:html' so the rendered pages and search-index.json match the corrected source markdown: - classroom/assignment-day{1,2}-*.html: drop the deprecated 'Autograding: See autograding-day{1,2}.json' metadata line - classroom/grading-guide.html, classroom/index.html: reflect the new workflow-based check list - admin/classroom/autograding-setup.html: now describes the workflow-based flow and watchdog fallback - admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html and qa-bundle copies: pick up the same edits - search-index.json: removes all stale 'autograding-day{1,2}.json' references from indexed bodies (the only remaining mentions are intentional historical references in autograding-setup.md) Generated by 'npm run build:html'. No hand-edits. --- html/GO-LIVE-QA-GUIDE.html | 11 +- html/README.html | 2 - html/REGISTER.html | 18 +- html/admin/CLASSROOM_INTEGRATION_GUIDE.html | 185 +++++++++++ html/admin/ENROLLMENT_SETUP_CHECKLIST.html | 291 ++++++++++++++++++ html/admin/FINE_GRAINED_TOKEN_SETUP.html | 110 +++++++ html/admin/GITHUB_CLASSROOM_ARCHITECTURE.html | 138 +++++++++ html/admin/IMPLEMENTATION_SUMMARY.html | 137 +++++++++ html/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html | 97 ++---- html/admin/QUICK_START_SETUP.html | 147 +++++++++ html/admin/REGISTRATION-ADMIN.html | 188 +++-------- html/admin/REGISTRATION-QUICKSTART.html | 39 +-- html/admin/classroom/autograding-setup.html | 265 +++++----------- html/admin/classroom/index.html | 14 +- .../classroom/live-facilitation-flow.html | 33 +- html/admin/qa-bundle/GO-LIVE-QA-GUIDE.html | 11 +- .../admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html | 97 ++---- .../admin/classroom/autograding-setup.html | 265 +++++----------- .../qa-bundle/admin/classroom/index.html | 14 +- .../classroom/live-facilitation-flow.html | 33 +- .../assignment-day1-you-belong-here.html | 8 +- .../assignment-day2-you-can-build-this.html | 8 +- .../qa-bundle/classroom/grading-guide.html | 6 +- html/admin/qa-bundle/classroom/index.html | 26 +- html/admin/qa-bundle/index.html | 2 - .../assignment-day1-you-belong-here.html | 8 +- .../assignment-day2-you-can-build-this.html | 8 +- html/classroom/grading-guide.html | 6 +- html/classroom/index.html | 26 +- html/search-index.json | 234 ++++++++------ 30 files changed, 1534 insertions(+), 893 deletions(-) create mode 100644 html/admin/CLASSROOM_INTEGRATION_GUIDE.html create mode 100644 html/admin/ENROLLMENT_SETUP_CHECKLIST.html create mode 100644 html/admin/FINE_GRAINED_TOKEN_SETUP.html create mode 100644 html/admin/GITHUB_CLASSROOM_ARCHITECTURE.html create mode 100644 html/admin/IMPLEMENTATION_SUMMARY.html create mode 100644 html/admin/QUICK_START_SETUP.html diff --git a/html/GO-LIVE-QA-GUIDE.html b/html/GO-LIVE-QA-GUIDE.html index 1505d4a..e9117f6 100644 --- a/html/GO-LIVE-QA-GUIDE.html +++ b/html/GO-LIVE-QA-GUIDE.html @@ -71,22 +71,25 @@

Release Decision

  • RSS feed validation passes for the current audio state.
  • Git diff whitespace check has no actual whitespace or conflict-marker errors.
  • Registration deployment gate completed (issue form template, workflow enablement, required labels, and optional classroom automation settings).
    • +
  • Registration comment flow is assignment-link based (no org invite dependency).
  • Support Hub is provisioned and publicly accessible at Community-Access/support.
  • Registration confirmation and help pathways route support requests to Support Hub issues/discussions.
  • Registration issue form template and labels are configured (workshop-registration.yml, registration, duplicate, waitlist).
  • Learning Room source has been synced to Community-Access/learning-room-template and merged to main (or validated as no-change).
  • Template smoke validation from Community-Access/learning-room-template succeeded before assignment publishing.
  • Template freshness proof confirms smoke repo content matches latest merged template sync changes.
    • -
  • Smoke repo confirms all required workflow files are present (PR validation, content validation, progression, skills progression, and all autograders).
    • +
  • 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 in enrollment issue 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.
  • Aria posts PR feedback on a test pull request.
  • Student Progression Bot creates the next challenge when a challenge issue is closed.
    • -
  • Autograding runs and reports results in GitHub Classroom.
    • +
  • 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.
    • @@ -235,7 +238,7 @@

    Day 1 Assignment

  • Create the Day 1 assignment using classroom/assignment-day1-you-belong-here.md.
  • Use private individual repositories.
  • Enable feedback pull requests.
    • -
  • Add every Day 1 autograding test from classroom/autograding-day1.json.
    • +
  • 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.
    • @@ -252,7 +255,7 @@

    Day 2 Assignment

  • Create the Day 2 assignment using classroom/assignment-day2-you-can-build-this.md.
  • Use private individual repositories.
  • Enable feedback pull requests.
    • -
  • Add every Day 2 autograding test from classroom/autograding-day2.json.
    • +
  • 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.
    • diff --git a/html/README.html b/html/README.html index 6041f14..72d8767 100644 --- a/html/README.html +++ b/html/README.html @@ -511,8 +511,6 @@

    This Repository's Structure

    │ ├── 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 diff --git a/html/REGISTER.html b/html/REGISTER.html index f19345e..360e2e0 100644 --- a/html/REGISTER.html +++ b/html/REGISTER.html @@ -62,6 +62,17 @@

    Student Opt-In

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

    Join the next GIT Going with GitHub cohort

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

    + +

    If you are new to GitHub or new to our workshop flow, start here.

    +
      +
    1. Open the beginner-friendly enrollment form.
      2. +
    2. Submit the six short questions.
      3. +
    3. Wait for the automation comment with your classroom join link.
      4. +
    +
    +

    Start Beginner Enrollment Form

    +
    +

    This does not replace legacy registration. Both flows remain available.

    @@ -83,7 +94,7 @@

    Join the next GIT Going with

    - +
    FormGitHub issue form with automated confirmation and waitlist handlingGitHub issue form with automated confirmation and beginner fast path

    Quick opt-in workflow

    @@ -95,11 +106,12 @@

    Quick opt-in workflow

    Start Student Opt-In Form

    +

    Legacy path (existing flow): this option remains unchanged and continues to work.

    What happens automatically

    • Duplicate submissions are handled automatically.
      • -
    • If capacity is available, your registration is confirmed.
      • -
    • If capacity is full, your issue is placed on the waitlist automatically.
      • +
    • Registration is currently unlimited.
      • +
    • Enrollment submissions are processed and public issue bodies are redacted after automation runs.

    Important note

    Registration issues are public because this repository is public.

    diff --git a/html/admin/CLASSROOM_INTEGRATION_GUIDE.html b/html/admin/CLASSROOM_INTEGRATION_GUIDE.html new file mode 100644 index 0000000..e187998 --- /dev/null +++ b/html/admin/CLASSROOM_INTEGRATION_GUIDE.html @@ -0,0 +1,185 @@ + + + + + + + GitHub Classroom Integration Guide - GIT Going with GitHub + + + + + + + + +
    +

    GitHub Classroom Integration Guide

    +

    This guide helps facilitators connect student enrollment data with GitHub Classroom assignments and dashboard triage.

    +

    Quick Start: Syncing Students to Classroom

    +

    1. Prepare Your Classroom Organization

    +
      +
    • Create a classroom organization (or use existing): https://classroom.github.com
      • +
    • Set up Day 1 and Day 2 assignments with your Classroom links
      • +
    • Add yourself and co-facilitators as org owners
      • +
    +

    2. Configure Repository Integration

    +

    Set these variables in the git-going-with-github repository settings:

    + + + + + + + + + + + + + + + + + + +
    VariableExamplePurpose
    CLASSROOM_DAY1_ASSIGNMENT_URLGitHub Classroom Day 1 assignment linkPosted to students after enrollment
    CLASSROOM_DAY2_ASSIGNMENT_URLGitHub Classroom Day 2 assignment linkPosted after Day 1 completion signal
    +

    3. Proficiency-Based Triage

    +

    When students enroll, the workflow automatically adds proficiency labels:

    +
      +
    • proficiency-beginner — New to GitHub or VS Code
      • +
    • proficiency-intermediate — Some experience
      • +
    • proficiency-advanced — Confident users
      • +
    +

    4. Viewing Enrollment Data

    + +

    Workflow: Enrollment → Team Assignment → Assignments

    +

    Day 0: Enrollment Opens

    +
      +
    • Students submit enrollment form
      • +
    • Workflow validates, redacts public issue, posts success comment with Day 1 assignment link
      • +
    • Student replies ack after confirming Day 1 access
      • +
    +

    Day 0-1: Facilitator Triage

    +
      +
    • Open enrollment issues with proficiency labels
      • +
    • For advanced proficiency students: consider pairing as peer mentors in team assignments
      • +
    • For beginner students: consider providing extra pre-workshop setup support
      • +
    +

    Day 1: Teams & Assignments

    +
      +
    • Create teams in classroom org (if using pair programming):
        +
      • Team: mentors (advanced proficiency students)
        • +
      • Team: learners (mixed proficiency for support)
        • +
      +
      • +
    • Students access Day 1 assignment via the link posted in their enrollment issue
      • +
    • Students reply day1-complete in the enrollment issue when they complete Day 1 milestone
      • +
    +

    Day 1-2: Track Progress

    +
      +
    • Monitor assignment submissions in GitHub Classroom
      • +
    • Identify students who haven't started Day 1
      • +
    • Re-reach out via Support Hub Issues
      • +
    +

    Day 2: Advanced Assignment

    +
      +
    • Day 2 assignment link is posted automatically after day1-complete signal (label or student comment)
      • +
    • Day 2 focuses on pair programming, code review, and open-source contribution
      • +
    +

    Troubleshooting

    +

    "Enrollment is temporarily unavailable"

    +
      +
    • Cause: PRIVATE_STUDENT_DATA_REPO or PRIVATE_STUDENT_DATA_TOKEN not configured
      • +
    • Fix: Follow section 2 (Configure Repository Integration) above
      • +
    +

    Student did not receive Day 2 release

    +
      +
    • Cause: No Day 1 completion signal found
      • +
    • Fix: Add day1-complete comment in enrollment issue or apply day2-eligible label
      • +
    +

    Can't find enrollment details

    +
      +
    • Location: Private repo → git-going-with-github-administration/issues
      • +
    • Search: Filter by label:intake to see all student intakes
      • +
    • Privacy: Full student PII (name, email, notes) visible only to org members with repo access
      • +
    +

    Exporting Student Roster

    +

    To export all enrolled students to a CSV (for import to a separate tool):

    +
      +
    1. Go to Workflow Runs
      2. +
    2. Click Run Workflow
      3. +
    3. Select export-classroom-intake job (if enabled)
      4. +
    4. Download artifact: classroom-intake-data → classroom-intake.csv
      5. +
    +

    Note: Public CSV export is disabled by default for privacy. To enable:

    +
      +
    • Set variable: ENABLE_PUBLIC_CLASSROOM_INTAKE_EXPORT = true
      • +
    • Then re-run the workflow
      • +
    +

    Need Help?

    +
      +
    • Technical: Open an issue in Support Hub
      • +
    • Best Practices: See FACILITATOR_GUIDE.md
      • +
    • Admin Access: Contact a repository maintainer for secret/variable updates
      • +
    + +
    + + + + diff --git a/html/admin/ENROLLMENT_SETUP_CHECKLIST.html b/html/admin/ENROLLMENT_SETUP_CHECKLIST.html new file mode 100644 index 0000000..619557b --- /dev/null +++ b/html/admin/ENROLLMENT_SETUP_CHECKLIST.html @@ -0,0 +1,291 @@ + + + + + + + Enrollment Setup & Configuration Checklist - GIT Going with GitHub + + + + + + + + +
    +

    Enrollment Setup & Configuration Checklist

    +

    Use this checklist to complete the GitHub Classroom integration setup for a new cohort.

    +

    Pre-Enrollment: GitHub Classroom Setup

    +
      +

    • +Confirm classroom access in GitHub Classroom

      + +
      • +

    • +Create GitHub Classroom assignments:

      +
        +
      • Day 1 assignment (e.g., "Day 1: You Belong Here")
        • +
      • Day 2 assignment (e.g., "Day 2: You Can Build This")
        • +
      • Get the assignment invitation link from Classroom UI for each
        • +
      +
      • +

    • +Decide your Day 1 completion signal for Day 2 release:

      +
        +
      • Label-based (day1-complete or day2-eligible)
        • +
      • Student comment-based (day1-complete in enrollment issue)
        • +
      +
      • +
    +

    GitHub Repository Configuration

    +

    Repository Variables

    +

    In Community-Access/git-going-with-github Settings → Variables:

    +
      +

    • +CLASSROOM_DAY1_ASSIGNMENT_URL

      +
        +
      • Value: Day 1 Classroom assignment invitation link
        • +
      • Purpose: Posted to students after enrollment; required for Day 1 start
        • +
      +
      • +

    • +CLASSROOM_DAY2_ASSIGNMENT_URL

      +
        +
      • Value: Day 2 Classroom assignment invitation link
        • +
      • Purpose: Posted to students after Day 1 completion confirmation
        • +
      +
      • +

    • +PRIVATE_STUDENT_DATA_REPO

      +
        +
      • Value: Community-Access/git-going-with-github-administration
        • +
      • Status: Already set ✓ (do not change)
        • +
      +
      • +

    • +ENABLE_PUBLIC_CLASSROOM_INTAKE_EXPORT

      +
        +
      • Value: false
        • +
      • Status: Already set ✓ (do not change unless you want public CSV export)
        • +
      +
      • +

    • +ENABLE_PUBLIC_REGISTRATION_EXPORT (legacy)

      +
        +
      • Value: false
        • +
      • Status: Already set ✓ (do not change unless you want public legacy export)
        • +
      +
      • +
    +

    Repository Secrets

    +

    In Community-Access/git-going-with-github Settings → Secrets:

    +
      +
    • PRIVATE_STUDENT_DATA_TOKEN
        +
      • Status: Already set ✓ (created at initial setup)
        • +
      • Validity: Verify token has not expired
        • +
      • Action: Renew if integration stops working
        • +
      +
      • +
    +

    Private Admin Repository Setup

    +

    In Community-Access/git-going-with-github-administration:

    +
      +
    • Verify repo is private
      • +
    • Add facilitators as maintainers
      • +
    • Verify labels exist:
        +
      • intake
        • +
      • classroom-enrollment
        • +
      +
      • +
    • Create any additional labels for triage:
        +
      • cohort-YYYY-MM (for filtering by cohort)
        • +
      • follow-up-needed
        • +
      • accessibility-request
        • +
      +
      • +
    +

    Pre-Workshop: Enrollment Window

    + +

    Workshop Day 0: Final Prep

    + +

    Workshop Day 1-2: Active Monitoring

    +
      +

    • +Track assignment submissions in GitHub Classroom

      +
        +
      • View: https://classroom.github.com → Your org → Assignments → Day 1
        • +
      • Identify students who haven't accepted invitation or started work
        • +
      +
      • +

    • +Re-engage non-starters:

      +
        +
      • File a support issue mentioning GitHub username
        • +
      • Direct to Support Hub
        • +
      • Offer 1:1 setup help if needed
        • +
      +
      • +

    • +Monitor private intake repo for flags:

      +
        +
      • Label issues: accessibility-request, follow-up-needed
        • +
      • Act on accommodations mentioned in course goals
        • +
      +
      • +
    +

    Post-Workshop: Data Archival

    +
      +

    • +Export final cohort roster:

      + +
      • +

    • +Tag private intakes by cohort:

      +
        +
      • Bulk-add cohort-YYYY-MM label to all intake issues
        • +
      • This helps future facilitators find historical data
        • +
      +
      • +

    • +Archive passwords/tokens:

      +
        +
      • Document which token was used (for audit trail)
        • +
      • Schedule token rotation for next cohort
        • +
      +
      • +
    +

    Troubleshooting Quick Reference

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ProblemCauseSolution
    "Enrollment is temporarily unavailable"Missing secrets/variablesCheck this checklist; verify all vars/secrets set
    Student cannot access assignmentInvite link mismatch or not signed inRe-copy assignment invite URL from Classroom and update variable
    Can't see private intakesPermission deniedVerify you're an org member of admin repo
    Proficiency labels not appearingWorkflow skippedCheck enrollment issue for errors; re-submit
    Assignments not posting to studentsMissing assignment URL variablesVerify CLASSROOM_DAY1_ASSIGNMENT_URL is set
    +
    +

    Last updated: 2026-05-12
    Owned by: Facilitator lead
    Version: 1.0

    + +
    + + + + diff --git a/html/admin/FINE_GRAINED_TOKEN_SETUP.html b/html/admin/FINE_GRAINED_TOKEN_SETUP.html new file mode 100644 index 0000000..2285eb6 --- /dev/null +++ b/html/admin/FINE_GRAINED_TOKEN_SETUP.html @@ -0,0 +1,110 @@ + + + + + + + Token and Variable Setup - GIT Going with GitHub + + + + + + + + +
    +

    Token and Variable Setup

    +

    This guide documents the current credential model for registration and dashboard automation.

    +

    Registration Flow Credentials

    +

    Registration no longer uses organization invitation tokens.

    +

    Required variables:

    +
      +
    • CLASSROOM_DAY1_ASSIGNMENT_URL
      • +
    • CLASSROOM_DAY2_ASSIGNMENT_URL
      • +
    +

    Required secret for private intake storage:

    +
      +
    • PRIVATE_STUDENT_DATA_TOKEN
      • +
    +

    Dashboard Flow Credential

    +

    instructor-dashboard-sync.yml writes progress snapshots to the private administration repository.

    +

    Required secret:

    +
      +
    • INSTRUCTOR_DASHBOARD_TOKEN
      • +
    +

    Recommended scope:

    +
      +
    • Repository issues read/write on the private administration repository only.
      • +
    +

    Verification Commands

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

    Expected registration-related output:

    +
      +
    • Variables include CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL.
      • +
    • Secrets include PRIVATE_STUDENT_DATA_TOKEN.
      • +
    • If dashboard sync is enabled, secrets include INSTRUCTOR_DASHBOARD_TOKEN.
      • +
    +

    Rotation Guidance

    +

    Rotate tokens at least once per cohort.

    +

    Rotation order:

    +
      +
    1. Create new token.
      2. +
    2. Update repository secret.
      3. +
    3. Run a smoke test workflow.
      4. +
    4. Revoke old token.
      5. +
    + +
    + + + + diff --git a/html/admin/GITHUB_CLASSROOM_ARCHITECTURE.html b/html/admin/GITHUB_CLASSROOM_ARCHITECTURE.html new file mode 100644 index 0000000..5cc37ba --- /dev/null +++ b/html/admin/GITHUB_CLASSROOM_ARCHITECTURE.html @@ -0,0 +1,138 @@ + + + + + + + GitHub Classroom Integration Architecture - GIT Going with GitHub + + + + + + + + +
    +

    GitHub Classroom Integration Architecture

    +

    This document describes the current production architecture for registration and classroom handoff.

    +

    Design Goals

    +
      +
    • Keep enrollment automation in a public repository without exposing private intake details.
      • +
    • Avoid organization invitation dependencies.
      • +
    • Use deterministic issue signals for Day 2 release and dashboard status.
      • +
    +

    High-Level Flow

    +
      +
    1. Student opens enrollment or registration issue.
      2. +
    2. registration.yml validates submission and posts assignment links.
      3. +
    3. Student replies ack after Day 1 link verification.
      4. +
    4. Student replies day1-complete after Day 1 milestone.
      5. +
    5. day2-release.yml posts Day 2 assignment link when completion signal is present.
      6. +
    6. instructor-dashboard-sync.yml writes status snapshots to private admin repo issues.
      7. +
    +

    Core Workflows

    +

    registration.yml

    +
      +
    • Handles duplicate and waitlist behavior.
      • +
    • Stores detailed intake in private repo when configured.
      • +
    • Redacts public issue body for privacy.
      • +
    • Posts Day 1 and Day 2 links from repository variables.
      • +
    +

    day2-release.yml

    +
      +
    • Runs on schedule and manual dispatch.
      • +
    • Reads enrollment issues with enrolled label.
      • +
    • Releases Day 2 when either condition is true:
        +
      • Label day2-eligible or day1-complete is present.
        • +
      • Student comment contains day1-complete.
        • +
      +
      • +
    +

    instructor-dashboard-sync.yml

    +
      +
    • Reads enrollment issues and comments from this repo.
      • +
    • Computes status categories:
        +
      • awaiting-ack
        • +
      • active-day1
        • +
      • day1-complete
        • +
      • day2-released
        • +
      • needs-info
        • +
      +
      • +
    • Upserts one dashboard issue per student in the private admin repo.
      • +
    +

    Configuration Surface

    +

    Variables

    +
      +
    • CLASSROOM_DAY1_ASSIGNMENT_URL
      • +
    • CLASSROOM_DAY2_ASSIGNMENT_URL
      • +
    • PRIVATE_STUDENT_DATA_REPO
      • +
    • ENABLE_PUBLIC_CLASSROOM_INTAKE_EXPORT
      • +
    • ENABLE_PUBLIC_REGISTRATION_EXPORT
      • +
    +

    Secrets

    +
      +
    • PRIVATE_STUDENT_DATA_TOKEN
      • +
    • INSTRUCTOR_DASHBOARD_TOKEN (dashboard sync)
      • +
    +

    Student Interaction Contract

    +

    Required student replies:

    +
      +
    • ack after opening Day 1 assignment.
      • +
    • day1-complete after Day 1 milestone completion.
      • +
    +

    These text signals are intentionally simple so facilitators can test and recover quickly.

    + +
    + + + + diff --git a/html/admin/IMPLEMENTATION_SUMMARY.html b/html/admin/IMPLEMENTATION_SUMMARY.html new file mode 100644 index 0000000..cc53d96 --- /dev/null +++ b/html/admin/IMPLEMENTATION_SUMMARY.html @@ -0,0 +1,137 @@ + + + + + + + Registration + Classroom Integration Summary - GIT Going with GitHub + + + + + + + + +
    +

    Registration + Classroom Integration Summary

    +

    Date: 2026-05-12

    +

    Active Model

    +

    The repository now uses assignment-link automation without organization invitation automation.

    +

    Student interaction sequence

    +
      +
    1. Student submits enrollment issue.
      2. +
    2. Workflow validates and posts Day 1 assignment link.
      3. +
    3. Student replies ack after confirming access.
      4. +
    4. Student replies day1-complete (or facilitator applies day2-eligible).
      5. +
    5. Day 2 release workflow posts Day 2 assignment link.
      6. +
    +

    Configuration Required

    +

    Variables

    +
      +
    • CLASSROOM_DAY1_ASSIGNMENT_URL
      • +
    • CLASSROOM_DAY2_ASSIGNMENT_URL
      • +
    • PRIVATE_STUDENT_DATA_REPO
      • +
    • ENABLE_PUBLIC_CLASSROOM_INTAKE_EXPORT
      • +
    • ENABLE_PUBLIC_REGISTRATION_EXPORT
      • +
    +

    Secrets

    +
      +
    • PRIVATE_STUDENT_DATA_TOKEN
      • +
    • INSTRUCTOR_DASHBOARD_TOKEN (for dashboard sync)
      • +
    +

    Workflow Changes

    +
      +

    • registration.yml

      +
        +
      • Removed org invite dependency.
        • +
      • Removed classroom join variable dependency.
        • +
      • Keeps duplicate/waitlist behavior.
        • +
      • Keeps assignment-link posting.
        • +
      +
      • +

    • day2-release.yml

      +
        +
      • Uses issue signals (day1-complete or day2-eligible) to release Day 2.
        • +
      • No org API dependency.
        • +
      +
      • +

    • instructor-dashboard-sync.yml

      +
        +
      • Uses enrollment issue labels/comments for status snapshots.
        • +
      • No classroom org scan dependency.
        • +
      +
      • +
    +

    QA and Testing Updates

    +

    Updated documents:

    +
      +
    • GO-LIVE-QA-GUIDE.md
      • +
    • admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md
      • +
    • admin/ENROLLMENT_SETUP_CHECKLIST.md
      • +
    • admin/REGISTRATION-QUICKSTART.md
      • +
    • admin/REGISTRATION-ADMIN.md
      • +
    • admin/QUICK_START_SETUP.md
      • +
    • admin/CLASSROOM_INTEGRATION_GUIDE.md
      • +
    +

    Readiness Checklist

    +
      +
    • Day 1 link variable set and validated.
      • +
    • Day 2 link variable set and validated.
      • +
    • Student test confirms ack and day1-complete path.
      • +
    • Day 2 release comment verified.
      • +
    • Dashboard sync workflow produces student status issues in admin repo.
      • +
    + +
    + + + + diff --git a/html/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html b/html/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html index 44e809f..65de8d4 100644 --- a/html/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html +++ b/html/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html @@ -180,8 +180,7 @@

    Critical Precondition Gat
  • Registration automation settings are correct when using registration-to-classroom handoff:
      -
    • Secret CLASSROOM_ORG_ADMIN_TOKEN is set in Community-Access/git-going-with-github
      • -
    • Variables CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL are set in Community-Access/git-going-with-github
      • +
    • Variables CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL are set in Community-Access/git-going-with-github
  • Registration entry configuration exists and is valid:
    • @@ -244,7 +243,7 @@

    A.1 Create GitHub Classroom assi
  • Title: You Can Build This
  • Same base settings as Day 1
  • Paste description from classroom/assignment-day2-you-can-build-this.md
    • -
  • Add Day 2 autograding: exactly 6 tests totaling 75 points
    • +
  • Skip the autograding tests area for the same reason as Day 1.
  • Copy the resulting invite URL. This is your CLASSROOM_DAY2_ASSIGNMENT_URL.
    • @@ -254,58 +253,25 @@

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

    B. Configure registration automation key and variables

    +

    B. Configure registration automation variables

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

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

    -

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

    -

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

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

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

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

    Step B.3 -- Add the repository variables

    +

    Step B.1 -- Add the repository variables

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

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

      Variable 1:

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

      Variable 2:

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

      Variable 3:

      +

      Variable 2:

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

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

      +

    4. After adding both, re-open each variable entry and confirm:

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

        B. Configure regi

    Why this matters:

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

    C. Configure template repository Actions permissions

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

    @@ -381,7 +347,7 @@

    Test Artifacts You Will Produce

    • Screenshots of registration confirmation and waitlist behavior.
    • Screenshot of Day 1 and Day 2 assignment configuration pages.
      • -
    • Screenshot of Day 1 and Day 2 autograding test lists with correct counts.
      • +
    • Screenshot of Day 1 and Day 2 assignment pages showing the autograding tests area is intentionally empty, plus a screenshot of the template repo's .github/workflows/ folder listing the eight autograder workflows.
    • Link to Learning Room template sync PR (or explicit no-change output) before cohort launch.
    • Evidence of template smoke validation from a repo created from Community-Access/learning-room-template.
    • Links to test student Day 1 and Day 2 repositories.
      • @@ -523,7 +489,7 @@

      QA Valid Autograder behavior -Classroom grading panel, PR checks, and Actions logs +Student-repo Actions tab and the bot comment posted on each relevant issue or PR On relevant challenge events Trigger known pass and known fail for each autograded challenge Failing scenarios are understandable and pass after correct fix @@ -629,26 +595,22 @@

      Step
    • Required labels exist and are usable.

    Step 0.2 Deploy optional registration-to-classroom automation settings

    -

    Goal: enable automatic org invite and assignment-link injection in registration confirmation comments.

    +

    Goal: enable assignment-link injection and Day 2 release signaling in registration confirmation comments.

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

    Using the setup script (recommended):

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

    The script will:

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

    If running manually instead:

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

      S

    Pass criteria:

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

    Step 2.

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

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

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

    +

    Expected output: CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL appear in variables.

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

    Pass criteria:

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

    Step 3. Execute registration happy-path test

    Use the non-admin test student account.

    @@ -731,7 +692,7 @@

    Step 3. Execute registratio
  • Confirm the welcome comment includes:
    • Zoom registration information.
    • Day 1 and Day 2 assignment links (if variables are set).
      • -
    • Organization invitation status when classroom org automation is active.
      • +
    • Guidance to reply ack after Day 1 link verification.
  • Confirm registration label is applied.
    • @@ -821,10 +782,14 @@

    Step 7. Valida
  • content-validation.yml
  • student-progression.yml
  • skills-progression.yml
    • +
  • 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
    • @@ -886,14 +851,14 @@

    Step 11. Create Day 1 assignmen
  • Grant students admin access: No
  • Enable feedback pull requests: Yes
  • Paste description from classroom/assignment-day1-you-belong-here.md
    • -
  • Add autograding from admin/classroom/autograding-setup.md -- Day 1 requires exactly 4 tests totaling 50 points
    • +
  • Skip the autograding tests area. Autograded checks run as GitHub Actions workflows in the template repo (see admin/classroom/autograding-setup.md). Leave the Classroom test cases section empty.
  • Save and copy the invite URL from the assignment page
  • If Initialize-WorkshopSetup.ps1 has not been run yet, paste the URL into CLASSROOM_DAY1_ASSIGNMENT_URL. If it has been run, re-run it to pick up the new URL automatically.

    • Pass criteria:

    • Day 1 assignment exists with title You Belong Here.
      • -
    • Test count is 4, total points is 50.
      • +
    • The Classroom autograding tests area is empty (checks run from template workflows instead).
    • Feedback pull request is enabled.
    • CLASSROOM_DAY1_ASSIGNMENT_URL variable matches the assignment invite link.
    @@ -908,14 +873,14 @@

    Step 12. Create Day 2 assignmen
  • Apply same base settings as Day 1 (individual, private, no admin access, feedback PR enabled)
  • Template: Community-Access/learning-room-template
  • Paste description from classroom/assignment-day2-you-can-build-this.md
    • -
  • Add Day 2 autograding from admin/classroom/autograding-setup.md -- 6 tests totaling 75 points
    • +
  • Skip the autograding tests area for the same reason as Day 1 (see admin/classroom/autograding-setup.md).
  • Save and copy the invite URL
  • Update CLASSROOM_DAY2_ASSIGNMENT_URL or re-run Initialize-WorkshopSetup.ps1 to pick it up automatically

    • Pass criteria:

    • Day 2 assignment exists with title You Can Build This.
      • -
    • Test count is 6, total points is 75.
      • +
    • The Classroom autograding tests area is empty (checks run from template workflows instead).
    • Feedback pull request is enabled.
    • CLASSROOM_DAY2_ASSIGNMENT_URL variable matches the assignment invite link.
    @@ -1981,9 +1946,9 @@

    Troubleshooting and Rollback

    1. Registration invite automation issue:

        -
      • Step 1: Confirm CLASSROOM_ORG_ADMIN_TOKEN and CLASSROOM_ORG values are present and correctly scoped.
        • -
      • Step 2: If automation is still failing, disable org invite automation by clearing CLASSROOM_ORG.
        • -
      • Step 3: Continue registration flow with manual classroom invite process.
        • +
      • Step 1: Confirm CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL are present and valid links.
        • +
      • Step 2: If automation is still failing, clear the affected assignment URL variable and continue with manual link sharing.
        • +
      • Step 3: Continue registration flow with manual classroom assignment guidance.
      • Verify: registration workflow still posts welcome response and assignment links as configured.
      2. @@ -2005,7 +1970,7 @@

      Troubleshooting and Rollback

    2. Autograder mismatch:

        -
      • Step 1: Re-check exact autograder command/settings definitions in admin/classroom/autograding-setup.md.
        • +
      • Step 1: Open the affected autograder-*.yml workflow file in learning-room/.github/workflows/ and confirm its logic matches the documented behavior in admin/classroom/autograding-setup.md.
      • Step 2: Trigger known-fail and known-pass scenarios for the affected autograder.
      • Step 3: Compare observed output with expected rubric behavior.
      • Verify: fail messages are actionable and pass state is reachable with correct student behavior.
        • @@ -2219,7 +2184,7 @@

        Current Progress Snapshot (2026-05
      • Registration issues deleted from source repository (count now 0).
      • Discussions deleted from source repository (count now 0).
      • Learning Room template sync PR merged: Community-Access/learning-room-template#11.
        • -
      • Registration secret and variable values set for next cohort (CLASSROOM_ORG_ADMIN_TOKEN, CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL).
        • +
      • Registration variable values set for next cohort (CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL).
      • Day 1 and Day 2 classroom assignments created for next cohort.

      diff --git a/html/admin/QUICK_START_SETUP.html b/html/admin/QUICK_START_SETUP.html new file mode 100644 index 0000000..7a5e747 --- /dev/null +++ b/html/admin/QUICK_START_SETUP.html @@ -0,0 +1,147 @@ + + + + + + + Quick Start: Assignment-Link Registration Setup - GIT Going with GitHub + + + + + + + + +
      +

      Quick Start: Assignment-Link Registration Setup

      +

      This quick start configures registration automation for the current student interaction model.

      +

      Prerequisites

      +
        +
      • Classroom assignments exist in GitHub Classroom.
        • +
      • You have admin access to Community-Access/git-going-with-github.
        • +
      • You can copy Day 1 and Day 2 assignment invite links.
        • +
      + +

      From https://classroom.github.com:

      +
        +
      1. Open Day 1 assignment and copy invite link.
        2. +
      2. Open Day 2 assignment and copy invite link.
        3. +
      +

      Expected format:

      +
        +
      • https://classroom.github.com/a/<short-code>
        • +
      +

      Step 2: Configure Repository Variables

      +

      Go to https://github.com/Community-Access/git-going-with-github/settings/variables/actions.

      +

      Create or update:

      + + + + + + + + + + + + + + + +
      NameValue
      CLASSROOM_DAY1_ASSIGNMENT_URLDay 1 invite link
      CLASSROOM_DAY2_ASSIGNMENT_URLDay 2 invite link
      +

      Step 3: Validate Registration Flow

      +
        +
      1. Open a test enrollment issue.
        2. +
      2. Confirm welcome comment includes Day 1 link.
        3. +
      3. Reply ack from test student account.
        4. +
      4. Reply day1-complete from test student account.
        5. +
      5. Confirm Day 2 release comment appears.
        6. +
      +

      Expected Results

      +
        +
      • Enrollment issue is processed successfully.
        • +
      • No org-invite dependency exists.
        • +
      • Day 2 release is driven by issue signal (day1-complete or day2-eligible).
        • +
      +

      Troubleshooting

      + + + + + + + + + + + + + + + + + + + +
      ProblemFix
      Day 1 link missingVerify CLASSROOM_DAY1_ASSIGNMENT_URL is set with no extra spaces
      Day 2 release did not triggerAdd day1-complete comment or apply day2-eligible label
      Wrong assignment openedRe-copy invite links and update variables
      +

      Operational Notes

      +
        +
      • Student org membership is not part of this flow.
        • +
      • Assignment acceptance remains student-driven in GitHub Classroom.
        • +
      • Private intake and dashboard workflows continue to run independently.
        • +
      + +
      + + + + diff --git a/html/admin/REGISTRATION-ADMIN.html b/html/admin/REGISTRATION-ADMIN.html index 1e7650a..fa0f4fd 100644 --- a/html/admin/REGISTRATION-ADMIN.html +++ b/html/admin/REGISTRATION-ADMIN.html @@ -59,161 +59,71 @@

      Registration Administration Guide

      -

      This document explains how the registration system works and how to manage it, including optional API-based classroom invitation automation.

      -

      If you just need implementation steps, start with REGISTRATION-QUICKSTART.md.

      -

      How Registration Tracking Works

      -

      Registration Count (Website)

      -

      The registration page at REGISTER.html queries the GitHub Search API in real time every time a visitor loads the page. It counts open issues with the registration label. No CSV or local data is involved.

      -

      Capacity Check (Workflow)

      -

      When someone submits a registration issue, the GitHub Actions workflow queries all issues labeled registration and counts unique GitHub usernames. If the count is at or above 75, the registrant is placed on the waitlist instead.

      -

      Optional Classroom API Automation

      -

      When configured, the registration workflow can also:

      +

      This document explains how registration automation works in the current assignment-link model.

      +

      If you only need setup steps, use REGISTRATION-QUICKSTART.md.

      +

      Current Model

      +

      Registration automation in this repository does not require organization invitations.

      +

      What the workflow does:

        -
      • Check whether the registrant is already in the classroom organization
        • -
      • Send an organization invitation if needed
        • -
      • Include Day 1 and Day 2 GitHub Classroom assignment links in the welcome comment
        • +
      • Validates registration or enrollment submissions.
        • +
      • Handles duplicate and waitlist behavior.
        • +
      • Posts Day 1 and Day 2 assignment links when variables are configured.
        • +
      • Uses student issue comments as milestone signals:
          +
        • ack confirms Day 1 link access.
          • +
        • day1-complete signals Day 2 release eligibility.
        -

        Important: This does not bypass GitHub Classroom acceptance. Students still must click the assignment link and accept.

        -

        Full API Setup (Classroom Automation)

        -

        Use these steps to enable end-to-end registration plus classroom invitation flow.

        -

        1. Create an admin token for organization invites

        -

        Create a GitHub personal access token for a facilitator/admin account with permission to manage organization invitations.

        -

        Recommended minimum permissions:

        +
        • +
      +

      Required Repository Variables

      +

      Set these in Community-Access/git-going-with-github:

        -
      • Organization administration permissions sufficient to create invitations
        • -
      • Repository read access for this repository
        • +
      • CLASSROOM_DAY1_ASSIGNMENT_URL
        • +
      • CLASSROOM_DAY2_ASSIGNMENT_URL
      -

      Store this token securely. Do not commit it to the repository.

      -

      2. Add repository secret

      -

      In repository settings, add this secret:

      +

      Optional operational variables:

        -
      • CLASSROOM_ORG_ADMIN_TOKEN = token from Step 1
        • +
      • ENABLE_PUBLIC_REGISTRATION_EXPORT
        • +
      • ENABLE_PUBLIC_CLASSROOM_INTAKE_EXPORT
        • +
      • PRIVATE_STUDENT_DATA_REPO
      -

      3. Add repository variables

      -

      In repository settings, add these variables:

      +

      Required secrets for private data and dashboard workflows are unrelated to org invites:

        -
      • CLASSROOM_ORG = your classroom org name (example: Community-Access-Classroom)
        • -
      • CLASSROOM_DAY1_ASSIGNMENT_URL = Day 1 Classroom invite URL
        • -
      • CLASSROOM_DAY2_ASSIGNMENT_URL = Day 2 Classroom invite URL
        • +
      • PRIVATE_STUDENT_DATA_TOKEN
        • +
      • INSTRUCTOR_DASHBOARD_TOKEN (if using dashboard sync)
      -

      If you omit these variables/secrets, registration still works; only the classroom automation steps are skipped.

      -

      4. Confirm workflow behavior

      -

      After setup, successful non-duplicate registrations should produce:

      +

      End-To-End Verification

      +

      Run this checklist before go-live:

        -
      1. Standard registration confirmation logic (registration label and capacity handling)
        2. -
      2. Organization invite status handling:
          -
        • invited (new invite sent)
          • -
        • already-invited (pending invite exists)
          • -
        • already-member (user already in org)
          • -
        -
        3. -
      3. Welcome comment including classroom assignment links (if configured)
        4. +
      4. Submit a test enrollment issue from a test student account.
        5. +
      5. Confirm welcome comment includes Day 1 link.
        6. +
      6. Reply ack as the test student.
        7. +
      7. Reply day1-complete as the test student.
        8. +
      8. Confirm Day 2 is unlocked comment appears.
        9. +
      9. Confirm labels are applied as expected: enrolled, day2-eligible, day2-released.
        10. +
      10. Submit a duplicate registration and confirm duplicate-close behavior.
      -

      5. End-to-end test checklist

      -

      Run this once before opening registration publicly:

      -
        -
      1. Submit a test registration issue from a non-member test account.
        2. -
      2. Verify an org invitation is sent.
        3. -
      3. Verify Day 1/Day 2 assignment links appear in the welcome comment.
        4. -
      4. Accept org invite from the test account.
        5. -
      5. Accept Day 1 assignment link from the test account.
        6. -
      6. Confirm private classroom repo is created.
        7. -
      7. Submit a second registration from the same account and confirm duplicate handling.
        8. -
      -

      6. Operational notes

      -
        -
      • The automation runs only when capacity is available and the registration is not a duplicate.
        • -
      • Waitlisted users are not invited automatically by this workflow.
        • -
      • Assignment acceptance remains student-driven in GitHub Classroom.
        • -
      -

      7. Rollback plan

      -

      If invitation automation causes issues:

      +

      Rollback

      +

      If assignment posting is incorrect, keep registration running and temporarily disable links:

        -
      1. Remove CLASSROOM_ORG_ADMIN_TOKEN secret (fastest stop switch), or
        2. -
      2. Clear CLASSROOM_ORG variable.
        3. +
      3. Clear CLASSROOM_DAY1_ASSIGNMENT_URL, or
        4. +
      4. Clear CLASSROOM_DAY2_ASSIGNMENT_URL.
      -

      Registration confirmations and CSV export continue to function without classroom API steps.

      -

      CSV Export

      -

      The CSV is a convenience export for reviewing registrations in spreadsheet form. It is regenerated from scratch (from the issues) every time someone registers or when the workflow is manually triggered. The issues are the source of truth, not the CSV.

      -

      The CSV is uploaded as a workflow artifact (retained for 90 days) and is only accessible to repository collaborators. It is not committed to the repository.

      -

      Downloading the CSV

      -

      Using the GitHub CLI

      -

      Download the latest registration CSV:

      -
      gh run download --name registrations --dir ./registrations -R community-access/git-going-with-github
      -

      List recent workflow runs first to pick a specific one:

      -
      gh run list --workflow=registration.yml -R community-access/git-going-with-github
-gh run download <run-id> --name registrations --dir ./registrations -R community-access/git-going-with-github
      -

      Using the GitHub Web UI

      +

      Registration, duplicate handling, waitlist behavior, and private intake storage will continue.

      +

      Student Interaction Contract

      +

      Students should be told to follow this sequence:

        -
      1. Go to the repository on GitHub
        2. -
      2. Click the Actions tab
        3. -
      3. Click a Registration - Welcome & CSV Export workflow run
        4. -
      4. Scroll down to the Artifacts section
        5. -
      5. Click registrations to download the CSV
        6. +
      6. Submit enrollment issue.
        7. +
      7. Open Day 1 assignment link from the bot comment.
        8. +
      8. Reply ack after verifying access.
        9. +
      9. Reply day1-complete when Day 1 milestone is done.
        10. +
      10. Open Day 2 assignment link from the release comment.
      -

      Regenerating the CSV On Demand

      -

      To rebuild the CSV from all current registration issues (e.g., right before the workshop):

      -
      gh workflow run registration.yml -R community-access/git-going-with-github
      -

      This triggers the workflow_dispatch event, which rebuilds the CSV from all registration issues and uploads a fresh artifact.

      -

      Resetting Support Environment (From Top)

      -

      If you need to rebuild the support environment from scratch, run:

      -
      scripts/classroom/Reset-SupportHubEnvironment.ps1
      -

      This restores support hub baseline settings, labels, and automation so registration help links and post-workshop support routing remain reliable.

      -

      Registration Scenarios

      -

      The workflow handles three scenarios when someone submits a registration issue:

      -

      1. New Registration (Spots Available)

      -
        -
      • Posts a welcome comment confirming registration
        • -
      • Adds the registration label
        • -
      • Optionally sends a classroom organization invitation
        • -
      • Optionally includes Day 1 and Day 2 assignment links in the welcome comment
        • -
      • Exports updated CSV as a workflow artifact
        • -
      -

      2. Duplicate Registration

      -
        -
      • Detects the user already has a prior registration issue
        • -
      • Posts a friendly message pointing to their original issue
        • -
      • Labels the issue duplicate and closes it
        • -
      -

      3. Registration Full (75+ Registrants)

      -
        -
      • Posts a message explaining registration is full
        • -
      • Labels the issue waitlist (keeps it open for future notification)
        • -
      • The registration page automatically switches to waitlist mode via JavaScript
        • -
      -

      Labels Used

      - - - - - - - - - - - - - - - - - - - - - - - -
      LabelColorPurpose
      registrationDefaultApplied to confirmed registrations
      duplicateGray (#cfd3d7)Applied to duplicate registration attempts
      waitlistYellow (#FBCA04)Applied when capacity is full

      Privacy Notes

        -
      • The CSV contains personal information (names, emails) and is stored only as a workflow artifact, not in the repository
        • -
      • A previous version of the CSV was committed to git history at commit 559ca5f. It remains accessible through git history but is no longer present in the current branch
        • -
      • Registration issues themselves are publicly visible since this is a public repository
        • -
      • The .gitignore file excludes .github/data/ to prevent accidental commits of registration data
        • -
      • Private student-success exports and facilitator follow-up notes belong in the private Community-Access/git-going-student-success repository, not in this public curriculum repository
        • -
      • The classroom roster sync file (.github/data/student-roster.json) intentionally stores non-PII operational data only
        • +
      • Registration issues are public in this repository.
        • +
      • Public issue bodies are redacted for enrollment fast-path.
        • +
      • Full intake details are stored in the private administration repository.
        • +
      • CSV exports are artifact-based and controlled by explicit flags.
      diff --git a/html/admin/REGISTRATION-QUICKSTART.html b/html/admin/REGISTRATION-QUICKSTART.html index 4b7166e..599d4a4 100644 --- a/html/admin/REGISTRATION-QUICKSTART.html +++ b/html/admin/REGISTRATION-QUICKSTART.html @@ -59,39 +59,20 @@

      Registration Automation Quickstart (Facilitator)

      -

      Use this when you need to enable registration plus classroom API automation quickly.

      +

      Use this when you need to enable registration with assignment-link automation quickly.

      For full background and troubleshooting, use REGISTRATION-ADMIN.md.

      5-Minute Setup

        -
      1. Create an admin token from a facilitator account with organization invitation permissions.
        2. -
      2. In repository settings, add secret:
          -
        • CLASSROOM_ORG_ADMIN_TOKEN
          • -
        -
      3. In repository settings, add variables:
          -
        • CLASSROOM_ORG
        • CLASSROOM_DAY1_ASSIGNMENT_URL
        • CLASSROOM_DAY2_ASSIGNMENT_URL
      4. Save all values.
        5. -
      5. Submit one test registration issue from a non-member test account.
        6. +
      6. Submit one test registration issue from a test account.

      Copy/Paste Settings Template

      Use this checklist while entering repository settings values.

      -

      Repository Secret

      - - - - - - - - - - - -
      NameValue to paste
      CLASSROOM_ORG_ADMIN_TOKENPASTE_ADMIN_TOKEN_HERE

      Repository Variables

      @@ -101,10 +82,6 @@

      Repository Variables

      - - - - @@ -117,28 +94,26 @@

      Before You Save

      • Confirm there are no extra spaces before or after values.
      • Confirm both assignment URLs open correctly in a logged-in browser.
        • -
      • Confirm the org name matches exactly, including capitalization.

      Expected Result (Happy Path)

      After the test issue is opened and capacity is available:

      1. Registration confirmation comment is posted.
        2. -
      2. Organization invite is sent (or detected as already pending/member).
      3. Day 1 and Day 2 assignment links appear in the confirmation comment.
      4. registration label is applied.

      Fast Verification Checklist

        -
      • Test user received or already had organization invite
      • Confirmation comment includes assignment links
      • Duplicate submission closes automatically with duplicate message
      • Waitlist behavior still works when capacity is full
        • +
      • Student can reply ack, then day1-complete, and receive Day 2 release comment

      Rollback (Immediate)

      -

      If anything behaves unexpectedly, disable classroom API automation without stopping registration:

      +

      If anything behaves unexpectedly, disable assignment-link posting without stopping registration:

        -
      1. Remove repository secret CLASSROOM_ORG_ADMIN_TOKEN, or
        2. -
      2. Clear repository variable CLASSROOM_ORG
        3. +
      3. Clear CLASSROOM_DAY1_ASSIGNMENT_URL, or
        4. +
      4. Clear CLASSROOM_DAY2_ASSIGNMENT_URL

      The registration workflow will continue standard confirmation, capacity checks, and CSV export.

      Full Support Reset (When Needed)

      @@ -149,7 +124,7 @@

      Day-Of Operations

    3. Keep REGISTRATION-ADMIN.md open.
    4. Watch Actions runs for registration.yml after each new registration.
    5. Spot-check one confirmation comment every few runs.
      6. -
    6. If failures appear, use rollback and continue manual classroom invite flow.
      7. +
    7. If failures appear, use rollback and continue manual assignment link sharing.

      8. Privacy Reminder

      CLASSROOM_ORGCommunity-Access-Classroom
      CLASSROOM_DAY1_ASSIGNMENT_URL https://classroom.github.com/a/REPLACE_DAY1_ID
      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ChallengeWhat it verifiesWorkflow file
      2: Issue FiledStudent has opened at least one issue in their repo.github/workflows/autograder-issue-filed.yml
      5: Commit on a branchAt least one commit on a non-default branch.github/workflows/autograder-branch-commit.yml
      6: PR links to an issuePR body contains Closes, Fixes, or Resolves #N.github/workflows/autograder-pr-link.yml
      7: No conflict markersNo <<<<<<<, =======, or >>>>>>> markers in docs/.github/workflows/autograder-conflicts.yml
      +

      Day 2 checks

      + + + + + + + + + + + + + + + + + + + + + + + +
      ChallengeWhat it verifiesWorkflow file
      10: Local commitAt least one commit on a non-default branch.github/workflows/autograder-local-commit.yml
      14: Custom issue templateA non-challenge YAML template under .github/ISSUE_TEMPLATE/ with name: and description: fields.github/workflows/autograder-template.yml
      16: Capstone agent fileAgent markdown file with frontmatter, responsibilities, and guardrails.github/workflows/autograder-capstone.yml
      +

      A separate workflow, .github/workflows/autograder-watchdog.yml, listens for workflow_run completion of every autograder above. If one of them ends with conclusion: failure and no challenge-result comment has been posted on the open PR for that branch, the watchdog posts a single fallback notice telling the student the check could not complete and to ping a facilitator. If the in-job error handler already posted a comment, the watchdog is a no-op. This is a safety net only -- the seven primary workflows remain the source of truth for pass/fail.

      +

      What to do during cohort setup

      +

      When creating Day 1 and Day 2 assignments in GitHub Classroom:

        -
      1. Add all tests and save assignment.
        2. -
      2. Confirm test count:
          -
        • Day 1 has 4 tests
          • -
        • Day 2 has 6 tests
          • -
        -
        3. -
      3. Confirm point totals:
          -
        • Day 1 total = 50
          • -
        • Day 2 total = 75
          • -
        -
        4. -
      4. Use a test student account to accept each assignment.
        5. -
      5. Trigger one known pass on each assignment.
        6. -
      6. Trigger one known fail on each assignment and confirm feedback appears.
        7. -
      7. Confirm rerun passes after fix.
        8. -
      8. Capture one screenshot of pass and one of fail for facilitator reference.
        9. +
      9. Paste the assignment description as usual.
        10. +
      10. Skip the autograding tests section. Leave it empty. Do not click Add test.
        11. +
      11. Save the assignment and copy the invite URL.
      -

      Fast Validation Scenarios

      -

      Day 1 quick checks

      -
        -
      • Pass check: open an issue, make a commit, open a PR with Closes #<issue-number>, ensure no conflict markers remain in docs/.
        • -
      • Fail check: open a PR without Closes, Fixes, or Resolves in the body.
        • -
      -

      Day 2 quick checks

      -
        -
      • Pass check: create one non-main commit, add a custom issue template with name: and description:, add an agent markdown file with frontmatter and required sections.
        • -
      • Fail check: create an agent file without a ## Responsibilities section.
        • -
      -

      Troubleshooting

      -

      Test stays red after student fix

      -
        -
      1. Confirm student pushed a new commit to the same PR branch.
        2. -
      2. Open PR checks and inspect the failing command output.
        3. -
      3. Verify required text is in the file body, not only in issue comments.
        4. -
      -

      Challenge 14 tests fail unexpectedly

      -
        -
      • Verify template filename is .yml.
        • -
      • Verify it is under .github/ISSUE_TEMPLATE.
        • -
      • Verify filename does not match challenge-*.yml, bonus-*.yml, or config.yml.
        • -
      -

      Challenge 16 section check fails

      -
        -
      • Ensure headings use markdown heading syntax (for example ## Responsibilities).
        • -
      • Ensure guardrail heading uses one accepted form:
          -
        • ## Guardrails
          • -
        • ## Limitations
          • -
        • ## Boundaries
          • -
        -
        • -
      -

      Keep This Guide Synced

      -

      If autograding JSON changes, update this file in the same pull request:

      -
        -
      • classroom/autograding-day1.json
        • -
      • classroom/autograding-day2.json
        • -
      +

      That is the entire change. Everything else in live-facilitation-flow.md still applies.

      +

      Verifying the checks work

      +

      Before sharing invite links, use a test student account to verify each workflow posts its comment. The procedure is in live-facilitation-flow.md (Phase 3: Verify Autograder Workflows).

      +

      Historical reference

      +

      The Classroom test-case definitions that used to live in classroom/autograding-day1.json and classroom/autograding-day2.json were deleted in May 2026 along with this workflow migration. The autograder workflow files (learning-room/.github/workflows/autograder-*.yml) are the only remaining source of truth for what each check verifies. Git history retains the old JSONs if you ever need to read them.

    8. Registration automation settings are correct when using registration-to-classroom handoff:
        -
      • Secret CLASSROOM_ORG_ADMIN_TOKEN is set in Community-Access/git-going-with-github
        • -
      • Variables CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL are set in Community-Access/git-going-with-github
        • +
      • Variables CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL are set in Community-Access/git-going-with-github
    9. Registration entry configuration exists and is valid:
      10. @@ -244,7 +243,7 @@

      A.1 Create GitHub Classroom assi
    10. Title: You Can Build This
    11. Same base settings as Day 1
    12. Paste description from classroom/assignment-day2-you-can-build-this.md
      13. -
    13. Add Day 2 autograding: exactly 6 tests totaling 75 points
      14. +
    14. Skip the autograding tests area for the same reason as Day 1.
    15. Copy the resulting invite URL. This is your CLASSROOM_DAY2_ASSIGNMENT_URL.
      16. @@ -254,58 +253,25 @@

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

      B. Configure registration automation key and variables

      +

      B. Configure registration automation variables

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

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

      -

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

      -

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

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

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

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

      Step B.3 -- Add the repository variables

      +

      Step B.1 -- Add the repository variables

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

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

        Variable 1:

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

        Variable 2:

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

        Variable 3:

        +

        Variable 2:

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

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

        +

      4. After adding both, re-open each variable entry and confirm:

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

          B. Configure regi

      Why this matters:

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

      C. Configure template repository Actions permissions

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

      @@ -381,7 +347,7 @@

      Test Artifacts You Will Produce

      • Screenshots of registration confirmation and waitlist behavior.
      • Screenshot of Day 1 and Day 2 assignment configuration pages.
        • -
      • Screenshot of Day 1 and Day 2 autograding test lists with correct counts.
        • +
      • Screenshot of Day 1 and Day 2 assignment pages showing the autograding tests area is intentionally empty, plus a screenshot of the template repo's .github/workflows/ folder listing the eight autograder workflows.
      • Link to Learning Room template sync PR (or explicit no-change output) before cohort launch.
      • Evidence of template smoke validation from a repo created from Community-Access/learning-room-template.
      • Links to test student Day 1 and Day 2 repositories.
        • @@ -523,7 +489,7 @@

        QA Valid Autograder behavior -Classroom grading panel, PR checks, and Actions logs +Student-repo Actions tab and the bot comment posted on each relevant issue or PR On relevant challenge events Trigger known pass and known fail for each autograded challenge Failing scenarios are understandable and pass after correct fix @@ -629,26 +595,22 @@

        Step
      • Required labels exist and are usable.

      Step 0.2 Deploy optional registration-to-classroom automation settings

      -

      Goal: enable automatic org invite and assignment-link injection in registration confirmation comments.

      +

      Goal: enable assignment-link injection and Day 2 release signaling in registration confirmation comments.

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

      Using the setup script (recommended):

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

      The script will:

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

      If running manually instead:

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

        S

      Pass criteria:

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

      Step 2.

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

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

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

      +

      Expected output: CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL appear in variables.

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

      Pass criteria:

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

      Step 3. Execute registration happy-path test

      Use the non-admin test student account.

      @@ -731,7 +692,7 @@

      Step 3. Execute registratio
    16. Confirm the welcome comment includes:
      • Zoom registration information.
      • Day 1 and Day 2 assignment links (if variables are set).
        • -
      • Organization invitation status when classroom org automation is active.
        • +
      • Guidance to reply ack after Day 1 link verification.
    17. Confirm registration label is applied.
      18. @@ -821,10 +782,14 @@

      Step 7. Valida
    18. content-validation.yml
    19. student-progression.yml
    20. skills-progression.yml
      21. +
    21. autograder-issue-filed.yml
      22. +
    22. autograder-branch-commit.yml
      23. +
    23. autograder-pr-link.yml
    24. autograder-conflicts.yml
    25. autograder-local-commit.yml
    26. autograder-template.yml
    27. autograder-capstone.yml
      28. +
    28. autograder-watchdog.yml
      29. @@ -886,14 +851,14 @@

      Step 11. Create Day 1 assignmen
    29. Grant students admin access: No
    30. Enable feedback pull requests: Yes
    31. Paste description from classroom/assignment-day1-you-belong-here.md
      32. -
    32. Add autograding from admin/classroom/autograding-setup.md -- Day 1 requires exactly 4 tests totaling 50 points
      33. +
    33. Skip the autograding tests area. Autograded checks run as GitHub Actions workflows in the template repo (see admin/classroom/autograding-setup.md). Leave the Classroom test cases section empty.
    34. Save and copy the invite URL from the assignment page
    35. If Initialize-WorkshopSetup.ps1 has not been run yet, paste the URL into CLASSROOM_DAY1_ASSIGNMENT_URL. If it has been run, re-run it to pick up the new URL automatically.

    Pass criteria:

    • Day 1 assignment exists with title You Belong Here.
      • -
    • Test count is 4, total points is 50.
      • +
    • The Classroom autograding tests area is empty (checks run from template workflows instead).
    • Feedback pull request is enabled.
    • CLASSROOM_DAY1_ASSIGNMENT_URL variable matches the assignment invite link.
    @@ -908,14 +873,14 @@

    Step 12. Create Day 2 assignmen
  • Apply same base settings as Day 1 (individual, private, no admin access, feedback PR enabled)
  • Template: Community-Access/learning-room-template
  • Paste description from classroom/assignment-day2-you-can-build-this.md
    • -
  • Add Day 2 autograding from admin/classroom/autograding-setup.md -- 6 tests totaling 75 points
    • +
  • Skip the autograding tests area for the same reason as Day 1 (see admin/classroom/autograding-setup.md).
  • Save and copy the invite URL
  • Update CLASSROOM_DAY2_ASSIGNMENT_URL or re-run Initialize-WorkshopSetup.ps1 to pick it up automatically

    • Pass criteria:

    • Day 2 assignment exists with title You Can Build This.
      • -
    • Test count is 6, total points is 75.
      • +
    • The Classroom autograding tests area is empty (checks run from template workflows instead).
    • Feedback pull request is enabled.
    • CLASSROOM_DAY2_ASSIGNMENT_URL variable matches the assignment invite link.
    @@ -1981,9 +1946,9 @@

    Troubleshooting and Rollback

    1. Registration invite automation issue:

        -
      • Step 1: Confirm CLASSROOM_ORG_ADMIN_TOKEN and CLASSROOM_ORG values are present and correctly scoped.
        • -
      • Step 2: If automation is still failing, disable org invite automation by clearing CLASSROOM_ORG.
        • -
      • Step 3: Continue registration flow with manual classroom invite process.
        • +
      • Step 1: Confirm CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL are present and valid links.
        • +
      • Step 2: If automation is still failing, clear the affected assignment URL variable and continue with manual link sharing.
        • +
      • Step 3: Continue registration flow with manual classroom assignment guidance.
      • Verify: registration workflow still posts welcome response and assignment links as configured.
      2. @@ -2005,7 +1970,7 @@

      Troubleshooting and Rollback

    2. Autograder mismatch:

        -
      • Step 1: Re-check exact autograder command/settings definitions in admin/classroom/autograding-setup.md.
        • +
      • Step 1: Open the affected autograder-*.yml workflow file in learning-room/.github/workflows/ and confirm its logic matches the documented behavior in admin/classroom/autograding-setup.md.
      • Step 2: Trigger known-fail and known-pass scenarios for the affected autograder.
      • Step 3: Compare observed output with expected rubric behavior.
      • Verify: fail messages are actionable and pass state is reachable with correct student behavior.
        • @@ -2219,7 +2184,7 @@

        Current Progress Snapshot (2026-05
      • Registration issues deleted from source repository (count now 0).
      • Discussions deleted from source repository (count now 0).
      • Learning Room template sync PR merged: Community-Access/learning-room-template#11.
        • -
      • Registration secret and variable values set for next cohort (CLASSROOM_ORG_ADMIN_TOKEN, CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL).
        • +
      • Registration variable values set for next cohort (CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL).
      • Day 1 and Day 2 classroom assignments created for next cohort.

      diff --git a/html/admin/qa-bundle/admin/classroom/autograding-setup.html b/html/admin/qa-bundle/admin/classroom/autograding-setup.html index 5a228f3..fba9522 100644 --- a/html/admin/qa-bundle/admin/classroom/autograding-setup.html +++ b/html/admin/qa-bundle/admin/classroom/autograding-setup.html @@ -4,7 +4,7 @@ - Autograding Setup and Verification - GIT Going with GitHub + Autograding Setup -- Not Required - GIT Going with GitHub @@ -28,7 +28,7 @@
      -

      Autograding Setup and Verification

      -

      This guide makes Classroom autograding setup repeatable and reliable for facilitators.

      -

      Scope

      -
        -
      • Day 1 tests come from classroom/autograding-day1.json
        • -
      • Day 2 tests come from classroom/autograding-day2.json
        • -
      • All entries below are copy-accurate from those files
        • -
      -

      UI Entry Rules (Use for Every Test)

      -

      For each test you add in Classroom:

      -
        -
      • Set Test name exactly as shown below
        • -
      • Set Run command exactly as shown below
        • -
      • Set Comparison to exact
        • -
      • Leave Setup, Input, and Expected output empty unless noted
        • -
      • Set Timeout and Points exactly as shown below
        • -
      -

      Do not paste raw JSON into the UI. Add tests one by one.

      -

      Day 1 Autograding Tests

      -

      Test 1

      -
        -
      • Test name: Challenge 2: Issue Filed
        • -
      • Run command:
        • -
      -
      gh issue list --repo $GITHUB_REPOSITORY --author $GITHUB_ACTOR --state all --json number --jq 'length' | xargs test 0 -lt
      -
        -
      • Comparison: exact
        • -
      • Timeout: 10
        • -
      • Points: 10
        • -
      -

      Test 2

      -
        -
      • Test name: Challenge 5: Commit Exists
        • -
      • Run command:
        • -
      -
      git log --oneline --all --author=$GITHUB_ACTOR | head -1 | grep -q '.'
      -
        -
      • Comparison: exact
        • -
      • Timeout: 10
        • -
      • Points: 10
        • -
      -

      Test 3

      -
        -
      • Test name: Challenge 6: PR with Issue Link
        • -
      • Run command:
        • -
      -
      gh pr list --repo $GITHUB_REPOSITORY --author $GITHUB_ACTOR --state all --json body --jq '.[0].body' | grep -iq 'closes\|fixes\|resolves'
      -
        -
      • Comparison: exact
        • -
      • Timeout: 10
        • -
      • Points: 15
        • -
      -

      Test 4

      -
        -
      • Test name: Challenge 7: No Conflict Markers
        • -
      • Run command:
        • -
      -
      ! grep -rn '<<<<<<< \|======= \|>>>>>>> ' docs/ 2>/dev/null
      -
        -
      • Comparison: exact
        • -
      • Timeout: 10
        • -
      • Points: 15
        • -
      -

      Day 2 Autograding Tests

      -

      Test 1

      -
        -
      • Test name: Challenge 10: Go Local - Commit on Branch
        • -
      • Run command:
        • -
      -
      git log --oneline origin/main..HEAD 2>/dev/null | head -1 | grep -q '.' || git branch -r --list 'origin/*' | grep -v main | head -1 | xargs -I{} git log --oneline origin/main..{} | head -1 | grep -q '.'
      -
        -
      • Comparison: exact
        • -
      • Timeout: 10
        • -
      • Points: 15
        • -
      -

      Test 2

      -
        -
      • Test name: Challenge 14: Template Remix - Custom Issue Template Exists
        • -
      • Run command:
        • -
      -
      find .github/ISSUE_TEMPLATE -name '*.yml' ! -name 'challenge-*.yml' ! -name 'bonus-*.yml' ! -name 'config.yml' 2>/dev/null | head -1 | grep -q '.'
      -
        -
      • Comparison: exact
        • -
      • Timeout: 10
        • -
      • Points: 15
        • -
      -

      Test 3

      -
        -
      • Test name: Challenge 14: Template Remix - Template Has Required Fields
        • -
      • Run command:
        • -
      -
      TEMPLATE=$(find .github/ISSUE_TEMPLATE -name '*.yml' ! -name 'challenge-*.yml' ! -name 'bonus-*.yml' ! -name 'config.yml' 2>/dev/null | head -1); grep -q '^name:' "$TEMPLATE" && grep -q '^description:' "$TEMPLATE"
      -
        -
      • Comparison: exact
        • -
      • Timeout: 10
        • -
      • Points: 10
        • -
      -

      Test 4

      -
        -
      • Test name: Challenge 16: Build Your Agent - Agent File Exists
        • -
      • Run command:
        • -
      -
      find agents community-agents -name '*.md' 2>/dev/null | head -1 | grep -q '.'
      -
        -
      • Comparison: exact
        • -
      • Timeout: 10
        • -
      • Points: 10
        • -
      -

      Test 5

      -
        -
      • Test name: Challenge 16: Build Your Agent - Agent Has Frontmatter
        • -
      • Run command:
        • -
      -
      AGENT=$(find agents community-agents -name '*.md' 2>/dev/null | head -1); head -1 "$AGENT" | grep -q '^---'
      -
        -
      • Comparison: exact
        • -
      • Timeout: 10
        • -
      • Points: 10
        • -
      -

      Test 6

      -
        -
      • Test name: Challenge 16: Build Your Agent - Agent Has Responsibilities and Guardrails
        • -
      • Run command:
        • -
      -
      AGENT=$(find agents community-agents -name '*.md' 2>/dev/null | head -1); grep -qi '## responsibilities\|## what this agent does' "$AGENT" && grep -qi '## guardrails\|## limitations\|## boundaries' "$AGENT"
      -
        -
      • Comparison: exact
        • -
      • Timeout: 10
        • -
      • Points: 15
        • -
      -

      Hardening Checklist Before Cohort Start

      +

      Autograding Setup -- Not Required

      +
      +

      Status: deprecated as of May 2026. You do not need to configure any test cases in the GitHub Classroom autograding UI for this workshop. Skip that step entirely when creating Day 1 and Day 2 assignments.

      +
      +

      Why this changed

      +

      GitHub Classroom's "test cases" panel intermittently fails to save edits (the modal closes with no error and the test list comes back empty). Rather than fight a broken UI on every cohort, every autograded check has been re-implemented as a normal GitHub Actions workflow inside Community-Access/learning-room-template. Those workflows are copied into each student repo automatically when GitHub Classroom creates the repo from the template -- no Classroom configuration required.

      +

      Where the checks live now

      +

      Each check below runs as its own workflow in the student repo. Results are posted as a single PR or issue comment that updates in place on each push.

      +

      Day 1 checks

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ChallengeWhat it verifiesWorkflow file
      2: Issue FiledStudent has opened at least one issue in their repo.github/workflows/autograder-issue-filed.yml
      5: Commit on a branchAt least one commit on a non-default branch.github/workflows/autograder-branch-commit.yml
      6: PR links to an issuePR body contains Closes, Fixes, or Resolves #N.github/workflows/autograder-pr-link.yml
      7: No conflict markersNo <<<<<<<, =======, or >>>>>>> markers in docs/.github/workflows/autograder-conflicts.yml
      +

      Day 2 checks

      + + + + + + + + + + + + + + + + + + + + + + + +
      ChallengeWhat it verifiesWorkflow file
      10: Local commitAt least one commit on a non-default branch.github/workflows/autograder-local-commit.yml
      14: Custom issue templateA non-challenge YAML template under .github/ISSUE_TEMPLATE/ with name: and description: fields.github/workflows/autograder-template.yml
      16: Capstone agent fileAgent markdown file with frontmatter, responsibilities, and guardrails.github/workflows/autograder-capstone.yml
      +

      A separate workflow, .github/workflows/autograder-watchdog.yml, listens for workflow_run completion of every autograder above. If one of them ends with conclusion: failure and no challenge-result comment has been posted on the open PR for that branch, the watchdog posts a single fallback notice telling the student the check could not complete and to ping a facilitator. If the in-job error handler already posted a comment, the watchdog is a no-op. This is a safety net only -- the seven primary workflows remain the source of truth for pass/fail.

      +

      What to do during cohort setup

      +

      When creating Day 1 and Day 2 assignments in GitHub Classroom:

        -
      1. Add all tests and save assignment.
        2. -
      2. Confirm test count:
          -
        • Day 1 has 4 tests
          • -
        • Day 2 has 6 tests
          • -
        -
        3. -
      3. Confirm point totals:
          -
        • Day 1 total = 50
          • -
        • Day 2 total = 75
          • -
        -
        4. -
      4. Use a test student account to accept each assignment.
        5. -
      5. Trigger one known pass on each assignment.
        6. -
      6. Trigger one known fail on each assignment and confirm feedback appears.
        7. -
      7. Confirm rerun passes after fix.
        8. -
      8. Capture one screenshot of pass and one of fail for facilitator reference.
        9. +
      9. Paste the assignment description as usual.
        10. +
      10. Skip the autograding tests section. Leave it empty. Do not click Add test.
        11. +
      11. Save the assignment and copy the invite URL.
      -

      Fast Validation Scenarios

      -

      Day 1 quick checks

      -
        -
      • Pass check: open an issue, make a commit, open a PR with Closes #<issue-number>, ensure no conflict markers remain in docs/.
        • -
      • Fail check: open a PR without Closes, Fixes, or Resolves in the body.
        • -
      -

      Day 2 quick checks

      -
        -
      • Pass check: create one non-main commit, add a custom issue template with name: and description:, add an agent markdown file with frontmatter and required sections.
        • -
      • Fail check: create an agent file without a ## Responsibilities section.
        • -
      -

      Troubleshooting

      -

      Test stays red after student fix

      -
        -
      1. Confirm student pushed a new commit to the same PR branch.
        2. -
      2. Open PR checks and inspect the failing command output.
        3. -
      3. Verify required text is in the file body, not only in issue comments.
        4. -
      -

      Challenge 14 tests fail unexpectedly

      -
        -
      • Verify template filename is .yml.
        • -
      • Verify it is under .github/ISSUE_TEMPLATE.
        • -
      • Verify filename does not match challenge-*.yml, bonus-*.yml, or config.yml.
        • -
      -

      Challenge 16 section check fails

      -
        -
      • Ensure headings use markdown heading syntax (for example ## Responsibilities).
        • -
      • Ensure guardrail heading uses one accepted form:
          -
        • ## Guardrails
          • -
        • ## Limitations
          • -
        • ## Boundaries
          • -
        -
        • -
      -

      Keep This Guide Synced

      -

      If autograding JSON changes, update this file in the same pull request:

      -
        -
      • classroom/autograding-day1.json
        • -
      • classroom/autograding-day2.json
        • -
      +

      That is the entire change. Everything else in live-facilitation-flow.md still applies.

      +

      Verifying the checks work

      +

      Before sharing invite links, use a test student account to verify each workflow posts its comment. The procedure is in live-facilitation-flow.md (Phase 3: Verify Autograder Workflows).

      +

      Historical reference

      +

      The Classroom test-case definitions that used to live in classroom/autograding-day1.json and classroom/autograding-day2.json were deleted in May 2026 along with this workflow migration. The autograder workflow files (learning-room/.github/workflows/autograder-*.yml) are the only remaining source of truth for what each check verifies. Git history retains the old JSONs if you ever need to read them.