diff --git a/.github/scripts/__tests__/challenge-doc-consistency.test.js b/.github/scripts/__tests__/challenge-doc-consistency.test.js index 3c9a1a6..b45061c 100644 --- a/.github/scripts/__tests__/challenge-doc-consistency.test.js +++ b/.github/scripts/__tests__/challenge-doc-consistency.test.js @@ -10,6 +10,10 @@ const humanMatrixPath = path.join(repoRoot, 'classroom/HUMAN_TEST_MATRIX.md'); const facilitatorGuidePath = path.join(repoRoot, 'facilitator/FACILITATOR_GUIDE.md'); const learningRoomSolutionsIndexPath = path.join(repoRoot, 'learning-room/docs/solutions/README.md'); const skillsBonusScenariosPath = path.join(repoRoot, 'learning-room/docs/skills-bonus-scenarios.md'); +const learningRoomRoadmapPath = path.join(repoRoot, 'learning-room/docs/course-roadmap.md'); +const learningRoomReadmePath = path.join(repoRoot, 'learning-room/README.md'); +const studentGuidePath = path.join(repoRoot, 'learning-room/.github/STUDENT_GUIDE.md'); +const startHereTemplatePath = path.join(repoRoot, 'learning-room/.github/ISSUE_TEMPLATE/start-here-roadmap.yml'); function getChallengeTemplateFiles() { return fs @@ -151,3 +155,68 @@ test('skills-inspired bonus scenarios doc includes source attribution', () => { ); }); }); + +test('course roadmap exists and includes full student path guidance', () => { + assert.equal(fs.existsSync(learningRoomRoadmapPath), true, 'Missing learning-room/docs/course-roadmap.md'); + + const content = fs.readFileSync(learningRoomRoadmapPath, 'utf8'); + const requiredSnippets = [ + '## Day 1 Path (Challenges 1-9)', + '## Day 2 Path (Challenges 10-16)', + '## Bonus Path (A-E)', + 'Challenge 16: Build Your Agent (Capstone)', + 'Challenge Hub' + ]; + + requiredSnippets.forEach(snippet => { + assert.match( + content, + new RegExp(escapeRegex(snippet)), + `course-roadmap.md missing expected content: ${snippet}` + ); + }); +}); + +test('learning-room entry points link to the course roadmap', () => { + const readme = fs.readFileSync(learningRoomReadmePath, 'utf8'); + const studentGuide = fs.readFileSync(studentGuidePath, 'utf8'); + + assert.match( + readme, + /\[\*\*Follow the Full Course Roadmap →\*\*\]\(docs\/course-roadmap\.md\)/, + 'learning-room/README.md should link to course roadmap' + ); + + assert.match( + readme, + /\[\*\*View Available Challenges →\*\*\]\(\.\.\/docs\/CHALLENGES\.md\)/, + 'learning-room/README.md should link to canonical challenge hub path' + ); + + assert.match( + studentGuide, + /\[Course Roadmap\]\(\.\.\/docs\/course-roadmap\.md\)/, + 'learning-room/.github/STUDENT_GUIDE.md should link to course roadmap' + ); +}); + +test('start-here issue template exists and points to roadmap resources', () => { + assert.equal(fs.existsSync(startHereTemplatePath), true, 'Missing learning-room/.github/ISSUE_TEMPLATE/start-here-roadmap.yml'); + + const content = fs.readFileSync(startHereTemplatePath, 'utf8'); + const requiredReferences = [ + 'Start Here: Student Course Roadmap', + 'https://github.com/Community-Access/git-going-with-github/blob/main/learning-room/docs/course-roadmap.md', + 'https://github.com/Community-Access/git-going-with-github/blob/main/docs/CHALLENGES.md', + 'https://github.com/Community-Access/git-going-with-github/blob/main/learning-room/docs/solutions/README.md', + 'https://github.com/Community-Access/git-going-with-github/blob/main/learning-room/.github/STUDENT_GUIDE.md' + ]; + + requiredReferences.forEach(text => { + assert.match( + content, + new RegExp(escapeRegex(text)), + `start-here-roadmap.yml missing required reference: ${text}` + ); + }); +}); diff --git a/learning-room/.github/ISSUE_TEMPLATE/start-here-roadmap.yml b/learning-room/.github/ISSUE_TEMPLATE/start-here-roadmap.yml new file mode 100644 index 0000000..6905089 --- /dev/null +++ b/learning-room/.github/ISSUE_TEMPLATE/start-here-roadmap.yml @@ -0,0 +1,62 @@ +name: "Start Here: Student Course Roadmap" +description: First-stop guide for students to follow setup, challenges, and support resources in order. +title: "Start Here: Student Course Roadmap (@{username})" +labels: ["onboarding", "student"] +body: + - type: markdown + attributes: + value: | + ## Start Here: Student Course Roadmap + + Use this issue as your launch point for the full workshop path. + + ### Step 1: Open the Roadmap + + - [Course Roadmap](https://github.com/Community-Access/git-going-with-github/blob/main/learning-room/docs/course-roadmap.md) + + Follow the roadmap sections in order: + + 1. Before You Start + 2. Day 1 Path (Challenges 1-9) + 3. Day 2 Path (Challenges 10-16) + 4. Bonus Path (A-E) + + ### Step 2: Open the Challenge Hub + + - [Challenge Hub](https://github.com/Community-Access/git-going-with-github/blob/main/docs/CHALLENGES.md) + + The Challenge Hub is the canonical challenge reference. + + ### Step 3: Use Support Resources if You Get Stuck + + - [Solutions Index](https://github.com/Community-Access/git-going-with-github/blob/main/learning-room/docs/solutions/README.md) + - [Student Guide](https://github.com/Community-Access/git-going-with-github/blob/main/learning-room/.github/STUDENT_GUIDE.md) + + Try your challenge first, then use references to unblock. + + - type: checkboxes + id: readiness + attributes: + label: "Readiness checklist" + options: + - label: "I opened the Course Roadmap" + - label: "I opened the Challenge Hub" + - label: "I know where to find support resources" + + - type: textarea + id: first_step + attributes: + label: "Your first step" + description: "Write the first challenge you will complete and one goal for today." + placeholder: | + First challenge: Challenge 1 + Goal: Complete Day 1 through Challenge 3 + validations: + required: true + + - type: markdown + attributes: + value: | + ### Facilitator note + + This template is optional onboarding guidance and does not replace the official challenge issue progression. diff --git a/learning-room/.github/STUDENT_GUIDE.md b/learning-room/.github/STUDENT_GUIDE.md index 6320968..0fe8f47 100644 --- a/learning-room/.github/STUDENT_GUIDE.md +++ b/learning-room/.github/STUDENT_GUIDE.md @@ -334,7 +334,8 @@ Here's the support path: - [Pull Requests (Chapter 06)](https://github.com/Community-Access/git-going-with-github/blob/main/docs/06-working-with-pull-requests.md) - [Markdown Reference (Appendix C)](https://github.com/Community-Access/git-going-with-github/blob/main/docs/appendix-c-markdown-reference.md) - [Accessibility Standards (Appendix M)](https://github.com/Community-Access/git-going-with-github/blob/main/docs/appendix-m-accessibility-standards.md) -- [Challenge Hub](../docs/CHALLENGES.md) +- [Challenge Hub](../../docs/CHALLENGES.md) +- [Course Roadmap](../docs/course-roadmap.md) - [GitHub Help](https://docs.github.com/en) diff --git a/learning-room/README.md b/learning-room/README.md index dfc1260..0d4f84b 100644 --- a/learning-room/README.md +++ b/learning-room/README.md @@ -21,7 +21,7 @@ Everything in this repository is designed for learning. The files in `docs/` hav ## How to Contribute -1. Open the canonical challenge list: `docs/CHALLENGES.md` +1. Open the canonical challenge list: `../docs/CHALLENGES.md` 2. Find your assigned issue (Issues tab → filter by "Assignee: me" or search your username in issue title) 3. Claim the issue with a comment: `I'd like to try this!` 4. Read the issue description - it tells you which file to edit and what to fix @@ -36,7 +36,7 @@ Everything in this repository is designed for learning. The files in `docs/` hav 13. Merge when approved (the issue closes automatically) 14. Add a final issue comment with what you learned and your merged PR link -See the [workshop documentation](../../docs/) for full step-by-step guidance. +See the [workshop documentation](../docs/) for full step-by-step guidance. ## About the Automation Bot @@ -81,7 +81,8 @@ As you complete challenges, you'll: - **Earn badges** for specific achievements (Branch Builder, PR Pioneer, Conflict Resolver, and more) - **Celebrate milestones** (first challenge, Day 1 complete, all challenges complete) -[**View Available Challenges →**](docs/CHALLENGES.md) +[**View Available Challenges →**](../docs/CHALLENGES.md) +[**Follow the Full Course Roadmap →**](docs/course-roadmap.md) ## Stuck? Use Guided References diff --git a/learning-room/docs/course-roadmap.md b/learning-room/docs/course-roadmap.md new file mode 100644 index 0000000..e637149 --- /dev/null +++ b/learning-room/docs/course-roadmap.md @@ -0,0 +1,87 @@ +# Course Roadmap + +This roadmap guides you through the full workshop from setup to capstone. Follow it in order. + +## Quick Navigation + +1. [Before You Start](#before-you-start) +2. [Day 1 Path (Challenges 1-9)](#day-1-path-challenges-1-9) +3. [Day 2 Path (Challenges 10-16)](#day-2-path-challenges-10-16) +4. [Bonus Path (A-E)](#bonus-path-a-e) +5. [How to Use Support Resources](#how-to-use-support-resources) +6. [Completion Checklist](#completion-checklist) + +## Before You Start + +1. Read the [Setup Guide](setup-guide.md). +2. Open the [Challenge Hub](../../docs/CHALLENGES.md). +3. Keep the [Keyboard Shortcuts](keyboard-shortcuts.md) page open if useful. + +## Day 1 Path (Challenges 1-9) + +Goal: learn GitHub basics in the browser and complete your first merged pull request. + +1. Challenge 1: Find Your Way Around +2. Challenge 2: File Your First Issue +3. Challenge 3: Join the Conversation +4. Challenge 4: Branch Out +5. Challenge 5: Make Your Mark +6. Challenge 6: Open Your First PR +7. Challenge 7: Survive a Merge Conflict +8. Challenge 8: The Culture Layer +9. Challenge 9: Merge Day + +Expected Day 1 outcome: + +- You have opened and merged a pull request. +- You have participated in issue and PR collaboration. + +## Day 2 Path (Challenges 10-16) + +Goal: work locally, perform code review, and complete the capstone contribution. + +1. Challenge 10: Go Local +2. Challenge 11: Open a Day 2 PR +3. Challenge 12: Review Like a Pro +4. Challenge 13: AI as Your Copilot +5. Challenge 14: Template Remix +6. Challenge 15: Meet the Agents +7. Challenge 16: Build Your Agent (Capstone) + +Expected Day 2 outcome: + +- You can run a local Git workflow end to end. +- You can give and respond to code review feedback. +- You can complete a capstone agent contribution. + +## Bonus Path (A-E) + +Use bonus scenarios after core challenges are complete. + +1. Bonus A: Improve an Existing Agent +2. Bonus B: Document Your Journey +3. Bonus C: Create a Group Challenge +4. Bonus D: Notification Mastery +5. Bonus E: Explore Git History Visually + +For optional advanced practice adapted from GitHub Skills, see [Skills-Inspired Bonus Scenarios](skills-bonus-scenarios.md). + +## How to Use Support Resources + +Use support in this order: + +1. Re-read your current challenge issue instructions. +2. Check the [Solutions Index](solutions/README.md). +3. Ask for help in your issue or PR comments. +4. Ask your facilitator. + +## Completion Checklist + +Use this list to track your full journey: + +- Completed all Day 1 challenges (1-9) +- Completed all Day 2 challenges (10-16) +- Completed capstone challenge (16) +- Optional: completed bonus challenges (A-E) + +When in doubt, return to the [Challenge Hub](../../docs/CHALLENGES.md). It is the canonical challenge reference.