Alex: Welcome back. Today is Challenge 2: File Your First Issue. You are going to find a TODO in `docs/welcome.md`, create a GitHub issue about it, and explain what needs to change clearly enough that someone else could act on it.

Jamie: I like that this starts with noticing, not coding. A TODO is basically the repository saying, "something belongs here, but it is not done yet."

Alex: Exactly. A GitHub issue is a conversation thread attached to a repository. Teams use issues to track bugs, chores, questions, feature ideas, accessibility barriers, and work that needs a decision before anyone edits files.

Jamie: So in this challenge, the issue is the work product. No branch, no commit, no pull request yet.

---

Alex: You are working in your private Learning Room repository for Day 1. That repository is where the early contribution path happens: issue, later branch, later commit, later pull request, and eventually a merge when you are ready.

Jamie: And for this specific challenge, everything happens on GitHub.com in the browser, mostly in the Issues tab.

Alex: Right. Start by opening `docs/welcome.md`. Find a line containing `TODO`; if you want the fastest route, use your browser's find command, Ctrl+F on Windows or Cmd+F on Mac, and search for `TODO`.

Jamie: What if I find more than one TODO, or the text is slightly different from the example?

Alex: Pick the TODO that is present in your repository and quote the exact text you found. The examples are models, not something you have to copy word for word.

Jamie: Then I go to Issues and choose New issue, right?

Alex: Yes. From the repository page, open the Issues tab. GitHub keyboard shortcuts may let you press G then I to jump there, or you can move through the repository navigation until you hear or see "Issues." Activate New issue, and if a template picker appears, choose a fitting template or open a blank issue.

---

Jamie: The title is the first place people get nervous. The challenge even says not to write "Fix TODO," which is painfully relatable.

Alex: A useful title says what file or area is involved and what kind of change is needed. Instead of "Fix TODO," try something like "Replace TODO in welcome.md intro with workshop welcome text" or "welcome.md placeholder needs real contributor context."

Jamie: That way someone scanning the issue list can understand the topic without opening every issue.

Alex: Exactly. In the body, this challenge asks for a very specific structure: `What:`, `Where:`, `Why:`, and `TODO found:`. The `Where:` line must include `docs/welcome.md`, and the `TODO found:` line should include the exact TODO text you discovered.

Jamie: So a strong body might say, `What: Replace the placeholder TODO with real welcome text.` Then `Where: docs/welcome.md, intro section.` Then `Why: New contributors need clear context when they open the file.`

Alex: Yes, and then `TODO found: TODO: Add a short workshop welcome paragraph.` Use the TODO text from your own file if it differs. That gives the reader the problem, the location, the reason, and the evidence.

Jamie: The solution examples also show two styles: a bug report and a feature request. Are both okay here?

Alex: They are both valid ways to write issues. A bug report style works when something expected is broken or missing, while a feature request style works when you are proposing an improvement. For Challenge 2, just make sure your issue is grounded in the TODO from `docs/welcome.md` and is clear enough for another person to fix.

---

Jamie: Let's talk about finding your way around the Issues pages, because that is where a lot of people lose time.

Alex: On the Issues list, the page has repository navigation, filters, a search or filter bar, issue rows, and the New issue button. With NVDA, Browse Mode is usually best for reading headings, links, issue titles, and page structure; switch to Focus Mode when you are typing in fields or search boxes. NVDA+F7 can open a list of headings, links, form fields, buttons, and landmarks, which is useful when the page feels busy.

Jamie: What gets announced for each issue in the list?

Alex: Usually you can learn the title, issue number, open or closed status, labels if present, author, comment count, and recent activity. Moving by heading level 3 can jump between issue titles faster than reading every control on the page.

Jamie: And low-vision learners should know that the New issue button is usually prominent near the top of the Issues page. At high zoom, the title field and body field are still large targets, but you may need to scroll more.

Alex: After you submit, GitHub opens the new issue page. The title should be the first main heading, the issue number appears in the page and URL, and the body should render as readable Markdown. Take a moment to confirm the title and body match what you meant to submit.

---

Jamie: Challenge 2 also includes a peer simulation check. That is easy to skip, but it is part of the communication practice.

Alex: Open the issue named "Peer Simulation: Welcome Link Needs Context" and leave a comment about whether the title is clear. Ask yourself, could I tell what needs fixing just from the title? If your facilitator gives you access to a real buddy repository, you may review your buddy's issue instead.

Jamie: This connects to Challenge 3 too, where learners comment on someone else's issue and use an @mention.

Alex: Right. An @mention is `@` followed by a username, and it sends that person a notification. A good comment is focused and helpful, such as `@classmate I can confirm this link goes to a 404 page` or `@classmate I would add the paragraph after the Who Can Contribute heading.`

Jamie: And the comment box supports Markdown, so you can use code ticks for file names, short lists, and links when that helps.

Alex: You can also cross-reference issues. In the same repository, typing something like `#150` links to issue 150. In some cases you can reference work in another repository too, but keep it simple here: copy the issue URL or note the issue number because you will use it as evidence.

---

Jamie: Once issues start piling up, the list can get noisy. What should learners know about filtering and searching?

Alex: The search and filter bar lets you narrow the list. Useful queries include `is:open`, `is:closed`, `author:USERNAME`, `assignee:@me`, `label:bug`, `label:good-first-issue`, and words from the title or body. You can combine filters, like `is:open label:bug`, to reduce the list to exactly what you need.

Jamie: There are also filter buttons for labels, milestones, assignees, and open versus closed state, depending on the repository.

Alex: Yes. Labels are short tags, milestones group work toward a goal, and assignees show who is responsible. The `good first issue` label is commonly used in open source to mark issues that are suitable for newcomers.

Jamie: When I open an issue, I should read the description first, then comments and activity, not jump straight to responding.

Alex: Exactly. The issue page usually starts with the title, then the original description, then discussion and activity. Maintainers may close an issue, close it with a reason, reopen it, assign it, add or remove labels, set a milestone, transfer it, or delete it when appropriate. You will not need most of those powers for Challenge 2, but recognizing the controls helps you understand real project workflow.

---

Jamie: Some learners prefer the terminal. Is there a safe way to do this from a clone?

Alex: Yes, if you already have the repository cloned and GitHub CLI installed. First confirm where you are with `git remote -v` and `gh repo view`. That prevents filing an issue in the wrong repository.

Jamie: Then read before writing.

Alex: Exactly. `gh issue list --assignee @me` can show issues assigned to you, and `gh issue view NUMBER` shows a specific issue with the Markdown rendered in the terminal. If you want only the comments, GitHub CLI has documented options, and `gh issue view --help` will show the current supported flags.

Jamie: For commenting, I can use `gh issue comment NUMBER` and let it open my default editor, or provide the body inline if I know exactly what I want to say.

Alex: And to create an issue, `gh issue create` can prompt you for title, body, labels, and assignees. You can also pass details inline with options like `--title`, `--body`, and `--label`. After any terminal action, check the command output and then view the issue so you know it landed where you intended.

---

Jamie: The chapter also mentions sub-issues. Are those part of this challenge?

Alex: They are an optional extension, not required for Challenge 2. A sub-issue is a smaller issue nested under a parent issue, useful when a big task needs separate trackable pieces. For example, a parent issue about improving `welcome.md` might have one sub-issue for adding a welcome paragraph and another for fixing a link.

Jamie: How is that different from a task list in a comment?

Alex: A task list is a checklist inside one issue or comment. A sub-issue is its own issue, with its own title, description, status, discussion, and sometimes its own assignee. If sub-issues are enabled in your repository, you may see an Add sub-issue or Create sub-issue control on the parent issue.

Jamie: And to finish the chapter work, evidence matters.

Alex: For Challenge 2, go back to your assigned challenge issue and paste the URL of the issue you created. Also explain what TODO you found and what title you used. If you are also doing the Chapter 5 pair of challenges, your evidence can include the issue you created, the issue where you commented with an @mention, and any optional sub-issue you added.

---

Jamie: What are the common stuck spots?

Alex: If you cannot find the TODO, open `docs/welcome.md` and search for `TODO` with Ctrl+F or Cmd+F. If you are not sure what to write, describe the problem to someone who has never opened the file: what is missing, where it is, and why it matters. If the New issue button is not visible, make sure you are on the Issues tab, and if issues appear disabled, ask your facilitator.

Jamie: And if I want to check whether my issue is strong, I should look for a clear title, enough context, and a reproducible location.

Alex: Yes. A vague issue says, "Bug" or "Update file." A clear issue says what is wrong, names `docs/welcome.md`, includes the TODO text, and explains the value of fixing it. Accessibility issues especially benefit from details like what happened, what you expected, how to reproduce it, environment details such as browser or assistive technology, and any extra context.

Jamie: Where should learners go when they need the current source of truth?

Alex: Use the official GitHub documentation about issues, the GitHub Accessibility Guide for working with issues, the GitHub Accessibility Lab CLI guide, and the GitHub changelog when interface behavior changes. The workshop chapter and its learning cards are your guided path, but official references are where you confirm current product details.

Jamie: So the practical goal is simple: find the TODO, file a clear issue, verify it appears, review a peer or simulation issue, and submit your evidence. That is a real open source communication skill before any code changes happen.