You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add step-by-step challenge walkthroughs for Chapters 4 and 5
- Chapter 4: Add numbered walkthroughs for all 3 challenges (4.1-4.3)
with clear guidance that no branches or file edits are needed
- Chapter 5: Add numbered walkthroughs for all 3 challenges (5.1-5.3)
with explicit branch naming guidance (fix/yourname-issueXX)
- Chapter 3: Replace vague branch note with a decision table showing
which branch to use per chapter
- CHALLENGES.md: Update both expandable sections with matching
step-by-step instructions and branch guidance callouts
- CHALLENGE_SYSTEM_ARCHITECTURE.md: Correct Chapter 4 submission
method from PR to issue-comment based
|**04** Issues | 3 |PR with `Closes #XX`| No (manual) | github-issues | 1 | Created |
36
+
|**04** Issues | 3 |Issue comment (evidence links)| No (manual) | github-issues | 1 | Created |
37
37
|**05** Pull Requests | 3 | PR with `Closes #XX`| Yes | pull-requests | 1 | Created |
38
38
|**06** Merge Conflicts | 1 | PR with `Closes #XX`| Yes | merge-conflicts | 1 | Created |
39
39
|**07** Culture and Etiquette | 1 | Issue comment | No | collaboration | 1 | Created |
@@ -49,7 +49,7 @@ Located in `.github/ISSUE_TEMPLATE/` (Chapters 4-6, 11) and inline in `scripts/c
49
49
50
50
**Total: 26 challenges per student**
51
51
52
-
Chapters 4, 5, 6, and 11 use PR-based submission with `Closes #XX` syntax. All other chapters use issue-comment-based submission where students post evidence as a checklist comment.
52
+
Chapters 5, 6, and 11 use PR-based submission with `Closes #XX` syntax. Chapter 4 uses issue-comment-based submission where students post evidence links on their assigned challenge issue (no branch or file editing required). All other chapters use issue-comment-based submission where students post evidence as a checklist comment.
53
53
54
54
**Template Contents:**
55
55
- YAML frontmatter with placeholders: `{CHAPTER}`, `{CHALLENGE_NUM}`, `{CHALLENGE_TITLE}`, `{USERNAME}`, `{ISSUE_NUMBER}`
Copy file name to clipboardExpand all lines: docs/03-the-learning-room.md
+10-1Lines changed: 10 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -140,7 +140,16 @@ When you join the workshop, the facilitator creates a **personal practice branch
140
140
3. Push your practice branch to GitHub
141
141
4. Open a pull request from your practice branch → `main`
142
142
143
-
> **Note:** For GitHub web-based editing (Chapters 4-5), you can create temporary feature branches with descriptive names like `fix/welcome-todos` or `add/keyboard-shortcuts`. Your practice branch becomes essential when you start working locally with Git in Chapter 11.
143
+
> **Which branch do I use and when?**
144
+
>
145
+
> | Chapter | Branch needed? | What to use |
146
+
> |---------|---------------|-------------|
147
+
> | Chapter 4 (Issues) | No | Work happens in issue threads directly. No branch or file editing required. |
148
+
> | Chapter 5 (PRs, web editor) | Yes, auto-created | GitHub creates a branch when you click "Propose changes." Name it `fix/yourname-issueXX`. |
149
+
> | Chapter 5 (PRs, local clone) | Yes, create manually |`git checkout -b fix/yourname-issueXX` from `main`. |
150
+
> | Chapter 11+ (Local Git) | Yes | Use your `username-practice` branch or create `fix/yourname-issueXX` branches from `main`. |
151
+
>
152
+
> **Summary:** Chapter 4 needs no branch. Chapters 5-10 use short-lived `fix/` branches. Your `username-practice` branch becomes essential starting in Chapter 11 when you work locally with Git and VS Code.
Copy file name to clipboardExpand all lines: docs/04-working-with-issues.md
+87-9Lines changed: 87 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,12 +30,90 @@ Chapter 4 is the first **issue-based challenge chapter** with short, confidence-
30
30
31
31
### Chapter 4 Challenge Set
32
32
33
-
1.**Create your first issue**
34
-
- Create one issue with a clear title and short description.
35
-
2.**Claim a challenge issue**
36
-
- Comment `I'd like to try this!` on a beginner challenge issue.
37
-
3.**Ask one clarifying question**
38
-
- Add one question comment on your claimed issue.
33
+
1.**Create your first issue** - file a new issue with a clear title and description.
34
+
2.**Claim a challenge issue** - comment on an existing beginner issue to claim it.
35
+
3.**Ask one clarifying question** - add a question comment on your claimed issue.
36
+
37
+
> **Branch guidance for Chapter 4:** Chapter 4 focuses on issue skills. You do NOT need to create a branch or edit any files for these challenges. All your work happens in GitHub issue threads. File editing and branches start in Chapter 5.
38
+
>
39
+
> **How completion works:** When you finish all three challenges, post a comment on your assigned Chapter 4 challenge issue with links to the issues you created, claimed, and commented on. The facilitator reviews your issue activity directly. No pull request is required for Chapter 4.
40
+
41
+
### Challenge 4.1 Step-by-Step: Create Your First Issue
42
+
43
+
**Goal:** File a new issue in the Learning Room repository with a specific title and a meaningful description.
44
+
45
+
**Where you are working:** the Issues tab of the `learning-room` repository on GitHub.com.
46
+
47
+
1. Open the `learning-room` repository in your browser.
48
+
2. Navigate to the **Issues** tab (press `G` then `I` to jump there with keyboard shortcuts, or find the "Issues" link in the repository navigation).
49
+
3. Activate the **New issue** button.
50
+
4. If a template picker appears, select **Open a blank issue** (or choose a template if one fits).
51
+
5. In the **Title** field, type a clear, specific title (at least 12 characters). Examples:
52
+
- "Add missing contributor background paragraph in welcome.md"
53
+
- "Keyboard shortcuts table has incorrect NVDA modifier key"
54
+
- "Setup guide link to accessibility settings is broken"
55
+
6. In the **Body** field, write a meaningful description (at least 80 characters). Include:
56
+
- What the problem is or what content is missing.
57
+
- Where in the repository the problem exists (file name and section).
58
+
- What you think the fix should be.
59
+
7. Activate **Submit new issue**.
60
+
8. Copy the issue URL or note the issue number (for example, `#150`). You will reference this later.
61
+
62
+
**You are done when:** Your new issue appears in the Issues list with your username as the author, a clear title, and a detailed description.
63
+
64
+
### Challenge 4.2 Step-by-Step: Claim a Challenge Issue
65
+
66
+
**Goal:** Find an existing beginner challenge issue and claim it by leaving a comment.
67
+
68
+
**Where you are working:** the Issues tab of the `learning-room` repository on GitHub.com.
69
+
70
+
1. Open the Issues tab in the `learning-room` repository.
71
+
2. Use the search filter to find beginner issues. Type in the filter bar:
72
+
```text
73
+
is:open label:"challenge: beginner"
74
+
```
75
+
3. Browse the results and pick one issue that interests you.
76
+
4. Open the issue by activating its title link.
77
+
5. Read the issue description to understand what needs to be done.
78
+
6. Scroll to the comment box at the bottom of the issue.
79
+
7. Type: `I'd like to try this!`
80
+
8. Activate the **Comment** button (or press `Ctrl+Enter`).
81
+
9. Note the issue number (for example, `#42`). This is the issue you will fix in Chapter 5.
82
+
83
+
**You are done when:** Your comment appears in the issue thread, and other participants can see you have claimed the work.
84
+
85
+
### Challenge 4.3 Step-by-Step: Ask One Clarifying Question
86
+
87
+
**Goal:** Practice asking a useful question before starting implementation work.
88
+
89
+
**Where you are working:** the issue you claimed in Challenge 4.2.
90
+
91
+
1. Open the issue you claimed in Challenge 4.2.
92
+
2. Re-read the issue description carefully. Think about:
93
+
- Is anything unclear about what needs to change?
94
+
- Do you know which file to edit?
95
+
- Do you understand the expected result?
96
+
3. Scroll to the comment box.
97
+
4. Write one specific question. Examples:
98
+
- "Should I add the paragraph after the existing heading or create a new subsection?"
99
+
- "The issue mentions a broken link. Is the correct URL documented somewhere else in the repo?"
100
+
- "Should the shortcut table keep the same column order, or can I reorganize it?"
101
+
5. Activate the **Comment** button.
102
+
103
+
**You are done when:** Your question comment appears in the issue thread. A facilitator or peer will respond.
104
+
105
+
### Completing Chapter 4: Submit Your Evidence
106
+
107
+
When you have finished all three challenges, go to your **assigned Chapter 4 challenge issue** (the one titled "Chapter 4.1: Create Your First Issue (@yourusername)" or similar) and post a comment with your evidence:
Copy file name to clipboardExpand all lines: docs/05-working-with-pull-requests.md
+88-6Lines changed: 88 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,12 +30,94 @@ Chapter 5 is the first **PR-validated chapter** where students convert issue wor
30
30
31
31
### Chapter 5 Challenge Set
32
32
33
-
1.**Create one small branch change**
34
-
- Edit only the file required by your claimed issue.
35
-
2.**Open a linked PR**
36
-
- Use PR template and include `Closes #XX`.
37
-
3.**Pass required checks**
38
-
- Respond to bot feedback until required checks pass.
33
+
1.**Create one small branch change** - edit the file specified in your claimed issue.
34
+
2.**Open a linked PR** - use the PR template and include `Closes #XX`.
35
+
3.**Pass required checks** - respond to bot feedback until all required checks pass.
36
+
37
+
> **Branch guidance for Chapter 5:** This is the first chapter where you edit files and create branches. Use one of these two paths:
38
+
>
39
+
> -**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`).
40
+
> -**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.
41
+
>
42
+
> **Do NOT use your `username-practice` branch yet.** The practice branch is for Chapter 11 and beyond when you work locally with Git and VS Code. For Chapter 5, use a short-lived feature branch as described above.
43
+
44
+
### Challenge 5.1 Step-by-Step: Create One Small Branch Change
45
+
46
+
**Goal:** Edit the file referenced in the issue you claimed in Chapter 4 (Challenge 4.2).
47
+
48
+
**Where you are working:** the `learning-room` repository on GitHub.com, using the web editor.
49
+
50
+
**Before you start:** Open the issue you claimed in Chapter 4.2 and note which file needs editing. The issue description tells you the file path and what to fix. The practice files are:
51
+
52
+
The following table summarizes the practice files in the learning-room, what each file contains, and the type of issues to look for.
53
+
54
+
| File | What it contains | What to fix |
55
+
|------|-----------------|-------------|
56
+
|`docs/welcome.md`| Introduction to open source contribution | Three `[TODO]` sections where content is missing |
|`docs/setup-guide.md`| Getting-started instructions | Broken links and incomplete steps |
59
+
60
+
**Steps using the web editor:**
61
+
62
+
1. In the `learning-room` repository, navigate to the file specified in your issue. Use the file tree or the "Go to file" button (`T` keyboard shortcut).
63
+
2. Open the file and activate the **pencil icon** (Edit this file) button.
64
+
- Screen reader users (NVDA/JAWS): Press `B` to navigate buttons, find "Edit this file," and press `Enter`.
65
+
- VoiceOver users: Press `VO+U`, open Buttons rotor, find "Edit this file," and press `VO+Space`.
66
+
3. The file opens in the web editor. Make your change. For example:
67
+
- If your issue is about a `[TODO]` section: replace the `[TODO]` placeholder with the requested content (one to three sentences).
68
+
- If your issue is about a broken link: find and correct the URL.
69
+
- If your issue is about a shortcut error: find and fix the incorrect value in the table.
70
+
4. Keep your change small and focused. Edit only what the issue asks for.
71
+
72
+
**Proposing your changes (this creates your branch):**
73
+
74
+
5. After editing, activate the **Commit changes** button (green button above the editor).
75
+
6. A dialog appears. In the **Branch name** field, type: `fix/yourname-issueXX` (replace `yourname` with your GitHub username, and `XX` with the issue number).
76
+
7. Select **Create a new branch for this commit and start a pull request**.
77
+
8. Activate **Propose changes**.
78
+
79
+
**You are done when:** GitHub shows the "Open a pull request" page. Your file change is saved on a new branch. Continue to Challenge 5.2.
80
+
81
+
### Challenge 5.2 Step-by-Step: Open a Linked PR
82
+
83
+
**Goal:** Open a pull request that links to your challenge issue so it closes automatically on merge.
84
+
85
+
**Where you are working:** the "Open a pull request" page that appeared after Challenge 5.1 (or navigate to Pull Requests tab and select "Compare and pull request").
86
+
87
+
1. In the **Title** field, write a short description of your change. Examples:
88
+
- "Complete the Who Can Contribute section in welcome.md"
89
+
- "Fix broken accessibility settings link in setup-guide.md"
90
+
- "Correct NVDA modifier key in keyboard-shortcuts.md"
91
+
2. In the **Body** field, use the PR template if one is provided. Make sure to include:
92
+
- A summary of what you changed and why (at least 50 characters).
93
+
- The line `Closes #XX` where `XX` is the number of your **assigned Chapter 5 challenge issue** (not the issue you claimed in Chapter 4, unless they are the same).
94
+
- If you are also closing the issue you claimed in Chapter 4, add that reference too: `Also addresses #YY`.
95
+
3. Verify the **base branch** is `main` and the **compare branch** is your `fix/yourname-issueXX` branch.
96
+
4. Activate the **Create pull request** button.
97
+
98
+
**You are done when:** Your PR appears in the Pull Requests list. The bot will begin running checks within about 30 seconds. Continue to Challenge 5.3.
0 commit comments