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
{{ message }}
Repository navigation
Commit 0d8d1c3
Browse filesBrowse the repository at this point in the historyBrowse files
authored
docs(challenge-12,9): clarify sample-file review path and surface reflection questions (#255)
ResolveCommunity-Access/support#70 and #66.
Challenge 12 (support#70): the review instructions assumed a PR with a
diff, but the fallback sample-file path has no diff and therefore no
Files changed tab, inline comment button, or review verdict control.
Split the template into Path A (PR review) and Path B (sample file),
with concrete Path B steps that post the review as a comment on the
Challenge 12 issue. Also clarify that the peer simulation PR lives in
the learner's own Learning Room (not the main workshop repo) and dedupe
the duplicated review checklist. Add a parallel no-PR note to chapter 15.
Challenge 9 (support#66): the chapter 10 Confidence Check reflection
questions were only reachable from chapter 10, so learners who
completed Challenge 9 from its issue never saw them before closing.
Surface the four reflection questions directly in the Challenge 9 issue
template and add a pointer in CHALLENGES.md.
Regenerate html/ and work.md.
Co-authored-by: GitHub Workshop Bot <workshop@example.com>
Co-authored-by: Claude <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: docs/15-code-review.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1089,6 +1089,8 @@ Chapter 15 is the **code review chapter** focused on practicing constructive fee
1089
1089
1.**Review a practice PR and leave 2-3 inline comments** - read the diff line by line, find specific items to comment on, and post constructive feedback.
1090
1090
2.**Submit a formal review verdict** - complete your review by choosing approve, request changes, or comment only.
1091
1091
1092
+
> **No open PR to review?** The steps below assume a pull request with a diff. If your Learning Room has no open PR (or the peer simulation PR is already merged), review the sample file at `docs/code-review-sample.md` instead: read the whole file, find at least two issues (typos, headings, formatting, alt text, clarity), and post your review - one thing done well, at least one constructive suggestion, and a one-sentence verdict - as a comment on your Challenge 12 issue. A plain file has no diff, so there is no Files changed tab and no inline comment button; the issue comment is where your review lives. See the Challenge 12 issue template for the full Path B steps.
1093
+
1092
1094
### Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments
1093
1095
1094
1096
**Goal:** Navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments.
Copy file name to clipboardExpand all lines: docs/CHALLENGES.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -178,6 +178,8 @@ Merge Day closes the Day 1 loop. You verify that your pull request is ready, mer
178
178
179
179
**Evidence to post:** Share the merged PR link and the issue number that closed.
180
180
181
+
Before you close the issue, answer the four **Confidence Check** reflection questions from [Chapter 10](10-notifications-and-day-1-close.md#confidence-check) in a comment on your Challenge 9 issue. There are no wrong answers - this is for you.
182
+
181
183
Before moving on, scan the [Challenge 9 solution reference](https://github.com/Community-Access/git-going-with-github/blob/main/docs/solutions/solution-09-merge-day.md) to make sure you caught both the merge and verification steps.
Copy file name to clipboardExpand all lines: html/docs/15-code-review.html
+3Lines changed: 3 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -1399,6 +1399,9 @@ <h3 id="challenge-12-practice-set">Challenge 12 Practice Set</h3>
1399
1399
<li><strong>Review a practice PR and leave 2-3 inline comments</strong> - read the diff line by line, find specific items to comment on, and post constructive feedback.</li>
1400
1400
<li><strong>Submit a formal review verdict</strong> - complete your review by choosing approve, request changes, or comment only.</li>
1401
1401
</ol>
1402
+
<blockquote>
1403
+
<p><strong>No open PR to review?</strong> The steps below assume a pull request with a diff. If your Learning Room has no open PR (or the peer simulation PR is already merged), review the sample file at <code>docs/code-review-sample.md</code> instead: read the whole file, find at least two issues (typos, headings, formatting, alt text, clarity), and post your review - one thing done well, at least one constructive suggestion, and a one-sentence verdict - as a comment on your Challenge 12 issue. A plain file has no diff, so there is no Files changed tab and no inline comment button; the issue comment is where your review lives. See the Challenge 12 issue template for the full Path B steps.</p>
1404
+
</blockquote>
1402
1405
<h3id="practice-121-step-by-step-review-a-pr-and-leave-inline-comments">Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments</h3>
1403
1406
<p><strong>Goal:</strong> Navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments.</p>
1404
1407
<p><strong>Where you are working:</strong> GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.</p>
Copy file name to clipboardExpand all lines: html/docs/CHALLENGES.html
+1Lines changed: 1 addition & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -366,6 +366,7 @@ <h2 id="day-1-you-belong-here-challenges-1-9">Day 1: You Belong Here (Challenges
366
366
<li>Check that the linked issue closed automatically</li>
367
367
</ul>
368
368
<p><strong>Evidence to post:</strong> Share the merged PR link and the issue number that closed.</p>
369
+
<p>Before you close the issue, answer the four <strong>Confidence Check</strong> reflection questions from <ahref="10-notifications-and-day-1-close.html#confidence-check">Chapter 10</a> in a comment on your Challenge 9 issue. There are no wrong answers - this is for you.</p>
369
370
<p>Before moving on, scan the <ahref="https://github.com/Community-Access/git-going-with-github/blob/main/docs/solutions/solution-09-merge-day.md">Challenge 9 solution reference</a> to make sure you caught both the merge and verification steps.</p>
<li>You contributed to an open source community</li>
909
909
</ul>
910
+
<h4id="reflect-before-you-close">Reflect before you close</h4>
911
+
<p>Before you close this issue, take two minutes to answer these questions in a comment below. There are no wrong answers - this is for you. (These are the same questions in the Chapter 10 Confidence Check, surfaced here so you see them before closing.)</p>
912
+
<ol>
913
+
<li>Which chapter felt the most natural to you? Which one do you want to revisit?</li>
914
+
<li>Can you explain what a pull request does to someone who has never used GitHub?</li>
915
+
<li>If you saw a merge conflict right now, would you know where to start?</li>
916
+
<li>What is one thing you want to try on GitHub this week that you did not get to today?</li>
917
+
</ol>
918
+
<blockquote>
919
+
<p><strong>Screen reader tip:</strong> Copy these questions into your comment and type your answers directly below each one. Use a blank line between each question-answer pair so the structure is clear when read back.</p>
920
+
</blockquote>
910
921
<hr>
911
922
<p><strong>Your evidence</strong> (fill in when closing this issue):</p>
912
923
<pre><codeclass="hljs language-text">My PR was merged: [link]
@@ -1179,16 +1190,21 @@ <h4 id="if-you-get-stuck">If you get stuck</h4>
1179
1190
<h3id="challenge-12-review-like-a-pro">Challenge 12: Review Like a Pro</h3>
<p><strong>What you will do:</strong> Perform a thorough code review on a peer-simulation PR (or a buddy's PR). Use the sample file at <code>docs/code-review-sample.md</code>for your review if you do not have a real PR to review. Leave inline comments, make a suggestion, and submit a verdict.</p>
1193
+
<p><strong>What you will do:</strong> Perform a thorough code review. If your Learning Room has an open pull request, review that (Path A). If it does not, review the sample file at <code>docs/code-review-sample.md</code>instead (Path B). Either way, you will leave specific feedback and a verdict.</p>
1183
1194
<p><strong>Why this matters:</strong> Code review is how teams maintain quality and teach each other.</p>
<li><strong>Path A (preferred):</strong> There is an open PR in <strong>this</strong> repository to review. Use the PR workflow below.</li>
1198
+
<li><strong>Path B (fallback):</strong> There is no open PR, or the only PR is already merged. Review the sample file and post your review as a comment on <strong>this</strong> issue.</li>
1199
+
</ul>
1200
+
<p>Not sure where to look? The peer simulation PR lives in <strong>your own Learning Room</strong> repository (the one you are in right now), not in the main workshop repository. Open the <strong>Pull requests</strong> tab here. If the <strong>Peer Simulation: Improve contribution guidance</strong> PR is missing or already merged, use Path B.</p>
1201
+
<h4id="path-a-review-a-pull-request">Path A: Review a pull request</h4>
1185
1202
<h4id="step-1-find-the-pr-to-review">Step 1: Find the PR to review</h4>
1186
1203
<ol>
1187
-
<li>Go to the <strong>Pull requests</strong> tab in this repository</li>
1188
-
<li>Look for the <strong>Peer Simulation: Improve contribution guidance</strong> PR</li>
1204
+
<li>Go to the <strong>Pull requests</strong> tab in <strong>this</strong> repository</li>
1205
+
<li>Look for the <strong>Peer Simulation: Improve contribution guidance</strong> PR, or a classmate's open PR</li>
1189
1206
<li>Click to open it</li>
1190
1207
<li>Alternatively, if your facilitator gave you buddy access, open your buddy's Day 2 PR</li>
1191
-
<li>If you do not have a real PR to review, open and review the sample file at <code>docs/code-review-sample.md</code> instead.</li>
1192
1208
</ol>
1193
1209
<h4id="step-2-go-to-the-files-changed-tab">Step 2: Go to the Files changed tab</h4>
1194
1210
<ol>
@@ -1232,14 +1248,29 @@ <h4 id="step-3-leave-inline-comment-1-something-positive">Step 3: Leave inline c
1232
1248
```text
1233
1249
6. Click **Submit review**
1234
1250
1235
-
#### Review checklist
1251
+
#### Path B: Review the sample file (when no open PR is available)
1252
+
1253
+
A plain Markdown file has no diff, so there is no **Files changed** tab and no inline comment button. Instead, you will read the file, find the issues, and post your review as a comment on **this Challenge 12 issue**.
1236
1254
1237
-
When reviewing, ask yourself:
1238
-
- ✅ Does it do what the PR description says?
1239
-
- ✅ Is the commit message clear and meaningful?
1240
-
- ✅ Are there typos or formatting issues?
1241
-
- ✅ Would a beginner understand this content?
1242
-
- ✅ Is the language accessible and clear?
1255
+
#### Step 1: Open the sample file
1256
+
1. In **this** repository, open `docs/code-review-sample.md`
1257
+
2. Read the whole file. It is intentionally written with a few issues for you to find
1258
+
1259
+
#### Step 2: Find at least two things to comment on
1260
+
Look for:
1261
+
- Typos or unclear language
1262
+
- Missing or incorrect headings
1263
+
- Inconsistent formatting (for example, list markers that do not match)
1264
+
- Missing alt text for images
1265
+
- Any accessibility or clarity problems
1266
+
1267
+
#### Step 3: Write your review as a comment on this issue
1268
+
Post a comment on **this Challenge 12 issue** that includes:
1269
+
1. One thing the author did well (be specific - quote the line)
1270
+
2. At least one constructive suggestion (quote the line, then suggest a fix)
1271
+
3. A one-sentence verdict: would you **Approve**, **Request changes**, or **Comment** if this were a real PR, and why
1272
+
1273
+
This is how review works when you cannot comment inline: you describe what you found and what verdict you would give.
1243
1274
1244
1275
#### Review checklist
1245
1276
@@ -1263,9 +1294,9 @@ <h4 id="step-3-leave-inline-comment-1-something-positive">Step 3: Leave inline c
1263
1294
**Your evidence** (fill in when closing this issue):
@@ -1279,12 +1310,16 @@ <h4 id="if-you-get-stuck">If you get stuck</h4>
1279
1310
</tr>
1280
1311
</thead>
1281
1312
<tbody><tr>
1313
+
<td>I cannot find the peer simulation PR</td>
1314
+
<td>It lives in your own Learning Room, not the main workshop repo. Open the Pull requests tab here. If it is missing or merged, use Path B with <code>docs/code-review-sample.md</code>.</td>
1315
+
</tr>
1316
+
<tr>
1282
1317
<td>I cannot find the Files changed tab</td>
1283
-
<td>Open the PR, then look for tabs: Conversation, Commits, Files changed. Screen reader users: these are tab links within the PR page.</td>
1318
+
<td>This only exists on a PR (Path A). If you are reviewing the sample file (Path B), skip this and post your review as a comment on this issue.</td>
1284
1319
</tr>
1285
1320
<tr>
1286
1321
<td>I do not know how to leave an inline comment</td>
1287
-
<td>Hover over (or focus on) a line number in the diff and select the blue + button that appears.</td>
1322
+
<td>Hover over (or focus on) a line number in the diff and select the blue + button that appears. Path B users: there is no inline button on a plain file, so write your review as an issue comment instead.</td>
Copy file name to clipboardExpand all lines: learning-room/.github/ISSUE_TEMPLATE/challenge-09-merge-day.yml
+11Lines changed: 11 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -78,6 +78,17 @@ body:
78
78
- You survived a merge conflict
79
79
- You contributed to an open source community
80
80
81
+
### Reflect before you close
82
+
83
+
Before you close this issue, take two minutes to answer these questions in a comment below. There are no wrong answers - this is for you. (These are the same questions in the Chapter 10 Confidence Check, surfaced here so you see them before closing.)
84
+
85
+
1. Which chapter felt the most natural to you? Which one do you want to revisit?
86
+
2. Can you explain what a pull request does to someone who has never used GitHub?
87
+
3. If you saw a merge conflict right now, would you know where to start?
88
+
4. What is one thing you want to try on GitHub this week that you did not get to today?
89
+
90
+
> **Screen reader tip:** Copy these questions into your comment and type your answers directly below each one. Use a blank line between each question-answer pair so the structure is clear when read back.
**What you will do:** Perform a thorough code review on a peer-simulation PR (or a buddy's PR). Use the sample file at `docs/code-review-sample.md` for your review if you do not have a real PR to review. Leave inline comments, make a suggestion, and submit a verdict.
13
+
**What you will do:** Perform a thorough code review. If your Learning Room has an open pull request, review that (Path A). If it does not, review the sample file at `docs/code-review-sample.md` instead (Path B). Either way, you will leave specific feedback and a verdict.
14
14
15
15
**Why this matters:** Code review is how teams maintain quality and teach each other.
16
16
17
-
### Step-by-step review process
17
+
### Choose your path
18
+
19
+
- **Path A (preferred):** There is an open PR in **this** repository to review. Use the PR workflow below.
20
+
- **Path B (fallback):** There is no open PR, or the only PR is already merged. Review the sample file and post your review as a comment on **this** issue.
21
+
22
+
Not sure where to look? The peer simulation PR lives in **your own Learning Room** repository (the one you are in right now), not in the main workshop repository. Open the **Pull requests** tab here. If the **Peer Simulation: Improve contribution guidance** PR is missing or already merged, use Path B.
23
+
24
+
### Path A: Review a pull request
18
25
19
26
**Step 1: Find the PR to review**
20
-
1. Go to the **Pull requests** tab in this repository
21
-
2. Look for the **Peer Simulation: Improve contribution guidance** PR
27
+
1. Go to the **Pull requests** tab in **this** repository
28
+
2. Look for the **Peer Simulation: Improve contribution guidance** PR, or a classmate's open PR
22
29
3. Click to open it
23
30
4. Alternatively, if your facilitator gave you buddy access, open your buddy's Day 2 PR
24
-
5. If you do not have a real PR to review, open and review the sample file at `docs/code-review-sample.md` instead.
25
31
26
32
**Step 2: Go to the Files changed tab**
27
33
1. At the top of the PR, you will see tabs: **Conversation**, **Commits**, **Files changed**, **Checks**
@@ -63,14 +69,29 @@ body:
63
69
```
64
70
6. Click **Submit review**
65
71
66
-
### Review checklist
72
+
### Path B: Review the sample file (when no open PR is available)
73
+
74
+
A plain Markdown file has no diff, so there is no **Files changed** tab and no inline comment button. Instead, you will read the file, find the issues, and post your review as a comment on **this Challenge 12 issue**.
75
+
76
+
**Step 1: Open the sample file**
77
+
1. In **this** repository, open `docs/code-review-sample.md`
78
+
2. Read the whole file. It is intentionally written with a few issues for you to find
79
+
80
+
**Step 2: Find at least two things to comment on**
81
+
Look for:
82
+
- Typos or unclear language
83
+
- Missing or incorrect headings
84
+
- Inconsistent formatting (for example, list markers that do not match)
85
+
- Missing alt text for images
86
+
- Any accessibility or clarity problems
87
+
88
+
**Step 3: Write your review as a comment on this issue**
89
+
Post a comment on **this Challenge 12 issue** that includes:
90
+
1. One thing the author did well (be specific - quote the line)
91
+
2. At least one constructive suggestion (quote the line, then suggest a fix)
92
+
3. A one-sentence verdict: would you **Approve**, **Request changes**, or **Comment** if this were a real PR, and why
67
93
68
-
When reviewing, ask yourself:
69
-
- ✅ Does it do what the PR description says?
70
-
- ✅ Is the commit message clear and meaningful?
71
-
- ✅ Are there typos or formatting issues?
72
-
- ✅ Would a beginner understand this content?
73
-
- ✅ Is the language accessible and clear?
94
+
This is how review works when you cannot comment inline: you describe what you found and what verdict you would give.
74
95
75
96
### Review checklist
76
97
@@ -93,11 +114,11 @@ body:
93
114
id: evidence
94
115
attributes:
95
116
label: "Your evidence"
96
-
description: "Paste the URL of your review and describe what feedback you gave."
117
+
description: "If you used Path A, paste the URL of your review. If you used Path B, paste the review comment you posted on this issue."
97
118
placeholder: |
98
-
Review URL: https://github.com/...
99
-
I reviewed the peer-simulation PR.
100
-
My inline comments were about: ...
119
+
Path used: A (PR review) or B (sample file)
120
+
Review URL or comment: https://github.com/...
121
+
My feedback was about: ...
101
122
My verdict was: ... because...
102
123
validations:
103
124
required: true
@@ -113,8 +134,9 @@ body:
113
134
114
135
| Symptom | Try this |
115
136
|---|---|
116
-
| I cannot find the Files changed tab | Open the PR, then look for tabs: Conversation, Commits, Files changed. Screen reader users: these are tab links within the PR page. |
117
-
| I do not know how to leave an inline comment | Hover over (or focus on) a line number in the diff and select the blue + button that appears. |
137
+
| I cannot find the peer simulation PR | It lives in your own Learning Room, not the main workshop repo. Open the Pull requests tab here. If it is missing or merged, use Path B with `docs/code-review-sample.md`. |
138
+
| I cannot find the Files changed tab | This only exists on a PR (Path A). If you are reviewing the sample file (Path B), skip this and post your review as a comment on this issue. |
139
+
| I do not know how to leave an inline comment | Hover over (or focus on) a line number in the diff and select the blue + button that appears. Path B users: there is no inline button on a plain file, so write your review as an issue comment instead. |
118
140
| I do not know how to suggest changes | In the comment box, select the file-diff icon (it looks like +/-) to create a suggestion block. Edit the code inside the block. |
119
141
| I am not sure which verdict to give | When in doubt, use **Comment**. It gives feedback without blocking. |
120
-
| 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-12-review.md) |
142
+
| 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-12-review.md) |
0 commit comments