Skip to content

Commit 0d8d1c3

Browse files
accesswatchGitHub Workshop Botclaude
authored
docs(challenge-12,9): clarify sample-file review path and surface reflection questions (#255)
Resolve Community-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>
1 parent 470601f commit 0d8d1c3

9 files changed

Lines changed: 174 additions & 65 deletions

File tree

‎docs/15-code-review.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1089,6 +1089,8 @@ Chapter 15 is the **code review chapter** focused on practicing constructive fee
10891089
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.
10901090
2. **Submit a formal review verdict** - complete your review by choosing approve, request changes, or comment only.
10911091

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+
10921094
### Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments
10931095

10941096
**Goal:** Navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments.

‎docs/CHALLENGES.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,6 +178,8 @@ Merge Day closes the Day 1 loop. You verify that your pull request is ready, mer
178178

179179
**Evidence to post:** Share the merged PR link and the issue number that closed.
180180

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+
181183
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.
182184
</details>
183185

‎html/docs/15-code-review.html‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1399,6 +1399,9 @@ <h3 id="challenge-12-practice-set">Challenge 12 Practice Set</h3>
13991399
<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>
14001400
<li><strong>Submit a formal review verdict</strong> - complete your review by choosing approve, request changes, or comment only.</li>
14011401
</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>
14021405
<h3 id="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>
14031406
<p><strong>Goal:</strong> Navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments.</p>
14041407
<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>

‎html/docs/CHALLENGES.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -366,6 +366,7 @@ <h2 id="day-1-you-belong-here-challenges-1-9">Day 1: You Belong Here (Challenges
366366
<li>Check that the linked issue closed automatically</li>
367367
</ul>
368368
<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 <a href="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>
369370
<p>Before moving on, scan the <a href="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>
370371
</details>
371372

‎html/search-index.json‎

Lines changed: 12 additions & 12 deletions
Large diffs are not rendered by default.

‎html/work.html‎

Lines changed: 52 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -907,6 +907,17 @@ <h4 id="day-1-celebration">Day 1 celebration</h4>
907907
<li>You survived a merge conflict</li>
908908
<li>You contributed to an open source community</li>
909909
</ul>
910+
<h4 id="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>
910921
<hr>
911922
<p><strong>Your evidence</strong> (fill in when closing this issue):</p>
912923
<pre><code class="hljs language-text">My PR was merged: [link]
@@ -1179,16 +1190,21 @@ <h4 id="if-you-get-stuck">If you get stuck</h4>
11791190
<h3 id="challenge-12-review-like-a-pro">Challenge 12: Review Like a Pro</h3>
11801191
<p>Source template: <a href="https://github.com/Community-Access/git-going-with-github/blob/main/learning-room/.github/ISSUE_TEMPLATE/challenge-12-review.yml">challenge-12-review.yml</a></p>
11811192
<p><strong>Chapter:</strong> <a href="https://github.com/Community-Access/git-going-with-github/blob/main/docs/15-code-review.md">Ch15: Code Review</a></p>
1182-
<p><strong>What you will do:</strong> Perform a thorough code review on a peer-simulation PR (or a buddy&#39;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>
11831194
<p><strong>Why this matters:</strong> Code review is how teams maintain quality and teach each other.</p>
1184-
<h4 id="step-by-step-review-process">Step-by-step review process</h4>
1195+
<h4 id="choose-your-path">Choose your path</h4>
1196+
<ul>
1197+
<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+
<h4 id="path-a-review-a-pull-request">Path A: Review a pull request</h4>
11851202
<h4 id="step-1-find-the-pr-to-review">Step 1: Find the PR to review</h4>
11861203
<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&#39;s open PR</li>
11891206
<li>Click to open it</li>
11901207
<li>Alternatively, if your facilitator gave you buddy access, open your buddy&#39;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>
11921208
</ol>
11931209
<h4 id="step-2-go-to-the-files-changed-tab">Step 2: Go to the Files changed tab</h4>
11941210
<ol>
@@ -1232,14 +1248,29 @@ <h4 id="step-3-leave-inline-comment-1-something-positive">Step 3: Leave inline c
12321248
```text
12331249
6. Click **Submit review**
12341250

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**.
12361254

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.
12431274

12441275
#### Review checklist
12451276

@@ -1263,9 +1294,9 @@ <h4 id="step-3-leave-inline-comment-1-something-positive">Step 3: Leave inline c
12631294
**Your evidence** (fill in when closing this issue):
12641295

12651296
```text
1266-
Review URL: https://github.com/...
1267-
I reviewed the peer-simulation PR.
1268-
My inline comments were about: ...
1297+
Path used: A (PR review) or B (sample file)
1298+
Review URL or comment: https://github.com/...
1299+
My feedback was about: ...
12691300
My verdict was: ... because...</code></pre>
12701301
<hr>
12711302
<h4 id="peer-simulation-check">Peer simulation check</h4>
@@ -1279,12 +1310,16 @@ <h4 id="if-you-get-stuck">If you get stuck</h4>
12791310
</tr>
12801311
</thead>
12811312
<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>
12821317
<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>
12841319
</tr>
12851320
<tr>
12861321
<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>
12881323
</tr>
12891324
<tr>
12901325
<td>I do not know how to suggest changes</td>

‎learning-room/.github/ISSUE_TEMPLATE/challenge-09-merge-day.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,17 @@ body:
7878
- You survived a merge conflict
7979
- You contributed to an open source community
8080
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.
91+
8192
- type: textarea
8293
id: evidence
8394
attributes:

‎learning-room/.github/ISSUE_TEMPLATE/challenge-12-review.yml‎

Lines changed: 41 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,24 @@ body:
1010
1111
**Chapter:** [Ch15: Code Review](https://github.com/Community-Access/git-going-with-github/blob/main/docs/15-code-review.md)
1212
13-
**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.
1414
1515
**Why this matters:** Code review is how teams maintain quality and teach each other.
1616
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
1825
1926
**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
2229
3. Click to open it
2330
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.
2531
2632
**Step 2: Go to the Files changed tab**
2733
1. At the top of the PR, you will see tabs: **Conversation**, **Commits**, **Files changed**, **Checks**
@@ -63,14 +69,29 @@ body:
6369
```
6470
6. Click **Submit review**
6571
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
6793
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.
7495
7596
### Review checklist
7697
@@ -93,11 +114,11 @@ body:
93114
id: evidence
94115
attributes:
95116
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."
97118
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: ...
101122
My verdict was: ... because...
102123
validations:
103124
required: true
@@ -113,8 +134,9 @@ body:
113134
114135
| Symptom | Try this |
115136
|---|---|
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. |
118140
| 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. |
119141
| 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

Comments
 (0)