diff --git a/docs/06-working-with-pull-requests.md b/docs/06-working-with-pull-requests.md index f839865f..23eb1abb 100644 --- a/docs/06-working-with-pull-requests.md +++ b/docs/06-working-with-pull-requests.md @@ -863,6 +863,7 @@ gh pr create --title "Your title" --body "Description" 2. A "Compare & pull request" banner may appear (if you recently pushed) - activate it 3. OR: Navigate to Pull Requests tab → "New pull request" 4. Choose your base branch (what to merge into) and compare branch (your changes) +5. Activate the **Create pull request** button. It sits between the branch choosers and the diff, and the title and description form appears only after you activate it. Use the button quick navigation key (B in NVDA and JAWS browse mode) or search the page for "Create pull request". The comparison preview can read as very long because it includes unchanged context lines - the form is above it, not below it. diff --git a/html/docs/06-working-with-pull-requests.html b/html/docs/06-working-with-pull-requests.html index 8024c072..32c5ca4f 100644 --- a/html/docs/06-working-with-pull-requests.html +++ b/html/docs/06-working-with-pull-requests.html @@ -1149,6 +1149,7 @@

From a fork or feature branch

  • A "Compare & pull request" banner may appear (if you recently pushed) - activate it
  • OR: Navigate to Pull Requests tab → "New pull request"
  • Choose your base branch (what to merge into) and compare branch (your changes)
    • +
  • Activate the Create pull request button. It sits between the branch choosers and the diff, and the title and description form appears only after you activate it. Use the button quick navigation key (B in NVDA and JAWS browse mode) or search the page for "Create pull request". The comparison preview can read as very long because it includes unchanged context lines - the form is above it, not below it.
    • diff --git a/html/search-index.json b/html/search-index.json index 0ab64273..4509b7b5 100644 --- a/html/search-index.json +++ b/html/search-index.json @@ -461,12 +461,6 @@ "url": "docs/CHALLENGES.html", "body": "Challenge Hub Welcome to the Challenge Hub - your guide to all 16 core challenges and 5 bonus challenges. The challenges are the practice path for the course. Each one asks you to do a small piece of real GitHub work, leave evidence of what you did, and then close the issue so the next challenge can open. The goal is not speed. The goal is to build a contributor rhythm you can trust: orient yourself, make the move, verify the result, and ask for help with clear facts when something feels off. Prefer the exact issue-style flow? Open the consolidated issue walkthrough: Issue-Style Challenge Walkthrough . How Challenges Work Start in your private Learning Room repository, not in the public curriculum repository. Open the Issues tab, find the challenge issue assigned to you, and read the issue body before acting. Each issue explains the task, the evidence prompt, and any buddy check or automated check that applies. When a challenge asks for evidence, post it as a comment on that challenge issue. Evidence can be a link, a short reflection, the name of a branch, a pull request number, or a note about what you tried and what happened. After you post the evidence, close the challenge issue. The Student Progression Bot uses that closed issue as the signal to open the next challenge. Every challenge below includes a reference solution. Treat those files as worked examples, not answer keys. Your exact branch name, issue number, wording, or file count may differ. What matters is whether you practiced the skill and can explain the result. Day 1: You Belong Here (Challenges 1-9) Challenge 1: Find Your Way Around Chapters: Ch02-04 | Evidence: Comment This first challenge is about orientation. Before you edit anything, you learn how a repository is organized: where the Code tab lives, where Issues live, how the file tree behaves, and how the README gives a project its front door. What to do: Find the Code tab and count the files or folders in the repository root Open the Issues tab and identify at least one issue or confirm the tab exists Navigate to docs/welcome.md and read the opening paragraph Find the repository description and the rendered README Evidence to post: Describe what you found and name one navigation shortcut or screen reader technique that helped. Compare your result with the Challenge 1 solution reference when you want a second view of the same exploration path. Challenge 2: File Your First Issue Chapter: Ch05 | Evidence: Comment Issues are how maintainers turn observations into trackable work. In this challenge, you find a small TODO in the Learning Room and write an issue that another person could understand without being in the room with you. What to do: Open docs/welcome.md and search for TODO Create a new issue with a specific title Explain what needs to change, where it is, and why the change would help Evidence to post: Link to the issue you created and include one sentence about why your title is clear. If you want to compare tone and structure, read the Challenge 2 solution reference . Challenge 3: Join the Conversation Chapter: Ch05 | Evidence: Comment Open source is conversation as much as code. This challenge teaches you how to participate in an issue thread with an @mention, a reaction, and a comment that moves the work forward. What to do: Find your buddy's Challenge 2 issue or a facilitator-provided peer simulation issue Leave a meaningful comment with an @mention Add a reaction to the original issue or a helpful comment Evidence to post: Link to your comment and describe what made it useful, kind, or specific. The Challenge 3 solution reference shows one way to make a short comment feel genuinely collaborative. Challenge 4: Branch Out Chapter: Ch06 | Evidence: Comment A branch is a safe workspace. It lets you try a change without rewriting the main version of the project. In this challenge, you create your own branch and confirm that you know where your work will happen. What to do: Find the branch selector on the Code tab Create a branch named learn/YOUR-USERNAME from main Confirm the branch selector now names your branch Evidence to post: Write the branch name you created and how you confirmed you were on it. Use the Challenge 4 solution reference if you want to check your branch mental model. Challenge 5: Make Your Mark Chapter: Ch06 | Evidence: Comment This is your first small content change. You edit a file, replace a TODO with real text, and commit the change with a message that explains what happened. What to do: Switch to your learn/YOUR-USERNAME branch Edit docs/welcome.md to replace the TODO with useful content Write a commit message that explains the change in plain language Evidence to post: Share your commit message and the file you edited. For a worked example of a focused commit, compare with the Challenge 5 solution reference . Challenge 6: Open Your First Pull Request Chapter: Ch06 | Evidence: Comment A pull request is the conversation around a proposed change. It lets" }, - { - "id": "docs/06-working-with-pull-requests.html", - "title": "Working with Pull Requests", - "url": "docs/06-working-with-pull-requests.html", - "body": "Working with Pull Requests Listen to Episode 6: Working with Pull Requests - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Related appendices: Appendix C: Markdown Reference | Appendix B: Screen Reader Cheat Sheet Authoritative sources: GitHub Docs: About pull requests | GitHub Accessibility Guide: Pull Requests | GitHub Accessibility Lab: CLI Guide Creating, Reviewing, and Merging Pull Requests with a Screen Reader See also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. Pull requests are where your work becomes a contribution. This guide takes you through the full pull request workflow - from opening one to participating in review - using only your keyboard and screen reader. Official GitHub Accessibility Guide: GitHub publishes an NVDA-focused guide for working with pull requests using a screen reader at Using GitHub Pull Requests with a Screen Reader . This chapter covers the same material with additional perspectives (VoiceOver, low vision, CLI) and workshop-specific challenges. Use the official guide as a companion reference. Screen reader note - New Files Changed Experience: This guide uses GitHub's improved Files Changed experience, which adds proper ARIA landmark structure to the Files Changed tab, including the file tree and diff navigation. This feature may already be active for your account - it has been broadly rolled out and may no longer appear as a Feature Preview toggle at all. To verify: Activate the User Menu button (top-right of any GitHub page) → activate "Feature preview" → scan the list for "New Files Changed Experience" : If listed and the toggle announces "Pressed" (or "Disable" ) - already enabled, no action needed If listed but not Pressed (or "Enable" ) - activate the toggle to enable it If not listed at all - the feature has graduated to the standard interface; it is active automatically Full step-by-step instructions with per-screen-reader commands are in Pre-Workshop Setup, Step 4 . Browse vs Focus Mode (NVDA): Use Browse Mode (the default) for reading PR conversations, navigating headings, and reviewing diffs. Switch to Focus Mode ( NVDA+Space ) only when you need to type in comment boxes or search fields. Switch back to Browse Mode to resume navigation. Maximize your browser window for consistent landmark layout. Workshop Recommendation (Chapter 6) Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions. Challenge count: 3 Time per challenge: under 10 minutes each Evidence: PR metadata, bot checks, and merged issue linkage Pattern: small change -> linked PR -> green checks Chapter 6 Challenge Set Create one small branch change - edit a practice file on a new branch. Open a linked PR - use the PR template and include Closes #XX . Pass required checks - respond to bot feedback until all required checks pass. CLI getting-started principles for pull request work For reliable PR workflows in the terminal: Check current branch before pushing ( git branch --show-current ). Keep PR scope small (one focused change per branch). Confirm issue linkage in plain text ( Closes #<number> ). Validate check status after each push ( gh pr checks ). Prefer documented command options only ( gh pr --help ). Branch guidance for Chapter 6: This is the first chapter where you edit files and create branches. Use one of these two paths: Web editor (recommended for beginners): When you edit a file on GitHub.com and click "Propose changes," GitHub creates a branch for you automatically. Name it fix/yourname-issueXX (for example, fix/maria-issue42 ). Local Git (if you cloned in Block 0): Create a feature branch with git checkout -b fix/yourname-issueXX from main . See the "Local Git Alternative" section below for the full command sequence. Do not reuse your learn/<username> branch for this short exercise unless your facilitator tells you to. Chapter 6 works best with a short-lived feature branch such as fix/yourname-issueXX , because it teaches the pull request loop without mixing multiple challenges on one branch. Challenge 6.1 Step-by-Step: Create One Small Branch Change Goal: Edit one of the practice files and save your change on a new branch. Where you are working: your Learning Room repository on GitHub.com, using the web editor. Before you start: Open your assigned Chapter 6.1 challenge issue (the one titled "Chapter 6.1: Create One Small Branch Change (@yourname)"). The issue description tells you which file to edit and what to fix. The Learning Room has three practice files with intentional problems. Your assigned issue points you to one of them: The following table summarizes the practice files in the learning-room, what each file contains, and the type of issues to look for. File What it contains" - }, { "id": "docs/11-vscode-interface.html", "title": "VS Code: Interface and Setup", @@ -485,6 +479,12 @@ "url": "docs/appendix-j-cloud-editors.html", "body": "Appendix J: GitHub Codespaces Listen to Episode 31: GitHub Codespaces - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 01: Choose Your Tools | Also relevant: Chapter 11 Authoritative source: GitHub Docs: Codespaces Cloud Development Environments - Accessibility Guide GitHub Codespaces gives you a full VS Code development environment in your browser or connected to your local VS Code, running on a cloud machine. For screen reader users, this means a consistent, pre-configured environment with no local setup required. Table of Contents What Is GitHub Codespaces? Creating a Codespace Codespace Environments Accessibility in Codespaces Screen Reader Configuration Keyboard Shortcuts in Codespaces Managing Your Codespaces Dotfiles and Persistent Configuration Codespaces vs GitHub.dev Common Issues and Workarounds 1. What Is GitHub Codespaces? A Codespace is a cloud-hosted development environment. When you open one, GitHub provisions a virtual machine, clones your repository into it, and connects it to a VS Code interface - either in your browser or via your local VS Code Desktop. Why this matters for accessibility No local installation of tools, compilers, or language runtimes required Your screen reader and OS settings stay on your machine; only the editor runs in the cloud VS Code's full accessibility features (audio cues, screen reader optimized mode, diff viewer) are available The environment is identical for every workshop participant - facilitators can reproduce issues reliably Free tier: GitHub provides a monthly free allowance of Codespace hours for personal accounts. Workshop usage typically falls well within the free tier. Learning Cards: Cloud Editors Overview Screen reader users Codespaces gives you a full VS Code interface with terminal access -- your screen reader and OS settings stay on your local machine The browser-based editor activates screen reader optimized mode automatically if your OS signals a screen reader is running Connect a Codespace to your local VS Code Desktop (via the Codespaces extension) for the most familiar screen reader experience Low vision users Settings Sync carries your font size, theme, and zoom preferences from local VS Code into Codespaces automatically The browser-based editor supports Ctrl+= / Ctrl+- zoom just like desktop VS Code Use a high-contrast VS Code theme -- it applies identically in the cloud editor Sighted users Press . on any GitHub repository page to open it instantly in github.dev (browser editor, no terminal) Codespaces provisions a full VM with terminal -- use it when you need to run code, not just edit The default 2-core machine is sufficient for workshop exercises; upgrade only for heavy builds 2. Creating a Codespace From a Repository Page Navigate to the repository on GitHub Press the Code button (keyboard shortcut: there is no direct shortcut - Tab to the button) In the panel that opens, choose the Codespaces tab Activate Create codespace on main (or your branch name) The Codespace opens in a new browser tab after provisioning (typically 30-60 seconds) From the Codespaces Dashboard Go to github.com/codespaces Activate New codespace Use the search field to find your repository Choose a branch, machine type, and region Activate Create codespace Machine Types Type CPU RAM Best for 2-core 2 vCPU 8 GB General development, documentation 4-core 4 vCPU 16 GB Builds, tests, moderate workloads 8-core 8 vCPU 32 GB Heavy builds, multiple services For workshop exercises, the default 2-core machine is sufficient. 3. Codespace Environments Browser (VS Code for the Web) The Codespace opens directly in your browser as a fully functional VS Code interface. Works in Chrome, Edge, Firefox, and Safari Screen reader support varies slightly by browser - Chrome and Edge have the most consistent behavior with NVDA and JAWS No installation needed Some VS Code extensions are not available in the browser version Local VS Code Desktop If you prefer your local VS Code setup with your extensions and settings: Install the GitHub Codespaces extension in VS Code Sign in to GitHub in VS Code Open the Command Palette ( Ctrl+Shift+P / Cmd+Shift+P ) Run Codespaces: Connect to Codespace Select an existing Codespace or create a new one When connected via local VS Code, your screen reader interacts with your local VS Code installation - all your familiar settings apply. 4. Accessibility in Codespaces Screen Reader Optimized Mode When VS Code detects a screen reader, it automatically activates Screen Reader Optimized mode. You can verify or toggle it manually: Open the Command Palette ( Ctrl+Shift+P ) Search for Toggle Screen Reader Accessibility Mode Press Enter to activate In this mode: The editor reads content line by line instead of character by character Diff views are rendered as accessible text comparisons Inline suggestions from Copilot are announced on a key" }, + { + "id": "docs/06-working-with-pull-requests.html", + "title": "Working with Pull Requests", + "url": "docs/06-working-with-pull-requests.html", + "body": "Working with Pull Requests Listen to Episode 6: Working with Pull Requests - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Related appendices: Appendix C: Markdown Reference | Appendix B: Screen Reader Cheat Sheet Authoritative sources: GitHub Docs: About pull requests | GitHub Accessibility Guide: Pull Requests | GitHub Accessibility Lab: CLI Guide Creating, Reviewing, and Merging Pull Requests with a Screen Reader See also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. Pull requests are where your work becomes a contribution. This guide takes you through the full pull request workflow - from opening one to participating in review - using only your keyboard and screen reader. Official GitHub Accessibility Guide: GitHub publishes an NVDA-focused guide for working with pull requests using a screen reader at Using GitHub Pull Requests with a Screen Reader . This chapter covers the same material with additional perspectives (VoiceOver, low vision, CLI) and workshop-specific challenges. Use the official guide as a companion reference. Screen reader note - New Files Changed Experience: This guide uses GitHub's improved Files Changed experience, which adds proper ARIA landmark structure to the Files Changed tab, including the file tree and diff navigation. This feature may already be active for your account - it has been broadly rolled out and may no longer appear as a Feature Preview toggle at all. To verify: Activate the User Menu button (top-right of any GitHub page) → activate "Feature preview" → scan the list for "New Files Changed Experience" : If listed and the toggle announces "Pressed" (or "Disable" ) - already enabled, no action needed If listed but not Pressed (or "Enable" ) - activate the toggle to enable it If not listed at all - the feature has graduated to the standard interface; it is active automatically Full step-by-step instructions with per-screen-reader commands are in Pre-Workshop Setup, Step 4 . Browse vs Focus Mode (NVDA): Use Browse Mode (the default) for reading PR conversations, navigating headings, and reviewing diffs. Switch to Focus Mode ( NVDA+Space ) only when you need to type in comment boxes or search fields. Switch back to Browse Mode to resume navigation. Maximize your browser window for consistent landmark layout. Workshop Recommendation (Chapter 6) Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions. Challenge count: 3 Time per challenge: under 10 minutes each Evidence: PR metadata, bot checks, and merged issue linkage Pattern: small change -> linked PR -> green checks Chapter 6 Challenge Set Create one small branch change - edit a practice file on a new branch. Open a linked PR - use the PR template and include Closes #XX . Pass required checks - respond to bot feedback until all required checks pass. CLI getting-started principles for pull request work For reliable PR workflows in the terminal: Check current branch before pushing ( git branch --show-current ). Keep PR scope small (one focused change per branch). Confirm issue linkage in plain text ( Closes #<number> ). Validate check status after each push ( gh pr checks ). Prefer documented command options only ( gh pr --help ). Branch guidance for Chapter 6: This is the first chapter where you edit files and create branches. Use one of these two paths: Web editor (recommended for beginners): When you edit a file on GitHub.com and click "Propose changes," GitHub creates a branch for you automatically. Name it fix/yourname-issueXX (for example, fix/maria-issue42 ). Local Git (if you cloned in Block 0): Create a feature branch with git checkout -b fix/yourname-issueXX from main . See the "Local Git Alternative" section below for the full command sequence. Do not reuse your learn/<username> branch for this short exercise unless your facilitator tells you to. Chapter 6 works best with a short-lived feature branch such as fix/yourname-issueXX , because it teaches the pull request loop without mixing multiple challenges on one branch. Challenge 6.1 Step-by-Step: Create One Small Branch Change Goal: Edit one of the practice files and save your change on a new branch. Where you are working: your Learning Room repository on GitHub.com, using the web editor. Before you start: Open your assigned Chapter 6.1 challenge issue (the one titled "Chapter 6.1: Create One Small Branch Change (@yourname)"). The issue description tells you which file to edit and what to fix. The Learning Room has three practice files with intentional problems. Your assigned issue points you to one of them: The following table summarizes the practice files in the learning-room, what each file contains, and the type of issues to look for. File What it contains" + }, { "id": "agents/image alt text agent/agents/image-alt-text.agent.html", "title": "image-alt-text.agent", @@ -2363,16 +2363,16 @@ "url": "REGISTER.html", "body": "The Adventure Gate: Student Opt-In Back to Home | Support Hub | Pre-Workshop Setup Guide Join the next GIT Going with GitHub cohort Welcome, traveler. I am your Grey Wizard Mentor at the gate, here to welcome you to your Git and GitHub adventure. Learn online from anywhere Remote learners follow the workshop as a fully online, self-paced experience . Every challenge, episode, and reference document is published on the public site, available to read or listen to at any time. You will work in your own GitHub learning room with mentors and automation agents supporting you through issues and discussions. No travel, no special software -- just a browser, a keyboard, and your assistive tech of choice. Begin at your own pace and open a discussion whenever you need a mentor. A magical welcome My role is simple: set expectations, light the path when Git gets foggy, and help you move from uncertain first steps to confident collaboration. In class, we travel through short quests, clear checkpoints, and practical support from mentors and automation agents. Beyond class, I remain with you through the Support Hub, progression bots, and challenge feedback so your learning continues after the workshop ends. You only need one path to begin. Status Open for student opt-in Current confirmed registrations Loading... Cost Free Form Single enrollment form with automated confirmation and guided next steps One path to begin Sign in to your GitHub account . Open the enrollment form in a new tab. Answer the five quick prompts. Submit the form and open the new issue page that appears. Stay on that issue page until the automation comment posts your learning room link and next steps. Reply ack , then close the enrollment issue as Challenge 0 . Begin the Adventure (opens in new tab) How to fill the form (wizard tips) Use this quick spellbook so your form is accepted on the first try: Full Name: enter the name you want facilitators to call you (example: Jane Doe ). Email Address: use the best address for workshop updates (example: jane.doe@example.com ). Experience dropdowns: pick the option that feels true today. There is no wrong level. Course goals: write 1 to 3 short sentences about what you want to learn. Final check: confirm everything looks right, then click Submit new issue once. Your GitHub username is detected automatically from the account that submits the issue. If your goals box is blank, try this starter line: I want to feel confident using Git and GitHub in real projects. If you do not receive an email notification, refresh your submitted issue page directly to see the latest automation comment. What happens automatically Duplicate submissions are handled automatically. Registration is currently unlimited. Enrollment submissions are processed and public issue bodies are redacted after automation runs. Your learning room repository is provisioned automatically after enrollment. Challenge progression automation picks up as you close issues and open pull requests. Enrollment issues stay open until the student replies ack and closes the issue as Challenge 0. Important note Registration issues are public because this repository is public. Need help? File a support issue Join Support Hub Discussions A Community Access initiative. Authoritative Sources Use these official references when you need the current source of truth for facts in this chapter. GitHub Docs, home GitHub Changelog GitHub Discussions docs GitHub Gists docs Section-Level Source Map Use this map to verify facts for each major section in this file. Join the next GIT Going with GitHub cohort: GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs , About Git A magical welcome: GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs One path to begin: GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs , Workflow syntax for GitHub Actions How to fill the form (wizard tips): GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs , Issue forms syntax for GitHub What happens automatically: GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs Important note: GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs Need help?: GitHub Docs, home , GitHub Changelog , GitHub Discussions docs , GitHub Gists docs" }, - { - "id": "work.html", - "title": "Work.md", - "url": "work.html", - "body": "Work.md Consolidated walkthrough generated from the challenge issue templates in learning-room/.github/ISSUE_TEMPLATE/ . Do not edit this file manually. Run npm run build:html (or node scripts/generate-work-md.js ) to regenerate. Core challenges Challenge 1: Find Your Way Around Source template: challenge-01-find-your-way.yml Chapters: Ch02: Understanding GitHub | Ch03: Navigating Repositories | Ch04: The Learning Room What you will do: Explore this learning-room repository like a scavenger hunt. You will navigate tabs, the file tree, read key files, and find landmarks. Step-by-step scavenger hunt Task 1: Count files in the root Make sure you are on the Code tab (click it at the top) Look at the file/folder list Count how many items are showing (stop before the first folder) Write down this number Task 2: Find an open issue Click the Issues tab Look for issues with a green Open label Click on one to read it Write down its title Task 3: Read welcome.md Click the Code tab Look for a folder named docs/ Click to open it Find welcome.md and click it Read the first paragraph (the opening sentence) Write down what it says Task 4: Find the repo description Go to the Code tab Look at the top-right area - you should see a text description under the repo name This is the "About" section Write down what it says Task 5: Read the README On the Code tab, scroll down to find README.md Click it to open Find the section that says "Who this workshop is for" Write down the answer Task 6: Check the About section On the Code tab, look at the right sidebar You should see a section labeled "About" with repo information Write down what you see there Your evidence (fill in when closing this issue): 1. I found ___ files in the root of the repository. 2. The open issue I found was titled "___". 3. The first paragraph of welcome.md says... 4. The repository description is... 5. The README says this workshop is for... 6. The About section shows... Peer simulation check After you submit your evidence, open the Peer Simulation: Welcome Link Needs Context issue in this repository and leave an encouraging comment or reaction. If your facilitator gave you access to a real buddy repository, you may use your buddy's issue instead. If you get stuck Symptom Try this I cannot find the tabs Look for a horizontal navigation bar below the repository name. Screen reader users: navigate by heading level 2 or use the landmark navigation. I cannot find docs/welcome.md On the Code tab, look for a folder called docs . Select it, then select welcome.md . I am not sure what counts as evidence Any description of what you found works. There are no wrong answers in a scavenger hunt. I finished but want to check my work View the reference solution Challenge 2: File Your First Issue Source template: challenge-02-first-issue.yml Chapter: Ch05: Working with Issues What you will do: Find a TODO comment in docs/welcome.md , then file an issue describing the problem with a clear title and description. Instructions Open docs/welcome.md and look for a line that contains TODO -- this marks something that needs fixing. Go to the Issues tab and select New issue . Write a clear, descriptive title (not just "Fix TODO"). In the description, use this required format: - What: what needs to change - Where: where the problem is (must include docs/welcome.md ) - Why: why the change matters - Mention the exact TODO text you found Required format (checked automatically) Use this structure in your issue description: What: Replace the placeholder TODO with real welcome text. Where: docs/welcome.md, intro section. Why: New contributors need clear context when they open the file. TODO found: TODO: Add a short workshop welcome paragraph. ```text #### What makes a good issue title? | Instead of this | Write this | |---|---| | Fix TODO | Fix missing workshop description in welcome.md | | Bug | welcome.md TODO placeholder needs real content | | Update file | Replace TODO in welcome.md intro section with actual welcome text | --- **Your evidence** (fill in when closing this issue): ```text Issue URL: https://github.com/... I found a TODO in docs/welcome.md that said... My issue title was... Peer simulation check Open the Peer Simulation: Welcome Link Needs Context issue and leave a comment: Is the title clear? Would you know what needs fixing just from reading the title? If your facilitator gave you access to a real buddy repository, you may review your buddy's issue instead. If you get stuck Symptom Try this I cannot find the TODO Open docs/welcome.md and use your browser's find feature (Ctrl+F or Cmd+F) to search for "TODO". I am not sure what to write in the description Describe the problem as if you are explaining it to someone who has never seen the file. The New issue button is not visible Make sure you are on the Issues tab. If issues are disabled, ask your facilitator. I finished but want to check my work View t" - }, { "id": "GO-LIVE-QA-GUIDE.html", "title": "Git Going with GitHub Go-Live QA Guide", "url": "GO-LIVE-QA-GUIDE.html", "body": "Git Going with GitHub Go-Live QA Guide Status note (2026-07): GitHub Classroom and the scripts/classroom/ PowerShell tooling were removed; provisioning is now the hybrid pipeline in .github/scripts/provisioning/ , and peer simulation seeding happens automatically via the Student Progression Bot in each learning room. Interpret scripts/classroom/*.ps1 steps below as the Student Progression Bot workflow dispatch (inputs start_challenge , assignee ). Use this guide before a cohort is opened to learners. It is the release gate for curriculum content, GitHub Classroom deployment, Learning Room automation, accessibility, and human test coverage. Podcast and LLM-generation QA is tracked here as non-blocking unless a podcast release is explicitly in scope. For end-to-end execution details, use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md as the operator procedure. This guide is the release gate summary; the runbook is the required execution playbook. The goal is simple: a facilitator should be able to create a classroom, seed test repositories, complete every challenge path, validate every generated artifact, and know exactly what remains before students arrive. Important Note: Email and Notification Handling This curriculum does NOT depend on email notifications. Account verification emails (GitHub signup, email confirmation) are required by GitHub and are outside our control Notification emails (activity updates, mentions, assignments) are completely optional All challenges complete successfully using only GitHub's web notification inbox at github.com/notifications Students can disable email notifications in their GitHub settings after account setup—this will NOT break the workshop Chapter 10 (Notifications) focuses on managing the web notification inbox, not email delivery If a student's email delivery is problematic, delayed, or filtered by their ISP, they can still complete all challenges and exercises without any impact. Instructors should inform students that they can check github.com/notifications anytime instead of waiting for emails. Release Decision Do not mark a cohort ready until all required items in this section are complete. Automated tests pass locally. HTML documentation builds from the current Markdown sources. Learning Room source has been synced to Community-Access/learning-room-template and merged to main (or validated as no-change). Template smoke validation from Community-Access/learning-room-template succeeded before assignment publishing. Template freshness proof confirms smoke repo content matches latest merged template sync changes. Git diff whitespace check has no actual whitespace or conflict-marker errors. Registration deployment gate completed (issue form template, workflow enablement, required labels, and optional classroom automation settings). Registration comment flow is assignment-link based (no org invite dependency). Registration form smoke test passed on 2026-05-14 (submission accepted, redacted, labeled, and support routing confirmed). Support Hub is provisioned and publicly accessible at Community-Access/support . Registration confirmation and help pathways route support requests to Support Hub issues/discussions. Registration issue form template and labels are configured ( workshop-registration.yml , registration , duplicate , waitlist ). Smoke repo confirms all required workflow files are present (PR validation, content validation, progression, skills progression, and all autograder workflows: autograder-issue-filed.yml , autograder-branch-commit.yml , autograder-pr-link.yml , autograder-conflicts.yml , autograder-local-commit.yml , autograder-template.yml , autograder-capstone.yml , autograder-watchdog.yml ). Day 1 Classroom assignment has been created from the current Learning Room template. Day 2 Classroom assignment has been created from the current Learning Room template. A test student account accepted the Day 1 invite and received a private repository. A test student account accepted the Day 2 invite and received a private repository. A test student can reply ack , then close the enrollment issue as Challenge 0 and retain expected workflow state. A test student can reply day1-complete and receive Day 2 release comment. Challenge 1 can be seeded and completed. Challenge 10 can be seeded and completed. Gandalf posts PR feedback on a test pull request. Student Progression Bot creates the next challenge when a challenge issue is closed. Autograder workflows run inside the student repo and post pass/fail comments on the relevant issues and PRs. (Classroom UI test cases are intentionally not configured -- see admin/classroom/autograding-setup.md .) Peer simulation artifacts can be seeded and used for review practice. Human testers completed the Day 1, Day 2, bonus, accessibility, and content-review passes below. Challenge tracking log includes explicit status and evidence for Challenges 1-16 and Bonus A-E. Challenge reliability matrix includes happy path, failure path, " + }, + { + "id": "work.html", + "title": "Work.md", + "url": "work.html", + "body": "Work.md Consolidated walkthrough generated from the challenge issue templates in learning-room/.github/ISSUE_TEMPLATE/ . Do not edit this file manually. Run npm run build:html (or node scripts/generate-work-md.js ) to regenerate. Core challenges Challenge 1: Find Your Way Around Source template: challenge-01-find-your-way.yml Chapters: Ch02: Understanding GitHub | Ch03: Navigating Repositories | Ch04: The Learning Room What you will do: Explore this learning-room repository like a scavenger hunt. You will navigate tabs, the file tree, read key files, and find landmarks. Step-by-step scavenger hunt Task 1: Count files in the root Make sure you are on the Code tab (click it at the top) Look at the file/folder list Count how many items are showing (stop before the first folder) Write down this number Task 2: Find an open issue Click the Issues tab Look for issues with a green Open label Click on one to read it Write down its title Task 3: Read welcome.md Click the Code tab Look for a folder named docs/ Click to open it Find welcome.md and click it Read the first paragraph (the opening sentence) Write down what it says Task 4: Find the repo description Go to the Code tab Look at the top-right area - you should see a text description under the repo name This is the "About" section Write down what it says Task 5: Read the README On the Code tab, scroll down to find README.md Click it to open Find the section that says "Who this workshop is for" Write down the answer Task 6: Check the About section On the Code tab, look at the right sidebar You should see a section labeled "About" with repo information Write down what you see there Your evidence (fill in when closing this issue): 1. I found ___ files in the root of the repository. 2. The open issue I found was titled "___". 3. The first paragraph of welcome.md says... 4. The repository description is... 5. The README says this workshop is for... 6. The About section shows... Peer simulation check After you submit your evidence, open the Peer Simulation: Welcome Link Needs Context issue in this repository and leave an encouraging comment or reaction. If your facilitator gave you access to a real buddy repository, you may use your buddy's issue instead. If you get stuck Symptom Try this I cannot find the tabs Look for a horizontal navigation bar below the repository name. Screen reader users: navigate by heading level 2 or use the landmark navigation. I cannot find docs/welcome.md On the Code tab, look for a folder called docs . Select it, then select welcome.md . I am not sure what counts as evidence Any description of what you found works. There are no wrong answers in a scavenger hunt. I finished but want to check my work View the reference solution Challenge 2: File Your First Issue Source template: challenge-02-first-issue.yml Chapter: Ch05: Working with Issues What you will do: Find a TODO comment in docs/welcome.md , then file an issue describing the problem with a clear title and description. Instructions Open docs/welcome.md and look for a line that contains TODO -- this marks something that needs fixing. Go to the Issues tab and select New issue . Write a clear, descriptive title (not just "Fix TODO"). In the description, use this required format: - What: what needs to change - Where: where the problem is (must include docs/welcome.md ) - Why: why the change matters - Mention the exact TODO text you found Required format (checked automatically) Use this structure in your issue description: What: Replace the placeholder TODO with real welcome text. Where: docs/welcome.md, intro section. Why: New contributors need clear context when they open the file. TODO found: TODO: Add a short workshop welcome paragraph. ```text #### What makes a good issue title? | Instead of this | Write this | |---|---| | Fix TODO | Fix missing workshop description in welcome.md | | Bug | welcome.md TODO placeholder needs real content | | Update file | Replace TODO in welcome.md intro section with actual welcome text | --- **Your evidence** (fill in when closing this issue): ```text Issue URL: https://github.com/... I found a TODO in docs/welcome.md that said... My issue title was... Peer simulation check Open the Peer Simulation: Welcome Link Needs Context issue and leave a comment: Is the title clear? Would you know what needs fixing just from reading the title? If your facilitator gave you access to a real buddy repository, you may review your buddy's issue instead. If you get stuck Symptom Try this I cannot find the TODO Open docs/welcome.md and use your browser's find feature (Ctrl+F or Cmd+F) to search for "TODO". I am not sure what to write in the description Describe the problem as if you are explaining it to someone who has never seen the file. The New issue button is not visible Make sure you are on the Issues tab. If issues are disabled, ask your facilitator. I finished but want to check my work View t" } ] diff --git a/html/work.html b/html/work.html index 2f61f0c6..a38f0967 100644 --- a/html/work.html +++ b/html/work.html @@ -591,10 +591,11 @@

    Instructions

    1. Go to the Pull requests tab.
    2. Select New pull request.
      3. -
    3. Set base to main and compare to learn/YOUR-USERNAME.
      4. +
    4. Set base to main and compare to learn/YOUR-USERNAME. The page shows a preview of your commits and changed files. This preview can read as very long because it includes unchanged context lines around each change - that is normal.
      5. +
    5. Activate the Create pull request button. It sits between the branch choosers and the diff, and the title and description fields do not appear until you activate it. With a screen reader, use the button quick navigation key (B in NVDA and JAWS browse mode) or search the page for "Create pull request".
    6. Write a descriptive PR title.
    7. In the PR description, include Closes #XX (replace XX with your Challenge 2 issue number). This automatically links and closes the issue when the PR is merged.
      8. -
    8. Submit the pull request.
      9. +
    9. Submit by activating the Create pull request button below the description field.

    PR description template

    Use this structure for your PR description:

    @@ -638,6 +639,10 @@

    If you get stuck

    Make sure you are on the Pull requests tab. The button is near the top-right. +The diff appears but there is no title or description field +The compare page shows only a preview at first. Activate the Create pull request button between the branch choosers and the diff to open the form. + + It says "There isn't anything to compare" Make sure your branch has at least one commit that differs from main. Did you commit to the right branch? diff --git a/learning-room/.github/ISSUE_TEMPLATE/challenge-06-first-pr.yml b/learning-room/.github/ISSUE_TEMPLATE/challenge-06-first-pr.yml index fa62b897..8b79369a 100644 --- a/learning-room/.github/ISSUE_TEMPLATE/challenge-06-first-pr.yml +++ b/learning-room/.github/ISSUE_TEMPLATE/challenge-06-first-pr.yml @@ -16,10 +16,11 @@ body: 1. Go to the **Pull requests** tab. 2. Select **New pull request**. - 3. Set **base** to `main` and **compare** to `learn/YOUR-USERNAME`. - 4. Write a descriptive PR title. - 5. In the PR description, include `Closes #XX` (replace XX with your Challenge 2 issue number). This automatically links and closes the issue when the PR is merged. - 6. Submit the pull request. + 3. Set **base** to `main` and **compare** to `learn/YOUR-USERNAME`. The page shows a preview of your commits and changed files. This preview can read as very long because it includes unchanged context lines around each change - that is normal. + 4. Activate the **Create pull request** button. It sits between the branch choosers and the diff, and the title and description fields do not appear until you activate it. With a screen reader, use the button quick navigation key (B in NVDA and JAWS browse mode) or search the page for "Create pull request". + 5. Write a descriptive PR title. + 6. In the PR description, include `Closes #XX` (replace XX with your Challenge 2 issue number). This automatically links and closes the issue when the PR is merged. + 7. Submit by activating the **Create pull request** button below the description field. ### PR description template @@ -66,6 +67,7 @@ body: | Symptom | Try this | |---|---| | I cannot find the New pull request button | Make sure you are on the Pull requests tab. The button is near the top-right. | + | The diff appears but there is no title or description field | The compare page shows only a preview at first. Activate the **Create pull request** button between the branch choosers and the diff to open the form. | | It says "There isn't anything to compare" | Make sure your branch has at least one commit that differs from main. Did you commit to the right branch? | | I forgot to include `Closes #XX` | Edit your PR description after creating it. Select the three-dot menu or the Edit button on the description. | | I finished but want to check my work | [View the reference solution](https://github.com/Community-Access/git-going-with-github/blob/main/docs/solutions/solution-06-first-pr.md) | diff --git a/work.md b/work.md index 5ea318be..7722578b 100644 --- a/work.md +++ b/work.md @@ -316,10 +316,11 @@ Source template: [challenge-06-first-pr.yml](https://github.com/Community-Access 1. Go to the **Pull requests** tab. 2. Select **New pull request**. -3. Set **base** to `main` and **compare** to `learn/YOUR-USERNAME`. -4. Write a descriptive PR title. -5. In the PR description, include `Closes #XX` (replace XX with your Challenge 2 issue number). This automatically links and closes the issue when the PR is merged. -6. Submit the pull request. +3. Set **base** to `main` and **compare** to `learn/YOUR-USERNAME`. The page shows a preview of your commits and changed files. This preview can read as very long because it includes unchanged context lines around each change - that is normal. +4. Activate the **Create pull request** button. It sits between the branch choosers and the diff, and the title and description fields do not appear until you activate it. With a screen reader, use the button quick navigation key (B in NVDA and JAWS browse mode) or search the page for "Create pull request". +5. Write a descriptive PR title. +6. In the PR description, include `Closes #XX` (replace XX with your Challenge 2 issue number). This automatically links and closes the issue when the PR is merged. +7. Submit by activating the **Create pull request** button below the description field. #### PR description template @@ -363,6 +364,7 @@ Find the **Peer Simulation: Improve contribution guidance** PR and leave an enco | Symptom | Try this | |---|---| | I cannot find the New pull request button | Make sure you are on the Pull requests tab. The button is near the top-right. | +| The diff appears but there is no title or description field | The compare page shows only a preview at first. Activate the **Create pull request** button between the branch choosers and the diff to open the form. | | It says "There isn't anything to compare" | Make sure your branch has at least one commit that differs from main. Did you commit to the right branch? | | I forgot to include `Closes #XX` | Edit your PR description after creating it. Select the three-dot menu or the Edit button on the description. | | I finished but want to check my work | [View the reference solution](https://github.com/Community-Access/git-going-with-github/blob/main/docs/solutions/solution-06-first-pr.md) |