Podcasts

Transcript

Alex: Welcome to Git Going with GitHub. This episode is the front porch for the workshop: what you are building, where the pieces live, and why the path is designed the way it is.

Jamie: I like that phrase, front porch. Because if someone is brand new to GitHub, open source, VS Code, or the command line, the first question is probably, am I already supposed to know all of this?

Alex: No. Open source means people collaborate on projects where the work is visible, reviewable, and shared under rules that allow others to use or improve it. In this workshop, that collaboration is not pretend. You will practice the same GitHub workflow that real projects use.

Jamie: So open source is not just code sitting somewhere public. It is people proposing changes, discussing them, reviewing them, and deciding what should become part of the project.

Alex: Exactly. And accessibility work belongs in that conversation because small improvements can remove real barriers. The workshop gives you a supported place to learn the mechanics before you carry those skills into larger community projects.

Jamie: The materials also say this course is actively maintained. That feels important, because GitHub pages and VS Code screens do change.

Alex: They do. The course guide is your table of contents, and the Learning Room is your personal workshop space. The materials are being refined for the May 2026 cohort, so you should expect updates before and during the course.

Jamie: What happens if a button name or page order does not match what the chapter says?

Alex: Do not treat that as failure. Check the URL, the browser tab title, the page heading, landmarks, tab names, button labels, keyboard help, and in VS Code, the Command Palette. Then ask a facilitator or report the mismatch with the page link, the step that differed, and what your screen reader announced or what you observed.

Alex: The workshop has a two-day shape. Day 1 is GitHub foundations in the browser: navigating repositories, using issues, making branches and commits, opening a pull request, reviewing, and merging.

Jamie: Can we preview those words quickly? Because repository, issue, pull request, and merge can sound like a wall of vocabulary.

Alex: A repository is the project space. It holds files, history, issues, and pull requests. An issue is a tracked conversation about work to do, a bug, a question, or an improvement. A pull request, often shortened to PR, is a proposed change that other people can review before it becomes part of the project.

Jamie: And merge is the moment the approved change is brought into the main project history.

Alex: Right. A branch is a safe working line for your change, and a commit is a saved snapshot with a message. In Day 1, those contributions happen in your own provisioned Learning Room repository, so you can practice issue, branch, commit, pull request, and merge without risking a public project.

Jamie: Then Day 2 moves out of the browser-only world.

Alex: Yes. Day 2 is VS Code, Git, GitHub Copilot, and the Accessibility Agents ecosystem. Some workshop materials may describe a snapshot, for example 55 accessibility agents organized across 3 teams. The safest way to remember it is that Accessibility Agents is a living catalog: agents can be added, revised, or reorganized as the course grows.

Jamie: And the course is not saying, let the agents do magic before you know what is happening.

Alex: Right. You learn the manual workflow first, then you see how automation can support it. There is also a bridge between the two days: on many GitHub repository pages, pressing the period key opens github.dev, which gives you a VS Code-style editor in the browser. It is useful, but it has limits: no local terminal or debugger, web-compatible extensions only, and not the full desktop agent workflow.

Jamie: Before someone gets to all that, what should they do first?

Alex: Start with the pre-workshop setup. It helps you create or verify your GitHub account, choose a browser, install Git, install VS Code for Day 2, and configure your screen reader for GitHub. Plan about 30 minutes, and if setup is not finished before the workshop, tell a facilitator early.

Jamie: Then comes the GitHub Classroom assignment link, right?

Alex: Yes. The facilitator gives you a link that usually starts with https://classroom.github.com/a/. Open it in the browser where you are signed in to GitHub, authorize GitHub Classroom if asked, choose your name from the roster if prompted, accept the assignment, wait for the repository to be created, refresh until the repository link appears, and bookmark it.

Jamie: That repository name usually looks like learning-room-your-username.

Alex: Exactly. It is private to you unless the facilitator intentionally pairs you with someone. Everyone starts from the same template, but your issues, branches, commits, pull requests, mistakes, fixes, and bot feedback belong to your learning process.

Jamie: Once the Learning Room exists, how does a learner know what to do first?

Alex: The Student Progression Bot creates Challenge 1: Find Your Way Around. Open your Learning Room, go to the Issues tab, or use GitHub's keyboard shortcut G then I, find that challenge issue, and read it from top to bottom before activating controls.

Jamie: The issue itself tells you what to do and what evidence to post.

Alex: Yes. Evidence might be a comment, a field, or another requested trace of the work. When the instructions tell you to close the challenge issue, closing it triggers the next challenge. You are not expected to search the whole curriculum to guess the next task.

Jamie: There are a lot of tools named in the guide: browser, github.dev, VS Code, GitHub Desktop, GitHub CLI. How should someone choose without feeling behind?

Alex: Use the tool that fits the moment. The browser is best for Day 1, issues, repository navigation, pull requests, and reviews. github.dev is helpful when you want a VS Code-like editor without installing anything. VS Code desktop is best for Day 2 work with local Git, Copilot, extensions, and deeper editing.

Jamie: And GitHub Desktop or the command line are options, not secret requirements.

Alex: Exactly. GitHub Desktop gives you a visual desktop Git workflow. GitHub CLI is useful if you like terminal workflows or want automation later. If the command line is new to you, you still belong here; the course keeps returning to the contribution workflow itself: issue, branch, change, commit, pull request, review, and merge.

Alex: When you feel lost with a screen reader, listen for structure before you act. Useful signals include the page title, repository name heading, landmarks like main content or repository navigation, tab names such as Code, Issues, and Pull requests, issue or pull request titles, branch names, button names, field labels, bot comments, and check results.

Jamie: So the move is not to press keys faster. It is to pause, find where you are, and then decide.

Alex: Yes. And the course has built-in support. Every challenge has instructions and evidence prompts, chapters include stuck points, reference solutions are available after you try, Gandalf posts educational feedback on pull requests, and facilitators and peers are part of the learning system. If you are still stuck, open a support issue and include what you tried, what happened, what you expected, plus your screen reader and operating system.

Jamie: How do the chapters, appendices, podcasts, and exercises fit together?

Alex: The live agenda is intentionally smaller than the full curriculum. Live sessions focus on the core contribution path, while the full chapter set is there for preparation, catch-up, remote participation, and follow-up. Day 1 runs from setup and tool choice through GitHub navigation, the Learning Room, issues, pull requests, merge conflicts, open source culture, labels, notifications, and the Day 1 close.

Jamie: And Day 2 maps those browser skills into VS Code and a more complete contribution process.

Alex: Right. Day 2 covers VS Code setup, accessibility features, how Git works, Git in practice, code review, Copilot, issue templates, fork-based contribution, Accessibility Agents, the Capstone Project, and what comes next. Challenge 15 is browse-first discovery of Accessibility Agents, not a requirement to fork that repository. Completing Challenge 15 opens Challenge 16, titled Capstone Project, plus Bonus Challenges A through E; the capstone can be a contribution to Accessibility Agents, GLOW, or another meaningful repository, and review-ready drafts or contribution plans can be valid evidence.

Jamie: The appendices sound like the place to go when you need a quick answer rather than a full lesson.

Alex: Yes. Keep the glossary and screen reader cheat sheet handy. Other reference material covers core workshop help, deeper Git topics, VS Code and Copilot, GitHub platform features, community practice, troubleshooting, quick reference, and resources for continued learning. The course also points to official GitHub docs and the changelog when you need the current source of truth.

Jamie: And the exercises have a pattern: Try It, You are done when, and What success feels like.

Alex: That pattern matters because it makes practice checkable. Try It gives you the action, You are done when tells you the finish line, and What success feels like helps you recognize the result, especially when you are navigating by sound, keyboard focus, and page structure.

Jamie: What is the first success check for someone who just accepted the assignment?

Alex: You are ready to continue when you can say four things: I can open my Learning Room repository, I can find the Issues tab, I can open Challenge 1, and I know where to post evidence and how to ask for help.

Jamie: That is refreshingly small. Not, I understand all of Git. Not, I can solve every merge conflict.

Alex: Exactly. If you want the gentlest path, go from pre-workshop setup to choosing your tools, understanding GitHub, navigating repositories, learning the Learning Room, and then your Challenge 1 issue. You belong here, and the course will keep making the next step explicit.

Transcript

Alex: Welcome back. This episode is a companion to the glossary, so the goal is simple: make GitHub words feel less mysterious when you hear them in a workshop, an issue, or a pull request.

Jamie: I love a glossary episode because half the stress of open source is hearing a familiar word used in a very specific way. Like, I know what a branch is in a tree. Git has other plans.

Alex: Exactly. The glossary is there for quick lookup across the whole workshop. Terms are grouped by topic, and there is also an alphabetical quick reference near the end when you already know the word you need.

Jamie: And the navigation tips matter. If you use a screen reader, headings are your friend here. Jump by headings, open the elements list, and type a few letters of the term.

Alex: If you use magnification, the term headings and the alphabetical table are useful because each row stands on its own. And anyone can use Control-F in the browser to search directly for a word like remote, stash, or ARIA.

Jamie: Let's also say pronunciations as we go, because some of these terms are awkward when you only read them.

Alex: Yes. Git is pronounced with a hard G, like get with an i sound. Repo is REE-poh, short for repository. Org is just org, short for organization. And PR is usually spoken as the letters P R, meaning pull request.

Jamie: Good. My shoulders just dropped a little.

Alex: A repository, often shortened to repo, is the project container. It holds the files, folders, documentation, and the full history of changes.

Jamie: So it is more than a folder. It is a folder with memory.

Alex: Right. A repository on GitHub has an address like github.com, then the owner name, then the repo name. If the owner is a group account, that group is called an organization, or org.

Jamie: So in microsoft slash vscode, microsoft is the organization and vscode is the repository.

Alex: Exactly. A fork is your personal copy of someone else's repository on GitHub. You use a fork when you do not have permission to write directly to the original project, but you still want to propose changes.

Jamie: And clone is different from fork, right? That pair always trips people up.

Alex: Fork means a copy under your GitHub account. Clone means a copy on your computer, where you can work in VS Code or another editor. A common workflow is fork the project on GitHub, then clone your fork to your computer.

Jamie: Where do remotes fit into that?

Alex: A remote is a named connection from your local Git repository to a repository hosted somewhere else, usually GitHub. The remote named origin usually points to the repo you cloned from. If you cloned your fork, origin points to your fork.

Jamie: And upstream is the original project you forked from.

Alex: Yes. You can see remotes with `git remote -v`. You can add the original project as upstream with a command like `git remote add upstream https://github.com/original-owner/repo.git`.

Jamie: So local means on my computer, remote means hosted elsewhere, origin is usually my GitHub copy, and upstream is the original project.

Alex: That is the usual setup. You may also hear downstream, which means something based on another project. A fork is downstream from the original because it receives changes from that original source.

Jamie: Before we leave the project container words, what is dot gitignore?

Alex: `.gitignore` is a special file that tells Git not to track certain files. You use it for temporary operating system files, build outputs like `dist/` or `build/`, dependency folders like `node_modules/`, editor folders like `.vscode/`, and secret files like `.env`.

Jamie: Important warning there: dot gitignore does not magically erase something that was already committed.

Alex: Correct. It only ignores untracked files. If a file is already tracked by Git, you remove it from tracking with `git rm --cached filename`, then add the pattern to `.gitignore`, then commit that change.

Alex: A branch is a separate line of development inside a repository. The main branch, usually called `main`, is often the stable version of the project.

Jamie: And sometimes older projects use `master`, so if I hear that, it is also a branch name, not a different tool.

Alex: Right. Common branch names include `main`, sometimes `develop`, and then names like `feature/add-search`, `fix/broken-button`, or `docs/update-readme`. The name should help people understand the purpose of the work.

Jamie: Then a commit is the saved checkpoint.

Alex: Yes. A commit records a snapshot of changes, a message, the author, a timestamp, and a unique identifier called a SHA hash. SHA is often pronounced shah, though spelling S H A is also common.

Jamie: Commit messages have a style too, don't they?

Alex: They do. A good message says what the change does, often in the imperative mood: `Fix typo in README`, not `Fixed typo` or `Fixing typo`. Longer commit messages can include a short title, a blank line, and then a body explaining why the change was made.

Jamie: And a diff is how we inspect the change.

Alex: A diff, short for difference, shows what changed between two versions. Added lines are usually shown with a plus sign, removed lines with a minus sign, and unchanged lines appear as context.

Jamie: That is what I am reading on the Files Changed tab of a pull request.

Alex: Exactly. Push, pull, and fetch are the movement words. Push sends your local commits up to a remote. Fetch downloads remote changes so you can inspect them. Pull fetches changes and then integrates them into your current branch.

Jamie: So fetch is the cautious look, and pull is the update that changes my branch.

Alex: An issue is a discussion item in a GitHub repository. People use issues to report bugs, request features, ask questions, discuss ideas, and track work.

Jamie: Issues also have numbers, like number 42, and they can have labels, assignees, milestones, and comments.

Alex: Yes. A pull request, or PR, is a proposal to merge changes from one branch into another. It includes the branch information, the diff, a description of what changed and why, and a place for discussion.

Jamie: The name still sounds a little odd. It means I am asking maintainers to pull my changes into their project.

Alex: That is exactly it. Review is the feedback process on a PR. A reviewer can leave a comment, approve the change, or request changes before it can be merged.

Jamie: And good review is not just thumbs up or thumbs down. It should be kind, specific, and useful.

Alex: Yes. You may also see a draft PR. Draft means the work is visible, but the author is signaling that it is not ready for final review yet.

Jamie: That is useful in learning settings too. A review-ready draft or a clear contribution plan can be real evidence that someone understands the workflow, even before a maintainer merges anything.

Alex: Merging is combining changes from one branch into another. GitHub projects may use a merge commit, squash and merge, or rebase and merge, depending on how they want the history to look.

Jamie: And then there is the famous merge conflict.

Alex: A merge conflict happens when two branches changed the same part of the same file in incompatible ways. Git pauses because it cannot decide which version should win.

Jamie: Those conflict markers are the lines with less-than signs, equals signs, and greater-than signs.

Alex: Yes. You resolve the file by choosing the final content, removing the markers, saving the file, and committing the resolution. It feels intimidating the first time, but it is a normal collaboration moment.

Jamie: Let's talk about the people words, because GitHub is not just commands.

Alex: A maintainer is someone with responsibility for a repository, often with write or admin access. A contributor is anyone who helps, whether through code, docs, issues, design, testing, accessibility feedback, or review.

Jamie: And a collaborator?

Alex: A collaborator is someone who has been granted access to work directly in a repository, usually more access than a typical outside contributor. Triage is the work of reviewing new issues, adding labels, asking clarifying questions, and routing work to the right place.

Jamie: Labels are those colored tags, like bug, documentation, good first issue, or accessibility.

Alex: Right. A milestone groups issues and pull requests around a goal, such as a release or a workshop deadline. GitHub Projects can organize work in boards, tables, and views so a team can track progress.

Jamie: Community files are part of that collaboration picture too.

Alex: They are. A README explains what the project is. A LICENSE tells people what they are allowed to do with the code. CONTRIBUTING explains how to help. A code of conduct sets expectations for behavior.

Jamie: And templates can guide issues and pull requests so people do not start from a blank box.

Alex: Exactly. You may also see SECURITY for reporting vulnerabilities, SUPPORT for help channels, GitHub Discussions for broader community conversations, a wiki for multi-page documentation, and Gists for small shareable snippets.

Jamie: What about the quick slang pile?

Alex: A few common ones: LGTM means looks good to me. WIP means work in progress. CI means continuous integration, where automated checks run on changes. CD can mean continuous delivery or continuous deployment, depending on the project.

Alex: Now for the Git terms that sound scarier than they usually are. HEAD, in all caps, is Git's pointer to your current branch or commit.

Jamie: Detached HEAD is the one that makes people wonder if they broke everything.

Alex: A detached HEAD means you are looking at a specific commit instead of working on a branch. It can happen when you check out an old commit, a tag, or a commit hash directly.

Jamie: What does that mean for my work?

Alex: You can look around safely, but new commits made there may be hard to find unless you create a branch. The fix is usually to create a branch at that point with `git switch -c branch-name`, or switch back to an existing branch if you were only inspecting history.

Jamie: Stash is another useful safety word.

Alex: Stash temporarily saves uncommitted changes so you can switch tasks or update your branch without committing unfinished work. A common flow is `git stash`, do the other task, then `git stash pop` to bring the changes back.

Jamie: And if I want to see what I stashed?

Alex: Use `git stash list`. You can use `git stash apply` to reapply without removing the stash, or `git stash drop` when you are sure you no longer need it.

Jamie: Rebase is where people get nervous.

Alex: Rebase replays your commits on top of another branch. Merge preserves the branch history and creates a merge point. Rebase can make history more linear, but it rewrites commit history.

Jamie: So when is rebase reasonable?

Alex: It is usually reasonable on your own local branch before you share it, or when your team explicitly uses that workflow. Do not rebase shared branches casually, because rewriting history can disrupt other people's work.

Jamie: And cherry-pick?

Alex: Cherry-pick copies one specific commit from one branch onto another. It is useful when you need one fix without bringing over every other change from that branch.

Jamie: Force push sounds like the red button.

Alex: It deserves caution. Force push overwrites the remote branch with your local history. It may be needed after a rebase on your own branch, but it is not okay on shared branches unless the team has agreed.

Jamie: There is a safer version, right?

Alex: Use `--force-with-lease` instead of plain force push when you can. It checks whether someone else updated the remote branch before overwriting it, which helps prevent accidental damage.

Alex: A SHA or hash is the unique identifier for a commit or Git object. You will often see a short version, like seven characters, in GitHub links and commit lists.

Jamie: A tag is a name attached to a specific commit, often for a version.

Alex: Yes. A release builds on a tag and adds release notes, downloadable files, or other packaged information for users.

Jamie: Then GitHub Actions is the automation system.

Alex: Right. An Action runs workflows, and a workflow is an automated process defined in the repository. CI/CD workflows might run tests, check formatting, build documentation, or deploy a site.

Jamie: And status checks are the pass or fail results that show up on a pull request.

Alex: Exactly. A status check might say the tests passed, the build failed, or an accessibility check needs attention. Maintainers often require important checks to pass before merging.

Jamie: What is a webhook?

Alex: A webhook sends information to another service when something happens on GitHub, like a push, issue comment, or pull request event. It is a way to connect GitHub activity to other tools.

Jamie: And profile?

Alex: Your GitHub profile is your public identity on GitHub. It can show your repositories, contributions, bio, links, and sometimes a profile README.

Jamie: The glossary also needs the accessibility words we keep using in this series.

Alex: A screen reader is software that reads interface content aloud or sends it to a braille display. NVDA, JAWS, VoiceOver, and TalkBack are common examples.

Jamie: Landmarks and headings are navigation structure.

Alex: Yes. Headings organize content by level, like heading level 1 for the page title and heading level 2 for major areas. Landmarks identify regions such as main content, navigation, search, and footer.

Jamie: ARIA is pronounced AIR-ee-uh, right?

Alex: Right. ARIA stands for Accessible Rich Internet Applications. It can add accessibility information to custom interface elements, but native HTML should come first whenever it can do the job.

Jamie: Focus is the current place my keyboard or assistive technology is interacting with.

Alex: Exactly. Tab order is the path focus follows as you press Tab. A good tab order matches the visual and logical reading order, does not trap people, and makes every interactive control reachable.

Jamie: So when we review a page, we are not only asking whether it looks good. We are asking whether the structure and keyboard path make sense.

Alex: Yes, and whether names, roles, labels, error messages, and instructions are available to assistive technology. That is where careful issues and clear reproduction notes really help maintainers.

Alex: Finally, the agent vocabulary. GitHub Copilot is an AI coding assistant. Depending on the environment, it may suggest code, answer questions, help explain errors, or help draft changes.

Jamie: And an agent is a little more active than a simple suggestion box.

Alex: Yes. An agent can follow instructions, use tools, inspect files, and carry out a task within limits. You still review the output, test it, and decide what belongs in the project.

Jamie: Slash commands are the short commands that start with a slash, like a shortcut in a chat or coding assistant.

Alex: Right. A prompt is the request you give the tool. An instruction file is a project-level guide that tells the assistant how to behave, such as coding style, testing expectations, accessibility requirements, or documentation tone.

Jamie: This connects to the later accessibility agent work too.

Alex: It does. The Accessibility Agents collection is a living catalog, so it grows over time. Challenge 15 is browse-first, and learners do not need to fork that repository just to complete the discovery challenge.

Jamie: Completing that discovery challenge unlocks the Capstone Project and the structured bonus path, right?

Alex: Yes. Challenge 16 is titled Capstone Project. It can involve a contribution to Accessibility Agents, GLOW, or another meaningful repository, and review-ready drafts or contribution plans can count as valid evidence of completion.

Jamie: And Day 1 contributions happen somewhere else.

Alex: They happen in the Learning Room repository, which is provisioned for each learner. That is where the issue, branch, commit, pull request, and merge workflow is practiced end to end.

Jamie: Let's end with a quick pronunciation pass for the words people may only have read.

Alex: Git has a hard G. GitHub is Git-hub. Repo is REE-poh. Org is org. PR is P R. SHA can be shah or S H A.

Jamie: More please.

Alex: ARIA is AIR-ee-uh. CI/CD is C I slash C D. YAML is often YAM-ul. `.gitignore` is usually spoken as dot gitignore. `HEAD` is head, even though it is written in capital letters.

Jamie: And when a term gets fuzzy, do not try to memorize every definition at once.

Alex: Look it up, read the nearby related terms, and connect it to the workflow you are doing right now. If a fact might have changed, use the official GitHub documentation, release notes, and linked references as the current source of truth.

Jamie: That makes the glossary less like homework and more like a map you keep beside you.

Alex: Exactly. The win is not knowing every word before you start. It is being able to recover your place when a new term appears, then keep contributing with confidence.

Transcript

Alex: Welcome back. This episode is all about getting ready before Day 1, so the workshop can start with learning instead of setup problems. Please try to finish this at least one day before the event, and if you want the bigger map first, the Get Going with GitHub guide explains GitHub Classroom, your Learning Room repository, Challenge 1, evidence prompts, and tool choices.

Jamie: I like that this is pre-work, but not busy work. It's the stuff that keeps you from getting stuck when everyone else is opening issues, making commits, and trying their first pull request.

Alex: Exactly. You'll want a Windows or macOS computer, a reliable internet connection, and headphones if you're using screen reader audio during group sessions. Linux users can still follow the Git installation path, but the workshop hardware guidance focuses on Windows and macOS.

Jamie: And the software side is a modern browser, a screen reader, and a GitHub account, right? Chrome or Firefox are recommended for GitHub, Edge is fine on Windows, and Safari is usually the best match for VoiceOver on macOS.

Alex: Yes. Before the workshop, install Git, install Visual Studio Code, and make sure you can sign in to GitHub. VS Code version 1.113 or later is recommended for later Accessibility Agents work, Git should be at least version 2.20, and Copilot should be current because it updates through VS Code.

Jamie: There's also Node.js, but only for optional command-line accessibility tools later. So if someone hears node --version and thinks, I don't have that, it doesn't block Day 1.

Alex: Let's start with the GitHub account. If you already have one, you don't need a second account, but you do need to know your password, have access to the email address, and be able to sign in.

Jamie: Username choice feels small until you realize it appears on every issue, pull request, and comment. What should people use?

Alex: Pick something professional and easy to recognize. Lowercase letters, numbers, and hyphens are safest, and GitHub will tell you if the name is already taken. During signup, you'll enter an email address, create a password, choose the username, decide whether you want product update emails, and then complete human verification.

Jamie: That verification step can be the rough spot. GitHub may present a visual CAPTCHA, and that can be a real barrier for screen reader users.

Alex: Yes. Look for an audio option such as Audio or Try an audio challenge. If the available challenge isn't accessible, contact the workshop organizer before the event so someone can help with account verification. After that, GitHub sends a short launch code to your email, and later you should also activate the separate email verification link.

Jamie: And that email verification is not the same thing as optional notification emails.

Alex: Right. Account verification is required for features like creating repositories. Notification emails are about activity, and the workshop does not require you to receive those by email because GitHub also has a web notification inbox.

Jamie: Now, two-factor authentication. People hear 2FA and sometimes think, oh no, another login hurdle.

Alex: It is one more step, but it's an important protection. Two-factor authentication means your password alone is not enough to sign in; you also confirm with a second method, such as an authenticator app, passkey, security key, or another approved option. GitHub requires 2FA for accounts, so make sure it is enabled and tested before the workshop.

Jamie: The part I always worry about is recovery. What if someone changes phones or loses access to the app?

Alex: Save your recovery codes somewhere secure, and add a backup method if GitHub offers one that works for you. Do not wait until the morning of the workshop to find out your 2FA method is unavailable. If you get locked out or you're unsure, use the support hub before the event.

Jamie: How does this connect to Git on your computer? Is that another password prompt?

Alex: Often VS Code or Git will open a browser-based GitHub sign-in, also called OAuth, where you approve access in the browser instead of typing a password into the terminal. More advanced options like SSH keys and personal access tokens are covered separately, but browser sign-in is the friendliest starting point.

Jamie: Once the account exists, I would want GitHub itself to feel less noisy. What settings help with that?

Alex: Open your GitHub account menu, go to Settings, and find Accessibility. The exact labels can move as GitHub changes, so use headings, landmarks, search, or your browser's find command if the page looks different from the guide.

Jamie: The big one is hovercards, right?

Alex: Yes, disable hovercards first. Hovercards are pop-up previews that appear when the pointer or focus lands on certain names or links, and they can interrupt navigation. Then enable link underlines so links are easier to identify without relying on color alone.

Jamie: What about character key shortcuts?

Alex: Those are single-letter shortcuts on GitHub pages. They can be useful, but they can also conflict with screen reader browsing keys, so set them in the way that works best with your assistive technology. While you're in settings, choose a theme that gives you comfortable contrast, such as light, dark, or a high contrast option if available.

Jamie: The profile step is partly social, but it also sounds practical.

Alex: It is. Maintainers are the people who review issues, review pull requests, and help decide what gets merged into a project. A clear profile, a short bio, and a profile picture if you're comfortable adding one can help maintainers recognize you as a real contributor; you can also set the notification email you want GitHub to use, or keep email notifications off and rely on the web inbox.

Jamie: Then there are feature previews, which always make me nervous because every account seems a little different.

Alex: That's normal. Feature previews are switches for GitHub experiences that may still be rolling out, such as new interface features, search experiences, or Copilot-related surfaces. With NVDA or JAWS on Windows, navigate the settings page by headings, buttons, and search fields; if a preview is not listed, it may already be generally available, unavailable for your account, or controlled by an organization policy.

Jamie: So not listed does not automatically mean you did something wrong.

Alex: Exactly. If the workshop asks for a specific preview and you cannot find it, write down the page, the account you're using, and what your screen reader announces, then ask for help.

Jamie: Let's talk about screen readers and browsers, because this is where a small setting can change the whole experience.

Alex: You only need one screen reader. On Windows, NVDA is free and widely used, and JAWS is a paid option with a trial. On macOS, VoiceOver is built in and can be started with Command+F5.

Jamie: For NVDA, what should be ready before GitHub work starts?

Alex: Make sure web browsing feels predictable in your chosen browser. Practice moving by headings, links, buttons, edit fields, and landmarks, and choose a voice rate you can understand during instructions. If you use focus highlighting or speech viewer for support, set those up before the workshop begins.

Jamie: And JAWS is similar, but with its own names for things.

Alex: Right. Make sure the virtual cursor is working in web pages, forms mode behaves as expected when you enter edit fields, and verbosity is set to a level that gives you enough detail without overwhelming you. GitHub pages contain a lot of controls, so comfort with headings and forms is very helpful.

Jamie: For Mac users, Quick Nav matters.

Alex: Yes. With VoiceOver, Safari is the recommended browser, and Quick Nav can make web navigation faster when it fits your workflow. Also remember that many Mac shortcuts use Command where Windows instructions use Control, and VoiceOver commands use the VoiceOver modifier, often Control+Option or Caps Lock depending on your setup.

Jamie: So the browser recommendation is not about brand loyalty. It's about which combination works best with GitHub and the screen reader someone already uses.

Alex: Exactly. Chrome and Firefox are strong choices on Windows, Edge is acceptable, and Safari is the usual VoiceOver pairing on macOS.

Jamie: Before we install anything, can we separate Git from GitHub? The names are almost identical, and that trips people up.

Alex: Git is the version control system on your computer. It tracks changes to files over time, lets you create commits, and supports branching so you can work without overwriting the main project. GitHub is the website where repositories, issues, pull requests, reviews, and collaboration happen.

Jamie: So Git is the tool that records the history, and GitHub is the place where people collaborate around that history.

Alex: Yes. On Windows, download Git from git-scm.com, run the installer, and the defaults are usually fine for this workshop. After installation, open PowerShell, Command Prompt, Git Bash, or Windows Terminal and run git --version.

Jamie: What about macOS and Linux?

Alex: On macOS, you can install Apple's Xcode Command Line Tools, often by running xcode-select --install, or use a package manager if you already have one. On Linux, use your distribution's package manager, such as apt, dnf, or pacman, then verify with git --version. If you're using a screen reader in the terminal, copy the output or review the current line if speech doesn't announce it clearly.

Jamie: And then VS Code is the recommended editor.

Alex: Right. Visual Studio Code is a free code editor with strong Git integration, a built-in terminal, accessibility support, and Copilot integration. Download it from the official VS Code site, install it, and open it once so it can finish its first-run setup.

Jamie: How do we turn on screen reader mode in VS Code?

Alex: Use the keyboard shortcut listed in the setup guide if it works for your system, or open the Command Palette with Control+Shift+P on Windows and Linux, or Command+Shift+P on macOS. Search for Toggle Screen Reader Accessibility Mode and run that command. VS Code should announce or show that screen reader mode is enabled.

Jamie: What changes when that mode is on?

Alex: VS Code exposes editor content and controls in ways that work better with assistive technology. It can improve how the editor, suggestions, notifications, and navigation are announced. We'll practice the everyday shortcuts during the workshop, including the Command Palette, opening files, using the terminal, and moving through source control.

Jamie: Git identity is one of those setup steps that sounds optional until your commits show up with the wrong name.

Alex: Exactly. Git stores a name and email address with each commit you create. In VS Code's terminal, you can set them globally with git config --global user.name followed by your name, and git config --global user.email followed by the email you want attached to commits.

Jamie: What should people use for the name?

Alex: Use the name you want maintainers and classmates to see in commit history. For email, use an address connected to your GitHub account, or use GitHub's private no-reply email if you don't want your personal address exposed. The important thing is that GitHub can match your commits to your account.

Jamie: And the check is simple?

Alex: Yes. Run git config --global --list and confirm that user.name and user.email are present and correct. If you mistype one, run the command again with the corrected value.

Jamie: This is also where the privacy decision shows up. A commit email is not just a setting hidden on your machine; it can become part of public project history.

Alex: That's right. Taking a minute here prevents confusing commit attribution later.

Jamie: What about VS Code extensions and Copilot? Do learners need to go hunting for a pile of add-ons?

Alex: No pile needed. GitHub Copilot is included with modern VS Code builds, and Copilot Free is available to GitHub users. To activate it, sign in with GitHub from VS Code when prompted and confirm that Copilot Chat or Copilot features are available.

Jamie: The other extension is GitHub Pull Requests, yes?

Alex: Yes. Open the Extensions view in VS Code, search for GitHub Pull Requests, install the GitHub Pull Requests extension, and sign in if prompted. You can verify it is working by checking that the GitHub Pull Requests view appears and can connect to your GitHub account.

Jamie: If someone's computer is locked down, is github.dev a fallback?

Alex: It can be. github.dev is a browser-based editor that looks and feels like VS Code and opens from a repository in the browser, often by pressing the period key on a GitHub repository page. It is useful for lightweight edits, but local VS Code plus Git is still the recommended setup for the full workshop.

Jamie: And there are other GitHub access methods, but they're not the main path here.

Alex: Right. GitHub Desktop and the gh command-line tool are useful references, and gh copilot exists for command-line help in some setups, but they are not required for this workshop. The core path is GitHub in the browser, Git on your machine, and VS Code as the editor.

Jamie: Before someone closes the laptop and says done, what should they verify?

Alex: Confirm you can sign in to GitHub, your email is verified, and 2FA works. Confirm your accessibility settings are adjusted, your profile is reasonable, your screen reader and browser combination is comfortable, Git responds to git --version, VS Code opens, screen reader mode is enabled, and your Git name and email are configured.

Jamie: And check versions if you're planning to use later advanced features.

Alex: Yes. Run code --version for VS Code, git --version for Git, and node --version only if you installed Node.js for optional command-line tools. The written guide's learning cards and tool cards are good quick checks if you want a compact review.

Jamie: What happens when Day 1 begins?

Alex: You'll work in your own Learning Room repository, which is provisioned for you. That's where the first contribution workflow happens: issue, branch, commit, pull request, and merge. The setup you did here supports that whole path.

Jamie: And if something fails before the event, don't silently struggle.

Alex: Use the Community Access support repository. You can open a support issue, join the support discussions, or ask in GitHub's accessibility community discussions. Include the exact page, command, prompt, or error message where you got stuck.

Jamie: And when tools change, because they will, use official sources rather than old screenshots.

Alex: Yes. The current GitHub documentation, GitHub's change log, the Git project documentation, and VS Code documentation are the best places to confirm details. The goal is simple: arrive on Day 1 signed in, accessible, and ready to contribute.

Transcript

Alex: Welcome back. Today we're doing something that can save a lot of frustration later: choosing the tool that fits the job, instead of assuming there is one correct way to use GitHub.

Jamie: I like that framing, because people can feel behind before they even start. One person is in a browser, someone else is in VS Code, someone else is using a terminal, and it can sound like they are all in different workshops.

Alex: They are using different doors into the same work. The workshop supports multiple tool paths because real teams do that too. A chapter might say, "open the file," and your job is to know whether that means the GitHub website, github.dev, VS Code, GitHub Desktop, or the GitHub CLI for you.

Jamie: So we are not choosing a tool forever. We are learning what each one is good at, what it cannot do, and how it feels with a screen reader or low vision setup.

Alex: There are five environments in this tour. GitHub.com is the website in your browser. github.dev is a browser-based editor that feels like VS Code. VS Code is the full desktop editor. GitHub Desktop is a graphical Git app. And GitHub CLI is a command-line tool called `gh`.

Jamie: Do learners need to install all of them?

Alex: No. Most people start with GitHub.com on Day 1, because it needs no installation and it is where issues, pull requests, repository pages, and reviews already live. Many learners add VS Code on Day 2 when they need a full workspace for editing, running commands, and working across files.

Jamie: And the other tools are not extra credit tools. They are alternate routes if they match the way you work.

Alex: Exactly. Later lessons use tool cards, which are expandable notes that show the same task in different tools. That way, you can follow the path that fits your access needs, your comfort level, and the task in front of you.

Jamie: Let's start with the browser, because that is the foundation for Day 1.

Alex: GitHub.com is the GitHub website. If you can sign in at github.com, you can browse repositories, open files, create and comment on issues, review pull requests, merge when you have permission, manage labels and project boards, and edit a single file with the built-in web editor.

Jamie: But it is not a full development environment.

Alex: Right. You cannot run code locally there, you do not get a full editor with desktop extensions, and you cannot work offline. It is excellent for collaboration and repository navigation, but limited for deeper coding work.

Jamie: How does it feel with a screen reader?

Alex: GitHub.com has strong screen reader support. Pages use landmarks, headings are generally consistent, and many actions have keyboard shortcuts. You can jump to main content or search with `S`, use `/` for search in many places, move by headings with `H`, and move by landmarks with `D` in browse mode. In a repository, `G` then `I` can take you to Issues.

Jamie: And for low vision users, the theme controls matter a lot.

Alex: They do. In appearance settings, you can choose light, dark, light high contrast, dark high contrast, or sync with your operating system. GitHub also responds well to browser zoom, and the layout usually adapts up to high zoom levels. The learning cards also remind people to enable link underlines in accessibility settings so links are not identified by color alone.

Jamie: github.dev feels like the bridge tool to me. It is still in the browser, but it is more editor-like.

Alex: That is a good way to put it. github.dev runs a VS Code-style editor in your browser, with a file explorer, tabs, diffs, staging, and commits. You can open it from a repository by pressing the period key, or by changing `github.com` to `github.dev` in the address bar.

Jamie: So if I am viewing a file on GitHub and I press period, I move into that editor experience?

Alex: Yes. It is especially useful when a change touches more than one file, or when you want a clearer editing workspace without installing anything. You can edit files, review the differences, and commit to a branch.

Jamie: What should people not expect from it?

Alex: It does not run your program, build your project, or execute normal terminal commands. Some browser-compatible VS Code extensions work, but anything that needs a local runtime may not. And like GitHub.com, it is not an offline tool.

Jamie: Any screen reader notes there?

Alex: Because github.dev is VS Code in the browser, the command palette is a central control point. Use `Ctrl+Shift+P` on Windows or Linux, and `Cmd+Shift+P` on macOS. Some screen readers may need focus mode or application mode in the editor area. If keys are not reaching the editor, press `Escape`, then try the command palette again.

Jamie: Then there is full VS Code on the desktop.

Alex: VS Code is the workshop's main full workspace for Day 2 and beyond. It does require installation, along with Git for local version control. Once set up, it gives you editing, extensions, an integrated terminal, Git tools, debugging, and GitHub Copilot features in one place.

Jamie: This is where you can actually run commands and test code on your own machine.

Alex: Exactly. You can stage, commit, push, and pull through the Source Control panel, or use the terminal if you prefer commands. You can run scripts, use language tools, install extensions, and keep working offline, then sync when you are back online.

Jamie: What does it not do by default?

Alex: Without extensions, VS Code does not give you the full GitHub issue and pull request workflow inside the editor. For that, you usually add the GitHub Pull Requests extension. You can still use Git from VS Code without it, but issues and pull request review may send you back to the website.

Jamie: And accessibility-wise, VS Code has its own learning curve.

Alex: It does, but it also has good keyboard support and screen reader features. The command palette is useful here too, because it lets you search for commands instead of hunting through menus. Low vision users can adjust themes, zoom, font size, and high contrast settings. The VS Code reference appendix is there for deeper setup help when learners are ready.

Jamie: Where does GitHub Desktop fit? I sometimes hear people assume it is only for beginners, but that seems unfair.

Alex: It is a real tool, and it can be a good fit. GitHub Desktop is a desktop Git client with a visual interface for cloning repositories, creating branches, seeing changed files, writing commits, pushing, pulling, and syncing with GitHub.

Jamie: So it helps with Git without requiring people to type Git commands.

Alex: Yes. That can reduce stress when the goal is to understand branches, commits, and sync status. It is also nice for reviewing a set of changed files before committing.

Jamie: But it is not a code editor, right?

Alex: Right. You usually pair it with an editor such as VS Code. It also does not run your project, and it is not the best choice for automation or scripted workflows. For issues, pull requests, settings, and deeper review, you may still move back to GitHub.com.

Jamie: How should screen reader users approach it?

Alex: Try it with your own screen reader before relying on it for a timed task. Some people like the clear commit workflow, while others find the browser or terminal more predictable. If it matches your access setup, it can be a comfortable middle ground.

Jamie: Now for the terminal people: the GitHub CLI.

Alex: The GitHub CLI is a command-line tool called `gh`. It lets you interact with GitHub from a terminal, so you can create issues, view pull requests, check repository information, authenticate, and automate repeated tasks.

Jamie: That sounds powerful, but also a little unforgiving.

Alex: It can be, which is why the learning path should start small. Install the tool, sign in with `gh auth login`, use `gh help`, and try one safe read-only command before changing anything. The goal is to build trust in what each command does.

Jamie: What can it not do for you?

Alex: It does not replace a code editor. You still need something to edit files, and you still need Git itself for many local repository operations. The CLI is strongest when you want speed, scripting, repeatable commands, or a terminal-first workflow.

Jamie: And for screen reader users, terminals can actually be appealing.

Alex: Yes, because command output can be linear and predictable. But precision matters. A missing flag or a wrong repository can change the result, so it helps to read command output carefully and use help text often. The CLI learning cards point learners toward small commands, authentication, and pull request workflows instead of trying to memorize everything.

Jamie: If someone is deciding where to start, what is the plain recommendation?

Alex: Start Day 1 in GitHub.com. The Learning Room repository is provisioned for each learner, and the early contribution workflow happens there: issue, branch, commit, pull request, and merge. The browser keeps everyone close to the collaboration pieces.

Jamie: Then Day 2 is when VS Code becomes more important.

Alex: Yes. When you need a full editing workspace, a terminal, extensions, Copilot, or local testing, VS Code is the recommended main path. github.dev is helpful when you want a quick editor without installation. GitHub Desktop is helpful when you want a visual Git workflow. The CLI is helpful when the terminal is comfortable or automation is part of the work.

Jamie: So switching tools is normal, not a sign that you chose wrong.

Alex: Absolutely. You might open an issue in the browser, edit three files in github.dev, test locally in VS Code, commit through GitHub Desktop, and check a pull request with the CLI. The best tool is the one that lets you understand the task, make the change, and verify what happened.

Jamie: I like ending with something small. What is the first confidence exercise?

Alex: Pick any repository you can safely explore, ideally your Learning Room repository once it is available. Find the README file, open it, and identify how you would make a small edit in each tool you are trying. You do not have to commit a real change in every tool. The exercise is about knowing where the file lives and how editing would begin.

Jamie: In GitHub.com, that means opening the README on the website and finding the edit control, usually the pencil icon when you have permission.

Alex: Yes. In github.dev, press period from the repository page or change the URL, then find the README in the explorer. In VS Code, open the cloned repository folder and find the README in the file explorer. If VS Code is not set up yet, skip that route for now.

Jamie: In GitHub Desktop, you would clone or open the repository, then use its option to open the files in your external editor.

Alex: And in the CLI, you might use `gh repo view` to confirm the repository, then use normal Git and your editor for file changes. Success looks simple: you can say which tool you used, where the repository was, where the README was, and what you would do before committing a change.

Jamie: And if someone gets stuck, what should they check before assuming they broke something?

Alex: Check the basics in order: which tool am I in, which repository am I looking at, which branch is active, which file is open, and have I actually saved the change? Then look for the matching appendix or official documentation for that tool. VS Code setup, GitHub Desktop, the GitHub CLI manual, and the GitHub Accessibility Lab CLI guide are all useful references.

Jamie: And when asking for help, include the tool and the exact point where things stopped making sense.

Alex: Yes. "I am in github.dev, on my Learning Room repository, trying to open the README, and the period key did not open the editor" is much easier to help with than "GitHub does not work." Clear context helps someone reproduce the problem or suggest a different path.

Jamie: That is a reassuring place to land. You do not have to become a browser expert, editor expert, desktop app expert, and terminal expert all at once. You just need enough orientation to choose the route that supports the work you are doing today.

Transcript

Alex: Welcome back. Today we're building the map you use before you click anything on GitHub. GitHub can feel like one giant website, but it makes more sense when you know what level you're on and what landmarks are always nearby.

Jamie: I like starting there, because the confusing moment is usually not, "What button do I press?" It's, "Where am I, and what kind of page is this?"

Alex: Exactly. GitHub has three nested levels. Level one is your own account area, like your profile, settings, and notifications. Level two is a user or organization space, such as github.com/github or github.com/community-access. Level three is a repository, and that is where issues, pull requests, code, actions, branches, and files live.

Jamie: So when a workshop says, "go to the repo," it usually means that third level. And for Challenge 01, Find Your Way Around, learners will practice that inside their own Learning Room repository, which is provisioned for each learner.

Alex: No matter which GitHub page you land on, there is a global navigation area near the top of the page. A screen reader will usually expose it as a landmark called "Navigation Menu." It includes the GitHub home link, search, links for pull requests and issues, notifications, and your account menu.

Jamie: And the keyboard path matters here. If your screen reader supports landmark navigation with D, you can move through landmarks until you hear "Navigation Menu," then use K to move through links inside it. Those are normal links, so Enter activates them from Browse Mode.

Alex: There is also a skip link on GitHub pages. When you start tabbing from the top of a freshly loaded page, you may hear something like "Skip to content." Activating it moves you past repeated navigation and into the main content area.

Jamie: That is especially helpful when the visual layout changes. At high zoom, or on a narrower screen, the same controls may collapse, wrap, or become icons. The labels, landmarks, tabs, URLs, and headings are the pieces to trust.

Alex: Inside a repository, you get a second navigation area. That one is usually labeled "Repository navigation," and it contains tabs like Code, Issues, Pull requests, Actions, Projects, Wiki, Security, Insights, and sometimes Settings. The active tab may have an underline visually, but the tab name and URL are the more reliable clues.

Jamie: Okay, let's say I followed a link and I have no idea where I landed. What are the fastest checks?

Alex: Use three signals: the URL, the browser tab title, and the first H1 heading. The URL is often the clearest. github.com by itself is your personal feed or dashboard. github.com slash username is a profile. github.com slash owner slash repo is a repository home page.

Jamie: And the extra pieces after that tell me the view. Slash issues is the issue list. Slash issues slash 42 is a specific issue. Slash pull slash 7 is a specific pull request. Slash settings slash accessibility is an account settings page.

Alex: Right. The browser tab title also follows patterns. A repository home page usually includes owner slash repo and a description. An issue page includes the issue title, issue number, and repo. A pull request page includes the PR title, PR number, and repo.

Jamie: Then the H1 confirms it from inside the page. Press 1 in Browse Mode to jump to the first H1. If you hear owner slash repo name, you're on a repository page. If you hear "Issues," you're on the issue list. If you hear an issue title or pull request title, you're on the detail page.

Alex: And if you want to check the URL directly, the browser address bar is your friend. Use Alt+D on Windows or Command+L on Mac, listen to the address, then Escape to return to the page.

Jamie: Let's walk through the main GitHub page types, because they sound similar until you've actually used them.

Alex: The repository home page, often the Code tab, is the project hub. Expect the H1 to be owner slash repo name, then repository tabs, then the file tree, and usually a rendered README below the files. The README is often where maintainers explain what the project does and how to contribute.

Jamie: The issue list is more like a tracker. The H1 is usually "Issues," and the page has filters, search, labels, milestones, and a list of open or closed issues. Then an issue detail page is one conversation about one task, bug, request, or discussion point.

Alex: A pull request detail page is similar, but it is about proposed changes. The Conversation tab holds the discussion, status checks, review comments, and merge controls. The Files changed tab shows the code or document differences file by file.

Jamie: And outside a repository, there are personal areas too. Your feed or dashboard is about activity and updates. Your profile is about you, your repositories, and your public activity. Settings pages are account-level controls, and the H1 usually names the settings category.

Alex: On a repository page, it helps to imagine the page from top to bottom. First there is global navigation. Then repository navigation. Then the main content, where the selected tab actually appears.

Jamie: On the Code tab, the main content usually has branch information, a file tree, and the README. If the file tree is exposed as a table, a screen reader user may jump to it with T, then use table navigation such as Control+Alt+Arrow keys, depending on the screen reader.

Alex: A quick orientation routine can take about a minute. Check the address bar. Check the browser title. Jump to the first H1. Move by landmarks until you find Navigation Menu, Repository navigation if you're in a repo, and Main. Then move by headings, links, buttons, or tables depending on what you need.

Jamie: And if I get stuck, I don't have to keep wandering. I can return to the repository root by trimming the URL back to github.com slash owner slash repo. I can use the skip link to jump into the main content. Or I can use search or the command palette to move faster.

Alex: Landmarks and headings are the two big orientation systems on GitHub. Landmarks divide the page into large regions, such as navigation and main content. Headings divide the content inside those regions.

Jamie: So the repository home page usually gives me Navigation Menu, Repository navigation, Main, and sometimes supporting side areas. The issues list has the same global and repository navigation, then a main region with filters and the issue results.

Alex: Issue detail pages and pull request Conversation tabs usually have the conversation in Main, with side information such as labels, assignees, reviewers, projects, and milestones. On a pull request Files changed tab, Main is dominated by the diff view, with file names, changed lines, and review controls.

Jamie: The heading pattern changes by page type too. Repository home starts with the repo name. Issues list starts with "Issues." Issue and pull request detail pages start with the title of that item. Then lower-level headings may mark comments, checks, files, README sections, or other page areas.

Alex: GitHub also has built-in keyboard shortcuts. Press question mark on GitHub.com to open the shortcut help dialog, then review what is available for that page and your current focus.

Jamie: Some shortcuts are especially useful. S or slash can take you to search. G then N opens notifications. And the command palette can be reached with slash or Control+K, with Command+K often used on Mac, depending on browser and GitHub context.

Alex: The command palette is a quick navigation and action box. You can type part of a repository, command, issue, or page destination, then choose from the results. It is useful when a page is crowded or when you know the destination but do not want to hunt through menus.

Jamie: This is also a good place to separate GitHub.com from github.dev. GitHub.com is the collaboration site: issues, pull requests, repository pages, profiles, settings, and notifications. github.dev is a browser-based VS Code-style editor for working with files in a repository.

Alex: Yes. Use GitHub.com when you need to read an issue, review a pull request, navigate project pages, or manage repository settings. Use github.dev when you want a code editor experience in the browser, especially for editing multiple files. Then return to GitHub.com when you need the full conversation, review, and pull request workflow.

Jamie: The source also talks about viewport changes, and I want to underline that. At full desktop width, you may hear or see more navigation items at once. At tablet width, controls may compress. Below mobile widths, menus may collapse even more.

Alex: And high zoom can create similar changes. At 200 percent or more, icons, wrapping, and spacing may shift. But the URL pattern, page title, H1, landmark names, tab names, button text, and command names are still your most dependable orientation clues.

Jamie: So the internal map is not a picture of one exact screen. It is account, organization or user space, repository, then global navigation, repository navigation when present, and main content.

Alex: That's the map Challenge 01 is asking you to practice. In your Learning Room repository, you will orient to the repo, find the headings, move through tabs, explore the file tree, and build confidence that you can recover your place.

Jamie: And it also connects to later work. Agents and automation still use GitHub's collaboration surfaces. They read issues, open pull requests, react to labels, and leave evidence in repositories.

Alex: Later, Challenge 15 has you browse the living Accessibility Agents catalog, and completing it unlocks the Capstone Project plus Bonus Challenges A through E. The Capstone Project can involve Accessibility Agents, GLOW, or another meaningful repository, and review-ready drafts or contribution plans can count as completion evidence. So this navigation work is not just warm-up. It is the surface you will keep using when the tasks get more advanced.

Transcript

Alex: Welcome back. Today we're making the screen reader cheat sheet practical: how to move around GitHub with NVDA, JAWS, and VoiceOver, and how to keep your place when pages get busy.

Jamie: I like that we're treating it as something you use while working, not something you memorize before you're allowed to touch GitHub.

Alex: Exactly. Keep it open in another browser tab, a second window, or print it if that helps. The commands are grouped by task, so you can look up the thing you are doing right now: moving by headings, finding a button, reading a table, typing a comment, or checking a pull request.

Jamie: And if you're using a screen reader, the cheat sheet itself is navigable too. Headings get you to the task areas, and the command tables put the key in one column and the action in the other.

Alex: Right. NVDA users can use NVDA+F7, often Insert+F7, to open the Elements List. JAWS users can use Insert+F6 for headings and Insert+F7 for links. Low vision learners may want the sheet at 150 to 200 percent zoom, and sighted helpers can bookmark it as a quick reference instead of hunting through the whole course.

Jamie: Before the key commands, I want to slow down on modes. This is the part where people press a key and something totally different happens than they expected.

Alex: Yes. On the web, NVDA and JAWS usually work in a reading and navigation mode first. NVDA calls it browse mode, and JAWS often calls it the virtual cursor. In that mode, pressing H does not type the letter H. It jumps to the next heading.

Jamie: So browse mode is for moving around and reading the page. Focus mode is for typing or interacting with controls.

Alex: Exactly. With NVDA, you can toggle browse and focus mode with NVDA+Space, where the NVDA key is usually Insert or CapsLock. With JAWS, Insert+Z toggles the virtual cursor, and forms mode may also turn on automatically in edit fields. VoiceOver on macOS works differently: the VO keys are Control+Option, and you often use VO+Shift+Down to interact with an element, then VO+Shift+Up to stop interacting.

Jamie: So if I press H and it types H into a comment box, I'm probably in the typing context. If I press H and it jumps headings, I'm navigating.

Alex: The fastest GitHub navigation usually starts with headings. H goes to the next heading, Shift+H goes back, and numbers like 1, 2, 3, and 4 jump by heading level. On GitHub, the page title is often level 1, major areas are often level 2, issue and pull request titles are often level 3, and commit titles may show up around level 4.

Jamie: That explains why headings feel so useful on issue lists and pull requests. You're not tabbing through every star button, avatar, and link.

Alex: Landmarks are the other big shortcut. A landmark is a named page region, like navigation, main content, repository navigation, search results, add a comment, or pagination. In NVDA, D moves by landmark. In JAWS, R is commonly used for regions. In VoiceOver, open the rotor with VO+U and choose Landmarks.

Jamie: Then links, buttons, and forms fill in the smaller moves. K for links in NVDA, B for buttons, F or E for edit fields, and Tab when you want the next interactive thing of any type.

Alex: Yes, and lists and tables matter on GitHub more than people expect. L moves to a list, I moves through list items, and T moves to a table. Repository file lists often behave like tables, so once you're in one, Ctrl+Alt plus the arrow keys can move across columns and down rows.

Jamie: And when the page is really crowded, use the tool that lists the page parts instead of wandering.

Alex: Exactly. The Elements List or rotor lets you see headings, links, form fields, buttons, and landmarks in one dialog. Open it, switch to the type you need, type a filter like new issue or comment, and press Enter to jump to the matching item. That is often faster than repeated Tab or repeated H.

Jamie: The cheat sheet also separates commands by screen reader. That's helpful because the pattern is similar, but the exact key can change.

Alex: For NVDA on Windows, remember the core browse mode keys: H for headings, 1 through 6 for heading levels, K for links, B for buttons, F or E for form fields, T for tables, D for landmarks, L for lists, and I for list items. Insert+Space toggles browse and focus mode. Insert+F7 opens the Elements List. NVDA+DownArrow starts reading from the cursor, NVDA+UpArrow reads the current line, and Control stops speech.

Jamie: JAWS has the same general shape. H for headings, K for links, B for buttons, F for form fields, T for tables, R for regions, L for lists, and I for list items.

Alex: Right. JAWS also has U for the next unvisited link. Insert+Z toggles the virtual cursor, Numpad Plus exits forms mode, Insert+F6 opens the headings list, and Insert+F7 opens the links list. Insert+DownArrow starts reading from the cursor, Insert+UpArrow reads the current line, and Control stops speech.

Jamie: For VoiceOver, the rotor is the home base.

Alex: Yes. Turn VoiceOver on or off with Cmd+F5. Open the rotor with VO+U, use left and right arrows to choose Headings, Links, Form Controls, Tables, or Landmarks, and use up and down arrows inside that category. VO+Right and VO+Left move through items, VO+Space activates, VO+A starts reading, and Control stops reading.

Alex: Now let's connect those commands to the GitHub pages learners actually use. On a repository main page, use landmarks to reach main content or repository navigation, use headings to find the README and major areas, and use T if you need the file table.

Jamie: So if I'm trying to find files in my repository, I shouldn't assume Tab is the only way. I can jump to the table and move through rows.

Alex: Exactly. On the issues list page, headings and lists help you find issue titles, filters, pagination, and the New issue button. On an issue detail page, headings help you move through the title, conversation, comments, and timeline. The add comment landmark or form field navigation helps you find the response box.

Jamie: Pull requests have even more moving parts. There's the list page, and then the detail page with tabs.

Alex: Yes. On a pull request detail page, the Conversation tab is where you'll find the discussion, review status, checks, and comment box. The Commits tab often exposes commit titles as headings or links. The Files changed tab can be dense, so use headings, buttons, and table or code navigation carefully, and look for controls that collapse files or move between changed files.

Jamie: What about feature previews? Those can be hard to find because they live around account menus and dialogs.

Alex: If a lesson asks you to check or enable a feature preview, start from the avatar or account menu, then look for a Feature preview item if it is available. NVDA and JAWS users can use browse mode commands to find buttons, headings, and toggles in the dialog. VoiceOver users may need to interact with the menu or dialog using VO+Shift+Down, activate with VO+Space, and stop interacting when done. If the preview has moved or become part of the standard GitHub experience, treat that as a page-change clue rather than a personal mistake.

Jamie: Typing is where mode mistakes show up fast. You find the comment box, start typing, and suddenly the screen reader is jumping around.

Alex: For GitHub text areas, focus mode is required. That includes issue titles, issue bodies, pull request descriptions, review comments, and regular comment boxes. Move to the edit field first, activate it, confirm that your keystrokes are going into the field, and then type.

Jamie: And GitHub text areas support Markdown, so formatting can be keyboard-friendly too.

Alex: Yes. You can type Markdown directly, like number signs for headings, hyphens for lists, backticks for code, and brackets plus parentheses for links. Common editing shortcuts such as Ctrl+B for bold, Ctrl+I for italic, and Ctrl+K for a link may work in GitHub text areas. When in doubt, use the Preview tab or the screen reader's reading commands to check what you wrote before submitting.

Jamie: Dropdown menus and flyouts are another place where I see people get stuck.

Alex: Open the button with Enter or Space, then try arrow keys, Tab, and Escape. Some menus behave like application widgets, so focus mode or interaction mode may be needed. For VoiceOver, interact with VO+Shift+Down, move within the menu, activate with VO+Space, and stop interacting with VO+Shift+Up when you leave the menu.

Alex: GitHub also has its own built-in keyboard shortcuts. Press the question mark key on a GitHub page to open the shortcut dialog, as long as you're not inside a text field.

Jamie: How do those work with a screen reader? Because single letters already mean things in browse mode.

Alex: Sometimes the screen reader gets the key first. If a GitHub shortcut does not fire, use your screen reader's pass-through command or briefly switch modes, then turn your normal navigation back on. And do not test GitHub page shortcuts while your cursor is inside a comment box, because then you're just typing into the box.

Jamie: Once the shortcuts dialog opens, how should someone read it?

Alex: Use headings, tables, or the rotor to move through the dialog. It groups shortcuts by area, so you can find the ones for site-wide navigation, repositories, code browsing, issues, pull requests, comments, notifications, Actions, and Projects. Escape usually closes the dialog.

Jamie: Give me the short list learners should recognize.

Alex: The slash key moves to search on many GitHub pages. g i goes to Issues, and g p goes to Pull requests from repository pages. t opens the file finder when you're browsing code. y updates the address to a permalink for the exact version of the file, and l jumps to a line number when you're viewing a file.

Jamie: And then there are page-specific shortcuts, right?

Alex: Yes. Issue and pull request lists have shortcuts for moving through items and opening selected items. Detail pages have shortcuts around comments and timeline actions. The Files changed tab in a pull request has shortcuts for moving between files and comments. Notifications, GitHub Actions, and Projects have their own shortcut groups, so use the question mark dialog on the page you're actually using.

Jamie: The source for this episode is mostly about GitHub, but this course also spends time in VS Code. What should screen reader users know there?

Alex: VS Code has accessibility help built in. Use the Command Palette and search for accessibility help if you forget a command or need editor-specific guidance. VS Code also has screen reader optimized behavior, and many commands are reachable from the keyboard without relying on the mouse.

Jamie: Diffs are the scary part for a lot of learners. A GitHub pull request diff and a VS Code diff can both feel like a wall of changed lines.

Alex: In VS Code, look for the accessible diff viewer when comparing changes. It presents additions, deletions, and changed lines in a way that is easier to review with speech or braille than a purely visual side-by-side diff. Pair that with GitHub's Files changed tab when you need to understand what will be reviewed before a pull request is merged.

Jamie: So the habit carries across tools: find the accessible view, move by meaningful units, and verify the change before you submit or approve it.

Alex: A few common patterns are worth practicing until they feel familiar. To open an issue, move to the repository navigation, choose Issues, find New issue, enter the title and body in focus mode, preview if needed, and submit. To leave a comment, find the add comment area, move into the text box, type in focus mode, preview or review, then activate the comment button.

Jamie: For pull request review, I would start with the Conversation tab for context, move to Commits if I need the history, and use Files changed when I need the exact code or documentation changes.

Alex: Yes. If you're hearing too much, switch from continuous reading to headings, landmarks, links, and form fields. If H is typing the letter H, leave the edit field or switch back to browse mode. If you cannot find the comment box, search the page elements for comment, add a comment, or form fields. If the diff or code area is hard to navigate, try the file list, changed-file controls, GitHub shortcuts, or VS Code's accessible diff viewer.

Jamie: And if the page doesn't match the instructions, that doesn't mean you failed. GitHub changes.

Alex: Exactly. Check whether you're on the same page type, whether a tab or filter is selected, whether a feature has moved, and whether your screen reader, browser, or GitHub setting changes the behavior. If a command does not work, verify the screen reader mode, keyboard layout, browser focus, and whether the command belongs to NVDA, JAWS, VoiceOver, GitHub, or VS Code. Official references from NV Access, Freedom Scientific, Apple, GitHub keyboard shortcut documentation, and W3C accessibility guidance are good places to confirm details.

Jamie: That's a good place to land. The cheat sheet is not a test. It's a workbench: use the command you need, check where you are, and keep building the workflow one reachable control at a time.

Transcript

Alex: Welcome back. Today we're getting comfortable inside a GitHub repository, which is the place most of your collaboration work starts.

Jamie: And repository is one of those words people hear constantly, but it can still feel fuzzy. What is it, in plain language?

Alex: A repository is a project folder tracked by Git. It can hold code, documents, images, configuration files, and the history of changes to all of those files. On GitHub, the repository page is the web view of that project.

Jamie: So when I open a repo, I'm not just looking at a file cabinet. I'm looking at the current project plus its memory.

Alex: Exactly. Chapter 3 is a confidence-building orientation chapter, so there is no graded automation check here. The goal is to learn the page structure, practice with headings and landmarks, confirm that you can find your way around, and then bring that confidence into the Learning Room work later.

Jamie: I like that this is not treated as busywork. If I can find the tabs, files, README, branches, and history, later issues and pull requests are much less mysterious.

Alex: When you land on a repository URL, the Code tab is usually the home page. Your screen reader may announce a page title like owner slash repo-name, a short description, and GitHub. The first heading is usually the repository name.

Jamie: So my first check is, did I land where I meant to land? If the heading says a different owner or repo name, I stop before doing anything else.

Alex: Yes. A dependable orientation routine is: press 1 to hear the main heading, press D to move through landmarks, and use the heading list with NVDA+F7 or the VoiceOver rotor with VO+U to scan what is on the page.

Jamie: What landmarks should people expect to hear?

Alex: Common ones include Repository navigation for the tab bar, Main for the file area and repository details, and Repository Files Navigation for the rendered README when a README exists. GitHub's visual layout can change with screen width, account features, and product updates, so landmarks, headings, tab names, and shortcuts are more reliable than memorizing the exact visual position.

Jamie: And the learning cards in the chapter support different ways of working, right? Visual and mouse, low vision, NVDA or JAWS, and VoiceOver.

Alex: Right. Open the cards that match your setup. The official GitHub Accessibility Guide is also a good companion reference, especially for NVDA, while this course adds workshop context and other perspectives.

Jamie: Once I'm oriented, the tab bar is usually the next thing I want. What belongs there?

Alex: The main repository tabs often include Code, Issues, Pull requests, Actions, and sometimes Discussions, Projects, Wiki, Security, Insights, and Settings. Settings appears only when you have the right permissions, and some tabs appear only if the repository owner enabled them.

Jamie: And the tab labels tell me more than just the name.

Alex: They can. Issues might announce the number of open issues, Pull requests might announce open pull requests, and the current tab may be announced as selected or current. At high zoom, the tabs may wrap across lines, but they are still links. Keyboard shortcuts can help too: G then I jumps to Issues, and G then P jumps to Pull requests inside a repository.

Jamie: Now the Code tab has the file list, which can be intimidating if the repo is large.

Alex: The files table is the core of the Code tab. It has file and folder names, the most recent commit message for each item, and the age of that change. Screen reader users can often press T to move to the next table and land on the files table.

Jamie: How do I read one row without getting lost?

Alex: Start in the Name column, then move across to the Message column, then to the Age column. A row might tell you docs slash, Add accessibility guide, 3 days ago. Folders often end with a slash, and opening a folder reloads the page with that folder's contents. You can go back up with the browser Back button or the breadcrumb links.

Jamie: Let's talk branches, because that word shows up near the file list and it sounds like something I could break.

Alex: A branch is a version line of the repository. The default branch is the main shared line, usually called main, and it is what you see first unless you choose a different branch. People use branches to work on changes without disturbing the default branch.

Jamie: So the branch selector changes what version of the files I'm viewing.

Alex: Yes. The branch selector is near the top of the file area on the Code tab. Open it, and you'll find a dropdown where you can search branches, choose another branch, or switch to a tag if the repository has tags.

Jamie: What is a tag in this context?

Alex: A tag is a named point in history, often used for releases. Switching to a tag lets you inspect the files as they existed at that release point. It's useful when you want to understand what changed in the last release, or compare current work with a stable snapshot.

Jamie: That helps. Branches are active lines of work, and tags are named snapshots.

Alex: At some point, you may want the repository on your computer. Cloning means copying a remote repository from GitHub to a local folder so you can inspect or work with it using local tools.

Jamie: And cloning is not the same as forking.

Alex: Correct. A clone is a local copy on your machine. A fork is your own GitHub-hosted copy of someone else's repository. A branch is a line of work inside a repository. Those three ideas connect, but they are not interchangeable.

Jamie: What are the practical cloning choices?

Alex: With the GitHub CLI, you can use gh repo clone owner/repo-name, so you do not need to paste the full URL. You can also clone and move into the folder with a command sequence such as gh repo clone owner/repo-name followed by cd repo-name. With standard Git, you can use git clone and the repository URL.

Jamie: And the ZIP download?

Alex: Downloading a ZIP gives you the files, but not the Git history and not the normal Git connection back to GitHub. It is fine for reading or quick inspection. For contribution work, cloning is usually the better choice.

Jamie: Where do watching, starring, and forking fit in?

Alex: Watching subscribes you to notifications. Starring bookmarks or signals interest in a repository. Forking creates your own GitHub copy, often used when you need a place to propose changes and you do not have direct write access.

Jamie: Once I open a single file, the page feels different from the file table. What should I listen for?

Alex: A file page usually has the repository navigation, the file path or breadcrumb, the file content area, and file action buttons. A Markdown file like README.md is often rendered as formatted headings, links, lists, and text. A code file is usually shown with line numbers and code content.

Jamie: So for a README, I can navigate by headings like I would on a web page.

Alex: Exactly. For code, line numbers can help you locate a specific part of the file, and screen reader behavior may depend on your browser and settings. File action buttons may include Raw, Blame, History, Copy path, Download, and Edit when editing is available.

Jamie: How do I reach those buttons without hunting visually?

Alex: Use Tab, button navigation, or your screen reader's links and buttons list. If you choose Edit, GitHub may open an editor if you have permission. If you do not have permission, GitHub may guide you toward making the change in a fork or another editable copy.

Jamie: That is a good moment to slow down and check where the change will go before typing.

Alex: GitHub also lets you inspect history. Commit history answers who changed what and when, and often why, based on the commit message.

Jamie: Where do I find that from the Code tab?

Alex: Near the file list, there is usually a commits link showing the number of commits. The commits page lists recent commits with messages, authors, and dates. Opening one commit page shows the files changed and the diff, which is the before-and-after view of the lines.

Jamie: And Blame is related, but more specific?

Alex: Yes. The Blame view shows, line by line, which commit last changed each part of a file. It is useful when you need context for a line: who touched it, when, and which commit message explains the change. It is not about blaming a person; it is about tracing history.

Jamie: What if I know the file name but not where it lives?

Alex: Use Go to file. The T shortcut opens a search-as-you-type file finder from the repository. Browser Find with Ctrl+F can help on the current page, but Go to file searches the repository's file paths. If you are navigating sidebars or collapsed areas, use landmarks, headings, Tab, and the question mark shortcut to review available GitHub keyboard shortcuts.

Jamie: So search is part of navigation, not a failure to navigate.

Alex: Before you contribute, scan the repository's About area. It often includes the short description, website link, topics, license, and sometimes release or package information.

Jamie: Topics are the little labels like accessibility, documentation, or python?

Alex: Yes. They help you understand the project's subject area. The license tells you the rules for reuse and contribution, and if there is no license, you should be cautious about assuming reuse rights.

Jamie: Can we connect all of this to real situations?

Alex: Sure. If you want to know what a project does, read the description, About area, and README. If you want a good file to edit, inspect the file tree, README, open issues, and contribution guidance. If you want to know who has worked on a file recently, use History or Blame. If you want to understand a release, look at tags, releases, and recent commits. If you want to contribute, start with Issues, README, contributing docs, and the repository's current activity.

Jamie: And if I get stuck?

Alex: Return to the orientation routine: main heading, landmarks, headings list, then tabs. Check whether the page changed because you opened a folder, switched branches, searched files, or moved from the Code tab to another tab. If needed, ask a peer or facilitator to confirm what page and branch you are on.

Jamie: This connects directly to Challenge 01, Find Your Way Around, in the Learning Room. That is where learners practice repository orientation, headings, tabs, file tree navigation, and building confidence in their own provisioned repository.

Alex: A simple practice run is the five-tab tour: visit Code, Issues, Pull requests, Actions, and Settings if you have access, or another visible tab if you do not. On each one, identify the main heading, one useful landmark, and how you would get back to Code. That's enough to turn a repo from a wall of links into a place you can move through on purpose.

Transcript

Alex: Welcome back. Today we're getting oriented in the Learning Room, which is your private practice repository for Day 1 of the workshop.

Jamie: I like starting there, because a new GitHub repository can feel like walking into a room with a lot of unlabeled doors.

Alex: Exactly. The Learning Room is a GitHub repo created for you through GitHub Classroom. It starts from the Community-Access/learning-room-template repository, but your copy lives in the workshop organization with a name like <workshop-org>/learning-room-<your-username>.

Jamie: So I am not editing the template repository itself.

Alex: Right. The template is the clean version facilitators maintain. Your work happens in your own private copy, with your own branches, your own pull requests, and your own feedback from Gandalf, the PR validation bot.

Jamie: And the private copy is on purpose, not just a convenience.

Alex: Yes. It gives you safety, authenticity, and room to move at your own pace. You can practice issues, branches, commits, pull requests, checks, reviews, and merges without changing anyone else's work. Facilitators manage the workshop organization, Classroom assignment, repository permissions, and automation, so you do not need to set those up yourself.

Jamie: What does the first hands-on moment look like?

Alex: You need to be signed in to your GitHub account in the browser, and you need the Classroom assignment link from the facilitator. It usually looks like classroom.github.com/a/ followed by a random-looking ID.

Jamie: And if GitHub Classroom asks for permission or asks who I am?

Alex: If it asks you to authorize GitHub Classroom, activate the authorization button. That is usually a one-time permission step. If it asks you to pick your name from a roster, use arrow keys or Find in Page with Ctrl+F or Cmd+F, and if your name is missing, skip to the next step and tell the facilitator.

Jamie: Then I accept the assignment?

Alex: Yes. Activate Accept this assignment, then wait while GitHub Classroom copies the template into the workshop organization and grants you access. That usually takes 10 to 30 seconds, and you may need to refresh every 15 seconds or so until the repository link appears.

Jamie: One accessibility detail there: status pages do not always announce when something changes.

Alex: Right. Use Browse mode and press K to move through links, or refresh the page until the repo link appears. When you open it, confirm the heading includes learning-room-<your-username>, check that it looks like a private workshop copy, and notice folders such as docs/ and .github/ plus README.md. Bookmark that page, because you will come back to it all day.

Jamie: Where does Challenge 1 show up?

Alex: In the Issues tab of your Learning Room repo. You can use GitHub's keyboard shortcut G then I to go to Issues. Look for an open issue like Challenge 1: Find Your Way Around, usually authored by aria-bot or github-actions[bot], then read the issue body for the task, evidence, and completion instructions.

Jamie: And if Challenge 1 does not appear after a couple of minutes?

Alex: Refresh the Issues tab once. If it is still missing, check the Actions tab for the Student Progression Bot workflow, and ask the facilitator with a link to your repo. While you are in Actions, you can also confirm that a workflow named pr-validation-bot or Gandalf PR Validation exists, which tells you Gandalf is ready for future pull requests.

Alex: Chapter 4 itself is an orientation chapter. There is no challenge to complete and no automation check for this part.

Jamie: So before starting the next chapter, I should be able to find docs/CHALLENGES.md, explain issue -> branch -> pull request -> review -> merge, and know where Gandalf comments on a PR.

Alex: Yes, and that comment location is the Conversation tab of the pull request. Day 1 also has two learning tracks that reinforce each other.

Jamie: One is the optional GitHub Skills practice, right?

Alex: Right. GitHub Skills modules such as Introduction to GitHub, Communicate Using Markdown, and Review Pull Requests let you practice individual skills in your personal account. Mona, GitHub's learning bot, guides those modules.

Jamie: And the required workshop track is the Learning Room.

Alex: Exactly. In the Learning Room, Blocks 1 through 4 move through Challenges 1 through 7, including finding your way, filing an issue, branching, committing, opening a PR, and dealing with a merge conflict. Block 5 covers Challenges 8 and 9 around culture and merge day, and Block 6 focuses on community tools like labels, milestones, and notifications.

Jamie: Same GitHub account, different purpose.

Alex: Yes. The Skills modules are optional self-paced practice. The Learning Room is the required workshop path, with your private repo, workshop issues, Gandalf feedback, and facilitator support.

Jamie: Once I am inside the repo, what files should I expect to work with?

Alex: Start with the file tree. The docs folder contains much of the practice content, .github contains automation and templates, README.md gives the repo overview, and docs/CHALLENGES.md acts like your challenge menu.

Jamie: What are the main practice files?

Alex: docs/welcome.md introduces open source contribution and includes TODO areas for who can contribute, finding something to work on, and what happens after a contribution is merged. Those edits help you practice improving documentation in a realistic way.

Jamie: So not everything is code.

Alex: Exactly. docs/keyboard-shortcuts.md is a screen reader shortcut reference, docs/setup-guide.md helps people get ready to contribute, and docs/CHALLENGES.md helps you understand the path. Some bonus material may appear too, but follow the challenge issue and facilitator guidance for when to use it.

Jamie: That makes the repository feel less mysterious. It is a set of practice surfaces, not a maze.

Alex: Yes. The files are there so you can practice Markdown, navigation, accessible writing, and contribution habits in a repo that behaves like a real project.

Alex: The first Day 1 skills are intentionally small, and that is good design.

Jamie: Challenge 01 is Find Your Way Around.

Alex: Right. Challenge 01 is about repository orientation: headings, tabs, the file tree, and confidence inside the Learning Room. Before you edit anything, you learn how to locate yourself.

Jamie: Then Challenge 04 is Branch Out.

Alex: Yes. A branch is a separate line of work inside the repo. Creating a safe working branch protects main, which is the stable branch you merge into when the work is ready.

Jamie: How do I use that branch without overthinking it?

Alex: Switch to your practice branch before editing, make the change there, commit the change, and open a pull request back into main. You might do that in the GitHub web editor, github.dev, VS Code, or the command line, depending on the workshop flow.

Jamie: I always worry that I will commit the wrong thing.

Alex: That is why you check the branch name before editing and before committing. Challenge 05, Make Your Mark, focuses on editing a file, writing a useful commit message, and connecting the change back to an issue. A good commit message says what changed and why it matters.

Jamie: And the learning cards and tool cards are there as reminders?

Alex: Yes. The learning cards explain the idea in short form, and the tool cards help with actions like switching to your practice branch. Use them when you need a quick reset without rereading the full chapter.

Jamie: So where does the pull request enter the picture?

Alex: A pull request, or PR, is the place where you propose bringing your branch changes into main. It also creates the conversation space for checks, comments, review, and final merge.

Jamie: Walk me through the shape of it.

Alex: You start from the issue instructions, create a branch, edit the file, commit the change, and open a PR. In the PR description, explain what changed and connect it to the issue. Then automation checks it, a reviewer may comment, you respond or update if needed, and eventually the work is merged.

Jamie: Is that the same as the fork-edit-PR workflow people use in open source?

Alex: It is the same collaboration pattern, but the Learning Room skips the fork because GitHub Classroom already created your private copy. Later, in public projects, a fork may be the copy you control before you propose changes to the original repository.

Jamie: Can you make that concrete?

Alex: Sure. Student A might work on a welcome guide challenge, open a PR from their branch, and describe which TODO they completed. The PR is visible to the author, facilitators, automation, and any assigned reviewer when that access is intentionally provided.

Alex: The automation is there to help you learn, not to scold you.

Jamie: That would be Gandalf.

Alex: Yes. Gandalf runs from a workflow such as .github/workflows/learning-room-pr-bot.yml, and it usually comments about 30 seconds after you open a pull request.

Jamie: Where should I listen for that feedback?

Alex: On the PR's Conversation tab. Gandalf may confirm that requirements are met, point out missing evidence, or suggest what to fix before you merge.

Jamie: And there is also progress tracking after merge.

Alex: Right. When a PR is merged, the progression automation can close the current challenge or post the next one. That is why challenges unlock one at a time instead of all arriving at once.

Jamie: What if everyone is working at the same time? Can my PR get buried?

Alex: Your Learning Room keeps your work separate. Use the Pull requests tab, filters, notifications, and direct links from issues or bot comments. Your work is not mixed into another student's repo.

Jamie: Peer review is the part that can make people nervous.

Alex: Totally understandable. In the Learning Room, review is low-stakes practice. You read the PR, inspect the files changed, compare the work to the challenge instructions, and leave one or two useful comments.

Jamie: How do I find a PR I am supposed to review?

Alex: The facilitator may assign one or share a direct link. When you open it, read the Conversation tab first for context, then the Files changed tab to hear what actually changed.

Jamie: Can I comment on anyone's PR whenever I want?

Alex: Only where access is intentionally provided and the facilitator says it is welcome. Private Learning Rooms mean classmates do not automatically see each other's work, though facilitators may arrange real peer review.

Jamie: What does a helpful review comment sound like?

Alex: Be specific and kind. You might say that a heading makes the steps easier to scan, or that the issue asks for a link back to setup-guide.md. If you disagree with a review, respond with context, ask a clarifying question, and bring in a facilitator if needed.

Alex: A few practical worries come up every cohort.

Jamie: What if my reviewer does not respond?

Alex: Use the workshop chat or the facilitator path. Human review may take 15 to 60 minutes, but you should not be left wondering what to do next.

Jamie: What if the bot feedback seems wrong?

Alex: Read the message, compare it with the challenge issue, and ask for help. Bots are useful, but they are not the final word when something looks off.

Jamie: Can I work with a friend or a study group?

Alex: Optional study groups are fine when facilitators allow them. You can talk through navigation and concepts together, while making sure the evidence in your repo represents your own work.

Jamie: Do I need to complete every challenge?

Alex: Follow the workshop requirements and facilitator guidance. Day 1 has a planned progression, but the bigger goal is confidence with the workflow, not racing through screens.

Jamie: How do I know when I am done with a challenge?

Alex: The issue tells you what evidence is required. Usually you will see the bot feedback satisfied, any assigned review addressed, the PR merged, and either the issue closed or the next challenge posted.

Jamie: And if I get stuck anywhere?

Alex: Keep your repo link, issue link, branch name, and PR link handy. Share where you are, what you tried, and what you expected to happen. Then take the win seriously, because opening issues, branches, commits, PRs, reviews, and merges is real contribution practice.

Jamie: If a word or Markdown pattern trips me up, where should I look?

Alex: Use the glossary and Markdown reference appendices, and rely on GitHub's documentation for README files, editing files, GitHub flow, Git basics, and pull requests when you want the source details.

Transcript

Alex: Welcome back. Challenge 1 is called Find Your Way Around, and it is exactly what it sounds like: a guided scavenger hunt through your Learning Room repository.

Jamie: I like starting there. Before anyone edits a file or opens a pull request, they need to know where they are and what they are touching.

Alex: Yes. Your Learning Room is your own private GitHub repository for Day 1. It is created from a template when you accept the GitHub Classroom assignment, but you do not work in the template itself.

Jamie: So my repo is not the class shared notebook. It is my copy, with my issues, my branches, my pull requests, and my practice space.

Alex: Exactly. You accept the Classroom link, wait while GitHub creates the repo, open the new repository link, and bookmark it. The repo name usually looks like learning-room-your-username inside the workshop organization.

Jamie: And Challenge 1 shows up as an issue in that repo, right? The Student Progression Bot opens the next challenge after you close the current one.

Alex: A little GitHub map helps before we click around. GitHub has account pages, organization or user spaces, and repositories. Most workshop work happens inside a repository, because that is where files, issues, pull requests, checks, and project history live.

Jamie: So when someone says, go to the repo, I should expect a page whose main heading is something like owner slash repo-name.

Alex: Right. Every GitHub page also has a global navigation area near the top. Inside a repository, there is a second navigation area for that repo, with tabs such as Code, Issues, Pull requests, Actions, Projects, Wiki, Security, Insights, and sometimes Settings.

Jamie: And if I am using a screen reader, I do not have to rely on where things appear visually. I can use landmarks, headings, links, and tab names.

Alex: Three signals tell you where you are: the URL, the browser tab title, and the first H1 heading. For example, owner slash repo is usually the Code tab, owner slash repo slash issues is the Issues list, and owner slash repo slash pull slash 7 is a specific pull request.

Jamie: My quick check would be: press 1 to hear the main heading, press D to move through landmarks, and open the headings list if I want a fast scan of the page.

Alex: That works well. Also remember that GitHub's layout can change with zoom level, window width, account settings, and product updates. So use visual position as a hint, but trust stable things like the URL, heading, landmark name, tab label, button text, and file name.

Jamie: Okay, I have the Challenge 1 issue open. What is the first thing I am actually asked to find?

Alex: Start on the Code tab. The challenge asks you to look at the file and folder list in the root of the repository and count how many items are showing before the first folder.

Jamie: Before the first folder is a funny detail. Why not just count everything?

Alex: Because this is a navigation practice task, not a math test. Repositories change over time, and the exact count may vary. If you can find the Code tab, reach the file list, and write a reasonable count, you are doing the skill.

Jamie: So the evidence can be simple, like, I found 3 files in the root before the first folder, even if someone else's number is different.

Alex: Yes. Then move to the Issues tab. Look for an issue marked Open, activate one, read it, and write down its title.

Jamie: What if there are no open issues when I look?

Alex: Then say that. Noting that the Issues tab exists and that you checked it is acceptable for this scavenger hunt. The goal is to learn the page type: Issues list, then issue detail.

Alex: Back on the Code tab, open the docs folder and then open docs/welcome.md. Read the first paragraph or opening sentence and write down what it says.

Jamie: And if I notice TODO comments in that file, I should not panic. Those are intentionally left there for a later challenge.

Alex: The next few findings are about understanding the project from its surrounding text. On the Code tab, find the repository description, then find the README, and then check the About area.

Jamie: The challenge says top-right for the description and right sidebar for About, but GitHub may move those pieces around at high zoom or on a narrow screen.

Alex: Exactly. Listen or look for the repository description near the repo name or in the About information. It is short text that tells you what this repository is for.

Jamie: And the README is the longer rendered document that GitHub shows below the file list, if the repo has one.

Alex: Right. For this challenge, open README.md and find the part about who the workshop is for. Then write a sentence about what you found. For the About area, write down the repo information you can identify, such as the description or other visible repo details.

Jamie: Let's slow down on the file list, because that is where a lot of people lose their place.

Alex: On the Code tab, the file list behaves like a table. It usually has a name column, a recent commit message column, and an age column that says how long ago the item changed.

Jamie: For screen reader table navigation, I might jump to the table and move row by row. On Windows screen readers, that is often Ctrl+Alt with arrow keys inside the table.

Alex: Yes. In the name column, folders and files are links. Folders may be announced with a trailing slash, and opening a folder reloads the page to show that folder's contents. Breadcrumb links and the browser Back command can take you back up.

Jamie: There is also a file finder shortcut, right?

Alex: Yes. GitHub has a Go to file control, and the repository shortcut T can open it when GitHub receives the key command. If your screen reader is using T for table navigation in Browse Mode, choose the method that is working in your current setup.

Jamie: When I open a Markdown file like README.md or welcome.md, I should expect headings, paragraphs, links, and maybe code-style text. A code file will feel different because the content is line-oriented.

Alex: And single file pages have action buttons too, such as controls to view raw content, copy, download, or edit when you have permission. Later you will edit files, but in Challenge 1 you are mainly reading and recognizing the page.

Jamie: What about blame and commit history? Those sound ominous.

Alex: They are just history views. Commit history shows a list of saved changes. Blame shows which commit last changed each line of a file. You do not need them to finish this challenge, but knowing they exist helps when you want to understand who changed what and when.

Jamie: Challenge 1 mostly uses Code and Issues, but the repo has more tabs than that.

Alex: It does. Pull requests are where proposed changes are discussed before merging. Actions show automation runs. Projects, Wiki, Discussions, Security, Insights, and Settings may appear depending on the repository and your permissions.

Jamie: The branch selector is on the Code tab too. Do I need to use it right away?

Alex: Not for this scavenger hunt, but you should recognize it. A branch is a safe line of work inside the same repo. Later, you will create a practice branch so your changes do not go straight onto main.

Jamie: And tags?

Alex: Tags are named points in history, often used for releases. The same selector may let you switch between branches and tags.

Jamie: I always mix up clone, fork, and branch.

Alex: A clone is a local copy on your computer. A fork is your own server-side copy of someone else's repository. A branch is a separate line of work inside a repository. For Challenge 1, you do not need to fork anything.

Jamie: And watching, starring, and forking are different social or workflow actions.

Alex: Right. Watching subscribes you to notifications. Starring bookmarks or signals interest. Forking creates a copy under your account or organization. Useful tools, but not required for completing Find Your Way Around.

Jamie: If the website is hard for me on a given day, do I have alternate ways to browse?

Alex: Yes. You can use github.com in the browser, press period on a repo page to open github.dev, browse with VS Code and the GitHub Repositories extension, or use GitHub CLI. For example, gh repo view owner/repo --web opens a repo page in your browser, and standard git clone works when you are ready to work locally.

Alex: When you have your findings, paste them into the evidence box in the Challenge 1 issue. Short sentences are enough: the root count, an open issue title, the opening of welcome.md, the repository description, who the README says the workshop is for, and what the About area shows.

Jamie: I appreciate that the evidence is not trying to trick anyone. If I explored the right places and described what I found, that counts.

Alex: After you submit your evidence, the challenge asks you to open the Peer Simulation: Welcome Link Needs Context issue and leave an encouraging comment or reaction. If your facilitator gives you access to a real buddy repository, you can use your buddy's issue instead.

Jamie: So even in the first challenge, I am practicing repository navigation and community behavior. Find the place, read the context, respond kindly.

Alex: Exactly. Then follow the issue instructions for completion. In this Day 1 flow, closing a challenge issue is what lets the Student Progression Bot open the next challenge.

Jamie: What are the common places people get stuck in this one?

Alex: If you cannot find the tabs, move to the Repository navigation landmark or search the links for Code and Issues. If you cannot find docs/welcome.md, return to the Code tab, open docs, then choose welcome.md. If you are unsure what to write as evidence, describe what you found in your own words.

Jamie: And if Challenge 1 itself is missing after I accepted the assignment?

Alex: Refresh the Issues tab once or twice. If it still does not appear after a couple of minutes, check the Actions tab for the Student Progression Bot workflow, then ask a facilitator with your repo link. While you are in Actions, you may also see the PR validation workflow for Gandalf; you do not need to run it yet.

Jamie: So the win condition is not memorizing GitHub's current layout or having the same file count as everyone else.

Alex: Right. The win is confidence. You can identify the repo, move between Code and Issues, open a folder, read a Markdown file, find the README and About information, leave a first community-style response, and recover when the page does not look exactly like the screenshot in your head.

Transcript

Alex: Welcome back. Today we're working with GitHub issues, which are often where collaboration starts.

Jamie: And an issue can be a bug report, but it's not only bugs, right?

Alex: Right. An issue is a trackable unit of work. It might be a bug, a feature request, a question, a documentation chore, or a note that says, something needs attention here.

Jamie: So it is the shared place where people agree on what needs to happen before anyone starts changing files.

Alex: Exactly. In this chapter, that matters because Challenges 2 and 3 happen entirely in your Learning Room repository's issue threads. You file one issue, then you join a conversation on someone else's issue.

Jamie: No branch, no commit, no pull request yet.

Alex: Not yet. Chapter 5 is about getting comfortable with issue work first: finding the Issues tab, reading the page, writing clearly, commenting well, and confirming your work was recorded.

Jamie: Before someone starts clicking around, is there any accessibility setup they should know about?

Alex: Yes. GitHub has an improved Issues experience with better landmarks and screen-reader announcements. For many accounts, it is already the standard interface. If you see a Feature preview area in your user menu, you can check whether "New Issues Experience" is listed and enabled; if it is not listed, that usually means it has already graduated into the regular interface.

Jamie: And for NVDA users, there is that mode switch that can trip people up.

Alex: Yes. Use Browse Mode for reading headings, issue titles, comments, and timelines. Switch to Focus Mode when you're typing in search boxes, title fields, or comment boxes. NVDA+Space toggles the mode, and NVDA+F7 opens a list of headings, links, form fields, buttons, and landmarks, which is a very practical way to reorient.

Jamie: Low-vision learners may be scanning visually instead, especially at high zoom.

Alex: The Issues tab is in the repository navigation, and the New issue button is prominent near the top of the Issues list. At high zoom, you may need to move through the top area carefully, but the list, filters, and button are still part of the same page. You can also go straight to a repository's issues URL if someone gives you the link.

Jamie: And keyboard shortcuts can help if they're enabled.

Alex: Yes. From a repository page, G then I jumps to Issues. Once you're on the list, issue titles are often heading level 3, so pressing 3 can move between issue titles more quickly than arrowing through every control.

Alex: The Issues list is your dashboard. It shows open work, closed work, titles, issue numbers, labels, authors, assignees, comment counts, and sometimes milestones.

Jamie: What should someone listen for when a screen reader lands on an issue in the list?

Alex: Usually the title link, the issue number, the state such as open or closed, who opened it, when it was updated, labels, and comment information. The exact order can vary, so the useful habit is to stop after each title and listen for the details before activating it.

Jamie: That makes the list less like a wall of links and more like a set of work items.

Alex: Yes. And the search or filter bar at the top lets you narrow that set down. GitHub uses search qualifiers, which are short filters typed into the search field.

Jamie: Like is:open label:bug?

Alex: Exactly. is:open shows open issues. is:closed shows closed ones. label:bug shows issues with the bug label. You can combine them, so is:open label:bug assignee:@me means open bug issues assigned to you.

Jamie: What about milestones and authors?

Alex: milestone:"Version 1" filters by a milestone, author:username finds issues opened by a person, and assignee:username finds issues assigned to them. You can also add plain words to search inside titles and descriptions, like keyboard shortcut or broken link.

Jamie: And if typing qualifiers feels like too much at first?

Alex: Use the filter controls. GitHub gives you menus for labels, assignees, milestones, and open or closed state. The search bar and the filter buttons are two paths to the same goal: a smaller, more relevant list.

Jamie: Once I open an issue, what am I actually reading?

Alex: Start with the title. Then read the body, which is the main description written in Markdown. After that, move through the timeline, where comments, label changes, assignments, references, commits, and pull request activity can appear.

Jamie: So the body tells me what the author thought was important, and the timeline tells me what has happened since.

Alex: Yes. The sidebar adds metadata: labels, assignees, milestone, linked pull requests, and sometimes sub-issues. Labels are short tags like bug, documentation, or good first issue. Assignees are the people responsible for working on it. A milestone groups issues toward a larger goal or release.

Jamie: For navigation, headings are useful here too.

Alex: They are. The issue title is usually the first main heading. Comments and timeline items are easier to skim if you move by headings, landmarks, or form fields instead of reading every page element from the top.

Jamie: And the terminal is an option, not a requirement.

Alex: Right. If you're using GitHub CLI, gh issue view 123 renders the issue in the terminal. gh issue view 123 --comments includes the comments. If the Markdown or timeline is easier in the browser, gh issue view 123 --web opens the issue page instead.

Jamie: I like that the rule is read first, then write.

Alex: Yes. Before commenting, assigning, closing, or editing, read the issue enough to understand the request and the current state.

Alex: Now let's talk about filing a new issue, because that is Challenge 2.

Jamie: This is where people often freeze. The blank title field feels surprisingly serious.

Alex: A clear title says what needs attention and where possible. "Broken link" is vague. "Setup guide link to accessibility settings returns 404" is much better because it names the object, the problem, and the impact.

Jamie: And the body is where the detail goes.

Alex: Yes. A strong issue body usually answers five questions: what happened, what you expected, how to reproduce it, what environment you used, and any additional context. For documentation chores, that might become what content is missing, where it belongs, and what the fix should say.

Jamie: Markdown helps make that readable.

Alex: Definitely. Use short paragraphs, numbered steps, bulleted lists, links, and task lists. If you include code, commands, or error messages, put them in fenced code blocks so they are read as code and not mashed into the sentence.

Jamie: What about labels and assignees while creating the issue?

Alex: If you have permission, you can add labels from the sidebar or issue form, assign someone, and place the issue in a milestone. If you do not have permission, that is fine. Maintainers or facilitators can triage it after you submit.

Jamie: And repositories may have issue templates.

Alex: Yes. If a template picker appears, choose the template that fits, or choose a blank issue when the challenge asks for that. Templates are there to guide you, not to trap you.

Jamie: For Challenge 2, learners are doing this in the Learning Room repository.

Alex: Correct. Open the Learning Room repo, go to Issues, activate New issue, choose a blank issue if needed, write a title of at least 12 characters, and write a meaningful body of at least 80 characters. The suggested theme is an accessibility problem or chore you wish an AI agent could help fix later.

Jamie: And you're done when the issue appears in the list with your username, a clear title, and the description you wrote.

Alex: Yes. Copy the URL or note the issue number, like #150, because you'll use that as evidence later.

Jamie: Challenge 3 shifts from filing to participating.

Alex: Exactly. Open a classmate's issue, or a facilitator-provided peer-simulation issue, read it carefully, and leave a helpful comment. The comment should include an @mention of the issue author, like @classmate, so GitHub notifies them.

Jamie: That notification part is easy to overlook.

Alex: It is, but it is central to open source communication. An @mention says, I want this person to see this. Later, when you study notifications, you'll decide how those alerts reach you.

Jamie: What makes a comment helpful instead of noisy?

Alex: It adds context, confirms a detail, asks a focused question, or suggests a next step. "Same" is not very useful. "@classmate I can confirm this link returns a 404 in setup-guide.md, under the accessibility settings heading" gives the author something they can use.

Jamie: And reactions are lighter than comments.

Alex: Yes. Emoji reactions can say thanks, agreement, celebration, or concern without adding another full message to the thread. Use them when you want to acknowledge something but do not need to add new information.

Jamie: After the comment appears and the username becomes a link, Challenge 3 is complete.

Alex: Right. If you're using the web page, Ctrl+Enter often submits a comment from the comment box. If you're using the terminal, gh issue comment 123 --body "Your message" posts inline, and gh issue comment 123 --editor opens your default editor for a longer comment.

Alex: Issues also connect to each other, and to pull requests, through references.

Jamie: That's the #number syntax?

Alex: Yes. If you type #150 in the same repository, GitHub links to issue or pull request number 150. If the issue is in another repository, you can use owner/repo#150.

Jamie: And those references show up in the timeline.

Alex: They do. That makes the history traceable. If a pull request mentions an issue, the issue timeline can show that connection, and the pull request becomes part of the story.

Jamie: What about closing keywords?

Alex: In a pull request description, phrases like fixes #150, closes #150, or resolves #150 can automatically close the issue when the pull request is merged. Those keywords can also appear in some issue comments, but the most common workflow is a pull request that resolves an issue.

Jamie: So issues describe the work, and pull requests propose the change.

Alex: Exactly. They are separate objects, but they work together. An issue can explain the problem, and a pull request can contain the commit history, file changes, discussion, and review that solve it.

Jamie: Where do sub-issues fit?

Alex: Sub-issues are parent-child relationships for breaking a large issue into smaller tracked pieces, when the repository has that feature available. A parent issue can show a progress indicator as child issues are completed.

Jamie: How is that different from a task list in the issue body?

Alex: A task list is a checklist inside one issue. A sub-issue is its own issue, with its own title, comments, labels, assignee, and status. Use sub-issues when each piece deserves separate tracking or discussion.

Jamie: And the optional extension asks learners to add one if the feature is available.

Alex: Yes. Open the issue you created, look for Sub-issues or Add sub-issue, create a new child issue with a specific title and short description, and confirm it appears nested under the parent.

Jamie: Maintainers and triagers have a few extra controls, right?

Alex: They do. They can assign issues, apply and remove labels, set milestones, close issues, reopen issues, and sometimes transfer or delete issues depending on permissions.

Jamie: Assigning yourself means you're taking responsibility for the work.

Alex: Yes, or at least signaling that you're the person currently handling it. Labels communicate type and status, such as bug, enhancement, documentation, help wanted, or needs triage. Milestones group work into a release, sprint, workshop checkpoint, or project goal.

Jamie: What does closed mean?

Alex: Closed means the issue is no longer active as open work. It might be completed, it might be a duplicate, it might be out of scope, or it might be closed as not planned. A good close usually includes a reason or a comment so readers understand what happened.

Jamie: And reopening is allowed when new information changes the situation.

Alex: Exactly. If the bug returns, the fix was incomplete, or the issue was closed by mistake, reopen it and explain why. Reopening without context can confuse people, so add a comment that names the new evidence.

Jamie: Transfer and delete sound more serious.

Alex: They are. Transferring moves an issue to a different repository, which can be useful if it was filed in the wrong place. Deleting removes it from view and is usually reserved for spam, sensitive content, or mistakes that should not remain public.

Jamie: And good first issue is the label new contributors often look for.

Alex: Yes. It marks work that maintainers believe is approachable for someone new to the project. Still read the issue carefully, check recent comments, and make sure nobody else is already actively working on it before you jump in.

Alex: If you prefer the terminal, GitHub CLI can handle much of this issue workflow.

Jamie: But first, make sure you're in the right repository.

Alex: Exactly. Run git remote -v to see what remote your local clone points to, and gh repo view to confirm the GitHub repository context. That prevents you from listing or commenting in the wrong place.

Jamie: Then you can list assigned issues.

Alex: Yes. gh issue list --assignee @me shows issues assigned to you in the current repository. gh issue view 123 lets you read one issue. gh issue comment 123 --body "Thanks, I can reproduce this" posts a comment.

Jamie: And creating an issue can be interactive or inline.

Alex: Right. gh issue create prompts for title, body, labels, and assignees. If you want to provide everything in one command, use options like --title, --body, --label, and --assignee. For example, gh issue create --title "Broken setup link" --body "The accessibility settings link returns 404." --label documentation.

Jamie: What about editing metadata from the terminal?

Alex: gh issue edit 123 --add-assignee @me can assign yourself. You can use --add-label, --remove-label, and --milestone when you have permission. gh issue close 123 closes an issue, gh issue close 123 --comment "Fixed in #151" adds context, and gh issue reopen 123 reopens it.

Jamie: The CLI is powerful, so the safest habit is still read, act, confirm.

Alex: Yes. Read with gh issue view, make one focused change, then confirm with gh issue view or gh issue list. And when in doubt, use gh issue --help or gh issue edit --help rather than guessing at options.

Jamie: Let's talk specifically about accessibility issue writing.

Alex: A strong accessibility issue names the barrier, where it happens, what technology was involved, and what the expected accessible behavior should be. For example: "In welcome.md, the banner image is referenced without alt text. A screen reader user does not receive the same information conveyed visually. Add concise alt text that describes the purpose of the image."

Jamie: That is much more useful than "accessibility is broken."

Alex: Yes. For accessibility reports, include browser, operating system, screen reader or magnification tool if relevant, zoom level if it matters, steps to reproduce, actual behavior, and expected behavior. If you can describe severity without exaggerating, do that too.

Jamie: Feature requests need a slightly different shape.

Alex: They do. A good feature request explains the user need, the proposed behavior, why it helps, and any alternatives you've considered. It should leave room for maintainers to discuss the design instead of demanding one exact implementation.

Jamie: The chapter's learning cards are meant to reinforce these habits.

Alex: Yes. They summarize navigation, filtering, reading, commenting, filing, cross-referencing, sub-issues, managing issues, the good first issue label, and accessibility-specific writing. Use them as quick review prompts after you've practiced the workflow once.

Jamie: What should someone do if they get stuck?

Alex: First, slow down and reorient. On the web, use headings, landmarks, the issue title, and the issue number in the page title or URL. In NVDA, check whether you're in Browse Mode or Focus Mode. In the terminal, confirm the repository with gh repo view before running issue commands.

Jamie: And if the issue did not appear?

Alex: Check whether the form has required fields, whether a template picker is still waiting for a choice, or whether you are in the wrong repository. After submitting, the new issue page should load, the title should be a heading, and the issue number should appear in the URL.

Jamie: How do learners submit evidence for the chapter?

Alex: Go to your assigned Challenge 2 or Challenge 3 issue and post a comment that says Chapter 5 completed, then include the issue number you created, the issue number where you commented with an @mention, and the optional sub-issue number if you made one. After that, close your assigned challenge issues so the facilitator can review your activity.

Jamie: So the expected outcome is not just that an issue exists. It's that the learner can create one clearly, participate respectfully, use metadata and references, and confirm the work is visible.

Alex: Exactly. Manual issue work builds the judgment you'll need later when tools or agents help with triage. If you can read the thread, understand the labels, ask a good question, and verify the result yourself, you're ready for the collaboration that comes next.

Transcript

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.

Transcript

Alex: Welcome back. Challenge 03 is called Join the Conversation, and it is the first time Day 1 asks you to participate in someone else's GitHub issue thread.

Jamie: This is comments, mentions, and reactions, right? The social parts of GitHub that can feel small until you actually need them.

Alex: Exactly. You are going to open a peer-simulation issue, leave a meaningful comment, use an @mention, and add a reaction to the original issue.

Jamie: So we are not editing files yet. We are practicing how collaboration sounds on GitHub.

Alex: Right. No branch, no commit, no pull request for this challenge. Your work happens in the issue conversation, and your evidence is the URL of the comment you posted.

Jamie: Where are learners doing this? Is it still the Day 1 repository?

Alex: Yes. You are in your Learning Room repository, the private repository provisioned for you for Day 1. That is where the early contribution path happens: issue, branch, commit, pull request, and merge, one skill at a time.

Jamie: And Challenge 03 comes after filing your first issue in Challenge 02.

Alex: Yes. Challenge 02 gets you comfortable creating an issue with a clear title and body. Challenge 03 shifts from filing your own report to joining a conversation around someone else's report.

Jamie: The classroom setup also says the Student Progression Bot opens the next challenge when you close the current challenge issue.

Alex: That is the normal flow. Complete the challenge, add the requested evidence, and close the assigned challenge issue when you are done. If anything is different for your cohort, follow your facilitator's instructions.

Jamie: Good. So learners should not go hunting for branches or files during this one.

Alex: Correct. Chapter 5 is issue practice. File editing starts later.

Alex: Start from your Learning Room repository page and open the Issues tab. If GitHub keyboard shortcuts are active for you, pressing G and then I can take you there.

Jamie: And if that shortcut does nothing, it is not a failure. Just use the repository navigation and find Issues.

Alex: Exactly. On the Issues page, you are looking for an issue titled Peer Simulation: Welcome Link Needs Context. If your facilitator assigned a real buddy repository, you may use your buddy's Challenge 02 issue instead.

Jamie: What if the peer-simulation issue is not obvious in the list?

Alex: Use the filter bar or the label filters and look for the peer-simulation label. You can also check whether you are viewing open issues, because closed issues may be hidden depending on the current filter.

Jamie: And a direct link from the facilitator is fine too.

Alex: Definitely. The important part is that you open the issue, read it, and respond to what it actually says.

Jamie: Let's make sure the word issue is clear. What is a GitHub issue, in plain language?

Alex: A GitHub issue is a trackable conversation about work. It might describe a bug, a missing document, an accessibility barrier, a question, or a feature request.

Jamie: So it is not just a complaint box.

Alex: Right. A good issue gives the team something they can act on. It usually includes what happened, what was expected, where it happened, and any useful context.

Jamie: What does the Issues list feel like with a screen reader?

Alex: You will usually hear a list of issue titles, status information such as open or closed, labels, authors, comment counts, and timestamps. Many learners move by headings to jump between issue titles more quickly than arrowing through every item.

Jamie: And NVDA users may switch modes depending on what they are doing.

Alex: Yes. Browse Mode is useful for reading headings, links, and issue text. Focus Mode is useful when you are typing into the search box or comment box. NVDA plus F7 can also open a list of headings, links, form fields, buttons, and landmarks when you need to re-orient.

Jamie: Low-vision learners should also know that zoom can change layout, but the pieces are still there.

Alex: Exactly. Look for the Issues tab, the search or filter bar near the top, the open and closed filters, and then the issue titles. At high zoom, some navigation may wrap or move, so use page search if you need to find the word Issues or the issue title.

Alex: Once the peer issue is open, read the description before you type. Your comment should respond to the specific situation, not just say that you agree.

Jamie: What would a strong comment sound like here?

Alex: Something like: @gandalf-bot Good catch on the missing context in welcome.md. I found the same issue near the welcome link, and I think adding one sentence that explains where the link goes would help new readers.

Jamie: That gives a location, confirms the observation, and suggests a possible fix.

Alex: Yes. You could also ask a clarifying question. For example: @gandalf-bot Is the goal to explain the link before the user opens it, or should the link text itself be more descriptive?

Jamie: That is much more helpful than a bare plus one.

Alex: Exactly. A good comment is specific, encouraging, constructive, and actionable. It helps the next person decide what to do.

Jamie: Let's slow down on @mentions, because that little symbol can be stressful the first time.

Alex: An @mention is the at sign followed immediately by a GitHub username, with no space. GitHub turns it into a link and usually sends that person a notification.

Jamie: For the simulation, the username is @gandalf-bot.

Alex: Yes. If you are using a real buddy repository, mention your buddy's exact username instead. Spelling matters, and the username must match exactly.

Jamie: So @ space gandalf-bot will not work.

Alex: Right. There should be no space between the @ and the username. After you post, check that the mention renders as a clickable link in the comment.

Jamie: And the reason is not just technical. You are signaling who should see the message.

Alex: Exactly. In open source, people often work in different time zones and read threads later. Mentions help route attention without needing everyone in the room at the same time.

Alex: The challenge also asks you to add a reaction to the original issue.

Jamie: Like a thumbs up, hooray, or heart?

Alex: Yes. Reactions are lightweight signals. They can acknowledge an issue, show agreement, or thank someone without adding another comment that says the same thing.

Jamie: How do I add one if I am using a screen reader?

Alex: Look near the issue description or comment for the button labeled Add reaction. Activate it, choose the reaction you want, and then confirm that the reaction count or icon appears.

Jamie: Is a reaction alone enough for Challenge 03?

Alex: No. The required evidence is a thoughtful comment with an @mention. The reaction is an additional collaboration feature you are practicing.

Jamie: The challenge form asks for evidence. What should go there?

Alex: Paste the URL of the comment you left on the peer-simulation issue or buddy issue. You can also add a short note such as: I commented on the peer-simulation issue about the welcome link, and I added a reaction to the original issue.

Jamie: How do you get a direct comment URL?

Alex: Each comment has a timestamp or a small menu that can lead to a link for that comment. If that is hard to find, copy the issue URL and describe which comment is yours, but a direct comment link is best when you can get it.

Jamie: And there is a peer check too.

Alex: Yes. If your facilitator gave you a real buddy, check whether they commented on your issue and reply. If you are using the simulation, reply to Gandalf or to your own peer-simulation comment with one follow-up thought.

Jamie: So completion is not about writing a perfect paragraph.

Alex: Right. One thoughtful comment with an @mention is enough evidence, as long as it actually participates in the conversation.

Alex: The culture behind this matters. Open source communication is usually written, asynchronous, and visible to more people than the two people talking.

Jamie: Which means tone has to do extra work, because nobody can hear your facial expression.

Alex: Exactly. Helpful feedback often starts by acknowledging what is working, then identifies a specific concern, explains why it matters, and suggests a path forward when possible.

Jamie: Can you give a tiny example?

Alex: Sure. Instead of saying, You wrote this wrong, try: The current link text may be hard to understand out of context. Could we make it more descriptive, such as Read the setup guide?

Jamie: That comments on the content, not the person.

Alex: Yes. Use we when it fits, describe the code or documentation instead of the author, and use tentative language when you are not sure. Words like might, could, and I think can make room for discussion.

Jamie: And do not pile on.

Alex: Right. If someone has already made the same point, a reaction may be better than repeating the criticism. Keep comments focused, and if a thread has been resolved, avoid reopening it unless there is new information.

Jamie: Saved replies can help too, right?

Alex: They can. A saved reply is a reusable comment snippet. For accessibility work, you might save a respectful template for asking for steps to reproduce, assistive technology details, browser version, or expected behavior.

Jamie: What if someone disagrees with my comment?

Alex: That is normal. Say thanks, clarify your reasoning, and be willing to adjust. A good thread can include disagreement without becoming personal.

Jamie: And if feedback feels harsh?

Alex: Pause before replying. Look for the useful information inside the message, ask a clarifying question if needed, and involve a facilitator or maintainer if the behavior crosses a line.

Jamie: What if I realize my own comment sounded blunt?

Alex: Own it plainly. You can say, I see that my wording came across stronger than I meant. Let me restate: I think the link text could be clearer for screen reader users.

Jamie: That is a very real open source skill.

Alex: It is. Respectful repair keeps collaboration moving.

Alex: If you prefer the terminal, the GitHub CLI can handle issue work too.

Jamie: What would that look like for this challenge?

Alex: First confirm you are in the right repository with commands such as git remote -v and gh repo view. Then read before writing with gh issue view followed by the issue number.

Jamie: And commenting?

Alex: You can use gh issue comment with the issue number. Some people let it open their editor, and others provide the comment text inline. Either way, keep the comment focused and verify from the command output or by viewing the issue again.

Jamie: Can the CLI create issues too?

Alex: Yes, gh issue create can prompt for title, body, labels, and assignees, or accept them inline. For Challenge 03, though, the main CLI task would be reading an existing issue and leaving a comment.

Jamie: Let me rehearse the whole thing. Open Issues, find the peer-simulation or buddy issue, read it, comment with a specific point and an @mention, add a reaction, then paste the comment URL as evidence.

Alex: That is it. If you cannot find the issue, filter by the peer-simulation label or ask your facilitator for the link.

Jamie: If the mention does not work, check for a space after the @ and check the username spelling.

Alex: And if you cannot find reactions, look for the Add reaction button near the issue text or comment. Screen readers should hear that label.

Jamie: I like that this challenge is small, but it is not trivial.

Alex: Exactly. You are practicing how real collaboration begins: read carefully, respond clearly, notify the right person, and leave a trace that someone else can follow.

Transcript

Alex: Welcome back. Today we're talking about Markdown, which is one of those skills that shows up everywhere on GitHub: README files, issues, pull requests, comments, wikis, and documentation.

Jamie: And it can look a little strange at first. You see a pound sign before a heading, stars around words, brackets and parentheses for links, and it feels like a tiny code language.

Alex: That's a fair reaction. Markdown is lightweight text formatting. You type plain text with simple punctuation, and GitHub turns it into structured content like headings, lists, links, tables, code blocks, and images.

Jamie: So it's not programming, but it does have syntax. The punctuation tells GitHub how to display the text.

Alex: Exactly. John Gruber created Markdown in 2004 with the goal of keeping writing easy to read as plain text. Under the surface, Markdown becomes HTML, so `**bold**` becomes strong text, and `# Heading` becomes a real heading in the rendered page.

Jamie: Where will learners actually use this during the workshop?

Alex: Almost everywhere. On Day 1, the Learning Room repository is full of Markdown: challenge descriptions, welcome files, issue bodies, pull request descriptions, review comments, and README files. On Day 2, you'll see Markdown in VS Code, in issue templates, in Copilot responses, and in reports from accessibility agents.

Jamie: That makes the Learning Room connection feel important. When someone fixes a link in `docs/welcome.md`, writes an issue, or adds alt text to an image, they're practicing Markdown, not just completing a random task.

Alex: Right. And the reference is designed so you can use it in different ways. If you're new, read from the beginning. If you already know the basics, use the table of contents, heading navigation, or Ctrl+F to jump to the thing you need.

Jamie: I also like that the guide shows raw Markdown, the rendered result, and notes about screen reader behavior. That helps you understand both what you type and what someone experiences after GitHub renders it.

Alex: For practice, you can use a GitHub issue on Day 1, any `.md` file in VS Code on Day 2, or a GitHub Gist if you want a quick scratch space. And Bonus Challenge B, Document Your Journey, is a natural place to apply this because you're writing reflective documentation, portfolio language, and accessible Markdown.

Alex: Let's start with the writing basics. A paragraph in Markdown is just text separated from the next paragraph by a blank line.

Jamie: That blank line matters more than people expect. If I write two lines right next to each other, GitHub may treat them as one paragraph instead of two separate thoughts.

Alex: Yes. If you need a line break inside the same paragraph, Markdown has ways to do it, but most documentation is clearer when you use separate paragraphs. Then headings give the page structure: one `#` for level 1, two `##` for level 2, all the way down to six `######` for level 6.

Jamie: And the levels aren't just visual size. A screen reader can use headings as a map of the page.

Alex: Exactly. Use one main heading for the document, then move in order. Don't jump from level 1 straight to level 4 because you like how it looks. Also avoid the older underline style for headings, because the hash mark style is clearer and more consistent.

Jamie: What about bold and italic?

Alex: Use `**bold**` for strong emphasis, `*italic*` for gentle emphasis, and three stars for bold italic. Use emphasis sparingly, because if everything is emphasized, nothing stands out. GitHub also supports strikethrough with two tildes on each side, which is useful for showing removed text or completed ideas without deleting the history.

Jamie: Lists are another place where Markdown feels friendly. A dash, star, or plus can make an unordered list, and numbers make an ordered list.

Alex: Yes, and GitHub will renumber ordered lists when they render, so many writers just type `1.` for each item. You can also start a numbered list at a specific number when that matters. For nested lists, indent the child items so GitHub understands they belong under the parent item.

Jamie: Mixed lists are useful too. Like a numbered setup process where one step has a few bullet reminders underneath it.

Alex: Exactly. You can also put extra paragraphs, code blocks, or quotes inside list items if you indent them correctly. And a few smaller tools round this out: blockquotes use the greater-than sign, horizontal rules can visually separate major breaks, and a backslash can escape special characters when you want Markdown punctuation to appear literally.

Jamie: Links are where I see a lot of accessibility problems. The syntax is simple, but the writing choice matters.

Alex: The basic pattern is `[link text](URL)`. You can add optional title text, but don't depend on it because not everyone will encounter it. The link text itself should say where the link goes or what it does.

Jamie: So not `click here` or `read more` when the page has ten links like that.

Alex: Right. Write something like `Read the pull request review guide` or `Open the WCAG overview`. Reference-style links are helpful in longer documents because the sentence stays clean and the URL definitions live elsewhere. Relative links are great inside a repository because you can link to `docs/setup.md` without writing the full web address.

Jamie: And GitHub can also autolink some things, right?

Alex: Yes. Plain URLs often become links automatically, and email addresses can be written as mail links. But even when autolinks work, descriptive link text is usually easier to understand.

Jamie: Images use a similar pattern, but with an exclamation point at the front.

Alex: Exactly: exclamation point, square brackets for alt text, then parentheses for the image path or URL. The alt text should describe the meaningful content or purpose of the image. If the image shows a screenshot of a failed test, say what failed and where, not just `screenshot`.

Jamie: What if the image is complicated, like a full architecture diagram or a workflow chart?

Alex: Then short alt text is not enough. Give the image a useful alt text summary, and add a longer explanation nearby, often in the surrounding paragraph or a collapsible details section. Images can also be links, and they can have title text, but again, the core information needs to be available in normal text.

Jamie: Code formatting is another big part of GitHub writing. What's the difference between inline code and a code block?

Alex: Inline code uses single backticks around a short item, like a file name, command, variable, or branch name. For example, you might write `README.md` or `git status` inside a sentence. A fenced code block uses triple backticks before and after a larger example.

Jamie: And after the opening triple backticks, you can add a language name for syntax highlighting.

Alex: Yes. `python`, `javascript`, `bash`, `yaml`, `json`, `markdown`, and `diff` are common examples. The language label helps sighted readers because GitHub colors the code, and it also tells future maintainers what kind of example they're looking at.

Jamie: But a screen reader won't necessarily benefit from the colors.

Alex: Right, so the explanation before the code block still matters. If you're showing a diff, say what changed. If the code block is inside a list item, indent it so the list structure stays intact. And if you need to show literal backticks, use a longer run of backticks around the example.

Jamie: Tables are useful, but they can become hard to navigate.

Alex: A Markdown table uses pipes between columns and a separator row under the header. Colons in that separator row control left, right, or center alignment. You can format text inside cells, but keep the table simple.

Jamie: So a table is good for comparing a few related values, not for building a whole page layout.

Alex: Exactly. Introduce the table before it appears, give every column a clear header, and don't bury complex paragraphs inside cells. If the information reads better as a list, use a list.

Alex: GitHub Flavored Markdown, often shortened to GFM, is Markdown plus GitHub-specific features. It works across many GitHub surfaces, including issues, pull requests, comments, discussions, README files, and other rendered Markdown files.

Jamie: One of the most visible GFM features is the alert block. Those are the callouts like note, tip, important, warning, and caution.

Alex: Yes. They use a blockquote style with a bracketed label, like `[!NOTE]`, followed by the alert text. Choose the type based on meaning: a note adds context, a tip helps someone succeed, important marks something they should not miss, warning points to a possible problem, and caution is for serious risk.

Jamie: And don't use a warning just because it looks dramatic.

Alex: Please don't. Screen readers can encounter the label text, but color and icons are not enough. The words in the alert need to carry the message on their own.

Jamie: The guide also covers collapsible sections with `details` and `summary`. Those are HTML elements, right?

Alex: They are, and GitHub allows them. They're useful for long examples, optional troubleshooting, or extra notes that would otherwise interrupt the flow. The summary should be descriptive, and the content inside still needs proper Markdown spacing. You can nest them, and you can make one start open, but don't hide essential instructions where people might miss them.

Jamie: Task lists feel especially GitHub-y. A dash, a space, then `[ ]` for an incomplete checkbox, or `[x]` for a completed one.

Alex: Exactly. In issues and pull requests, task lists become interactive checkboxes, which makes them great for pre-review checklists. A screen reader user should hear them as checkbox items, so each item needs a clear label like `Update alt text for hero image`, not just `Done`.

Jamie: Mermaid diagrams are powerful, but I always get nervous about accessibility there.

Alex: That's the right instinct. GitHub can render Mermaid code blocks into diagrams such as flowcharts, sequence diagrams, class diagrams, state diagrams, and timelines. But the rendered diagram may not provide enough information to assistive technology users.

Jamie: So if you use Mermaid, write a text equivalent too.

Alex: Yes. Introduce what the diagram shows, provide the Mermaid block if it helps visual readers, and include a plain-language description of the same relationships or steps. If the diagram communicates a process, write the process as text.

Jamie: The guide also includes math expressions with LaTeX syntax. That's the dollar-sign style, right?

Alex: Right. Inline math can sit inside single dollar signs, and block math can be written as a larger displayed expression. It's useful for formulas, but screen reader support can vary, so explain important equations in words nearby.

Jamie: Footnotes are another GitHub feature people discover later. You put a marker like `[^1]` in the sentence and define the note elsewhere.

Alex: Yes. The identifier can be a number or a word, and GitHub creates links between the marker and the footnote. Multi-line footnotes are possible with indentation. They can be handy for citations or side comments, but too many footnotes can make reading feel jumpy.

Jamie: And headings get automatic anchors, which makes tables of contents possible.

Alex: GitHub turns heading text into an anchor by lowercasing it, replacing spaces with hyphens, and removing many punctuation marks. If there are duplicate headings, GitHub adds a number to later anchors. You can link to a heading in the same file, or to a heading in another file, and you can use those links to build a table of contents.

Jamie: There are also autolinked references, like issue numbers, pull requests, commits, and usernames.

Alex: Exactly. `#12` can link to an issue or pull request, an at-mention can notify a user or team, and a commit hash can link to a commit. Pull requests can also use closing keywords like `Fixes #12` to close an issue when the PR merges. Useful, but be careful with mentions because they can notify real people.

Jamie: And GitHub allows some HTML inside Markdown.

Alex: A limited, safer subset. You might see `kbd` for keyboard keys, subscript and superscript tags, line breaks, comments that stay hidden in the rendered page, or `details` and `summary`. But unsafe HTML, scripts, and many styling tricks are stripped or ignored, so use HTML only when Markdown cannot do the job clearly.

Jamie: Can we pull the screen reader behavior together? Because this is where Markdown stops being just formatting.

Alex: Rendered Markdown becomes structured HTML. Headings become navigable headings, lists become real lists, links become links, images expose alt text, tables expose rows and columns, and code blocks are read as code-like text. Good Markdown gives assistive technology useful structure to work with.

Jamie: And weak Markdown removes that structure. Like using bold text as a fake heading.

Alex: Exactly. Common mistakes include forgetting blank lines between paragraphs, skipping heading levels, writing generic link text, leaving image alt text empty when the image has meaning, using bold instead of headings, and dropping in a table without explaining what it contains.

Jamie: The more advanced mistakes matter too: code blocks without language identifiers, inconsistent list markers, Mermaid diagrams without text equivalents, and alert blocks with the wrong type.

Alex: A good authoring checklist is simple to remember. Use real headings in order, write clear paragraphs, make links descriptive, give meaningful images useful alt text, keep lists and tables readable, label code blocks, and use GFM features because they help the reader, not because they look fancy.

Jamie: That checklist also supports portfolio writing. If you're documenting your journey in Bonus Challenge B, accessible Markdown makes your work easier for reviewers, maintainers, and future collaborators to read.

Jamie: The guide ends with a first real Markdown document exercise, which feels like a good low-pressure way to practice.

Alex: It is. You create a short document with a main heading like `About Me`, an introduction, a section about what you want to learn, a setup section that uses emphasis and inline code, a favorite resource with a link and blockquote, a tools table, a workshop checklist, and a collapsible notes section.

Jamie: So by the time you're done, you've touched headings, paragraphs, lists, emphasis, code, links, quotes, tables, task lists, and details sections in one document.

Alex: Exactly. You're done when the file renders clearly, the heading structure makes sense, the links have meaningful text, images if any have alt text, the table has clear headers, and the checklist items are understandable on their own.

Jamie: And then the quick-reference card is there for everyday use: basic formatting, headings, lists, links, images, blockquotes, code blocks, tables, horizontal rules, task lists, alerts, collapsible sections, footnotes, anchors, autolinks, math, HTML, and Mermaid with accessible text.

Alex: The official GitHub writing and formatting documentation is the authoritative place to confirm details, but this reference gives you the workshop version: what to type, what GitHub renders, and how to keep the result accessible.

Jamie: Markdown starts small, but it changes how your work lands. A clear issue, a readable pull request, or a polished README can make collaboration feel easier for everyone.

Alex: That's the goal. Write plain text with structure, check the rendered result, and keep the reader's experience in mind.

Transcript

Alex: Welcome back. Today we're looking at GitHub Gists, which are one of the lightest ways to share code, notes, examples, and small configuration files.

Jamie: So not a whole project, not a full repository, just a quick shareable thing?

Alex: Exactly. A Gist can hold one file or several files, and each file can have syntax highlighting if GitHub recognizes the extension. It's useful when you want to show a snippet, save a small note, or give someone a reproducible example without creating an entire repo.

Jamie: I like that middle ground. Sometimes an issue comment is too cramped, but a new repository feels like overkill.

Alex: That's where Gists fit nicely. They are small, linkable, and still connected to Git, so you can edit them and keep a history of changes.

Jamie: The appendix that this episode goes with also talks about GitHub Discussions. Before we stay with Gists, can we place Discussions in the workflow?

Alex: Sure. GitHub Discussions is the forum-style area for a repository or an organization. It is where questions, ideas, announcements, polls, and community Q&A can live without turning every conversation into an issue or pull request.

Jamie: So an issue says, there is work to track. A discussion says, let's talk, ask, compare, or decide whether there should be work.

Alex: Right. Use an issue for a bug, a specific feature request, or a task that needs labels, assignees, and closure. Use a discussion for questions, brainstorming, community input, or a topic that may not have one final answer.

Jamie: And the categories help set that expectation before anyone replies.

Alex: They do. Common categories include Q&A for support questions, Ideas for brainstorming, Announcements for maintainer updates, General for everything else, and Show and Tell when community members share what they built.

Jamie: Where does the workshop support hub fit into that?

Alex: For alumni, the Community-Access/support repository is the ongoing support home. Read the pinned Start Here resources in Discussions, search existing threads before starting a new one, and use issues when you have a setup blocker or accessibility blocker that maintainers need to track. In Accessibility Agents work, remember that the catalog grows over time, so Discussions are a good place for questions and ideas, while issues are better for concrete changes.

Jamie: If I'm on a repository page, how do I get to Discussions without hunting around forever?

Alex: Look in the main repository navigation near Code, Issues, Pull Requests, Actions, and Projects. If you use keyboard shortcuts, T can move through tab items, and K can help you find links such as Discussions. If the tab is missing, that usually means the maintainer has not enabled Discussions for that repository.

Jamie: And organizations can have their own Discussions too, right?

Alex: Yes. An organization can host community-wide conversations that are not tied to one repository. On a Discussions home page, categories are usually shown with headings, and a side panel may appear on the left or right depending on the width of the view. That panel can show category counts, pinned items, active discussions, and tags if the project uses them.

Jamie: Creating one sounds similar to opening an issue, but with a category first.

Alex: That's the key difference. Activate New discussion, choose a required category, write a clear searchable title, write the body in Markdown, and start the discussion. For Q&A, phrase the title as a real question, because that title becomes part of how other people search later.

Jamie: What should screen reader users expect in that form?

Alex: The path is usually New discussion, category selection, title field, body editor, and Start discussion. The body editor behaves like an issue comment editor, so enter focus mode when your screen reader needs it, type your content, and Ctrl+Enter can submit. Inside a discussion, replies are often exposed as article elements; NVDA and JAWS users may use A to move among them, while VoiceOver users may prefer headings, links, or the rotor depending on browser setup.

Jamie: And participation is more than just replying at the bottom.

Alex: Yes. You can reply to the main thread, reply to a specific comment with a nested reply, upvote useful posts instead of adding plus-one comments, vote in polls, and, in Q&A threads, the discussion author can mark an accepted answer. Low-vision users may also notice answered badges, percentage bars after poll voting, and success banners that can appear above the current zoom position. If the interface changes, GitHub's own documentation is the reference to check.

Jamie: Okay, back to Gists. If I want to make one from the web, where do I start?

Alex: Go to gist.github.com while signed in. You'll get fields for an optional description, a filename, and the file contents. Name the file with a useful extension, like notes.md, example.py, or config.json, because that helps GitHub choose the right formatting.

Jamie: And then I choose public or secret. This is the part where people can get surprised.

Alex: Yes, and it is important. A public Gist is visible and discoverable. A secret Gist is unlisted, meaning it is not meant to appear in public discovery, but anyone with the link can view it.

Jamie: So secret does not mean private.

Alex: Correct. Don't put passwords, tokens, private keys, personal data, unreleased business information, or anything sensitive in a Gist. Treat secret Gist links as shareable links, not access control.

Jamie: What about multiple files? Can one Gist hold a small example with a script and a README?

Alex: Yes. Use Add file in the web interface and give each file its own name and content. That is handy for a short demo where you want a README, a code file, and maybe a sample output file all traveling together.

Jamie: What if I'm already in the terminal and I don't want to open the browser?

Alex: If you use the GitHub CLI, you can create a Gist with gh gist create. For example, `gh gist create hello.py --public --desc 'small Python example'` creates a public Gist from that file with a short description.

Jamie: And if I want it unlisted instead?

Alex: Use the secret option when you mean unlisted, such as `gh gist create config.json notes.md --secret`. You can pass more than one filename, and the files become part of the same Gist. If you're piping text from another command, give the content a filename so people know what they're reading.

Jamie: After the command runs, how do I know it worked?

Alex: The CLI prints the Gist URL. Open that URL, check the filenames, read the rendered content, and make sure the visibility matches what you intended before sharing it.

Jamie: You said earlier that Gists are connected to Git. Does that mean they have history like repositories?

Alex: They do. A Gist is a Git repository behind the scenes, so edits create revisions. You can edit in the browser, review the revision history, and see what changed over time.

Jamie: Can I clone one locally too?

Alex: Yes. On the Gist page, copy the clone URL, or use the CLI with `gh gist clone` followed by the Gist identifier or URL. Once it's local, you can inspect the files in your editor, make changes, commit, and push if you have permission to update that Gist.

Jamie: And comments live on the Gist page, not in my local clone.

Alex: Right. Gist comments are for discussion around the snippet or note. To add one, open the Gist page, move to the comment editor near the bottom, type your message, and submit it much like an issue comment.

Jamie: Gists also have stars and forks. Are those the same as repository stars and forks?

Alex: Similar idea, smaller scale. Starring a Gist saves or signals appreciation for it. Forking a Gist makes your own copy under your account, so you can modify it without changing the original.

Jamie: But I shouldn't expect the whole repository collaboration system.

Alex: Exactly. A Gist doesn't give you the same project structure, issue tracker, pull request workflow, releases, or automation that a full repository does. It is lightweight sharing, not a complete project home.

Jamie: How do I find my own Gists later?

Alex: Use the Gists area from your GitHub profile, go directly to gist.github.com, or visit gist.github.com followed by your username. Screen reader users can move by headings and links to the Gist list, then open titles. You can also browse public Gists through GitHub's Gist discovery areas or arrive at them through links, search results, and community posts.

Jamie: Embedding sounds useful. What does it mean to embed a Gist in a web page?

Alex: It means placing the Gist content inside another page, usually a blog post, lesson, or documentation page. On the Gist page, GitHub provides an embed script you can copy and paste into an HTML page.

Jamie: So the page shows the snippet without me re-copying all the code by hand.

Alex: Yes, and if you update the Gist, the embedded version can reflect that update. For accessibility, don't rely only on the embedded script. Add a short plain-language summary and a direct link to the Gist, so people have another route if scripts are blocked, slow, or awkward with their setup.

Jamie: Give me a few situations where a Gist is the right tool.

Alex: A good one is sharing screen reader configuration notes, like NVDA settings for GitHub web navigation. Another is a quick Markdown note, such as Workshop Day 1 notes, where the content is useful but not a project. A third is a code snippet for an answer on Stack Overflow or in a support thread.

Jamie: And when should I stop and make a real repository instead?

Alex: Use a repository when the work has a project shape: a README, folders, tests, issues, pull requests, releases, permissions, or ongoing collaboration. Use a Gist when the work is small, self-contained, and easy to understand as a snippet or note.

Jamie: So a Gist is great for showing a pattern. A repository is better for maintaining a thing.

Alex: Nicely put. If you expect other people to file bugs, propose changes, run workflows, or follow a roadmap, give the work a repository.

Jamie: Let's end with the safety check, because secret Gists can sound safer than they are.

Alex: They can, and the rule is simple: never put sensitive data in Gists. Public Gists are discoverable. Secret Gists are link-accessible. Neither one is a password vault.

Jamie: If I accidentally put a token in a Gist and then delete the Gist, am I safe?

Alex: No. If a secret or public value was exposed, rotate or revoke it as soon as possible. Deleting the Gist removes the page from your account, but you cannot assume nobody copied the content, cached it, or followed the link while it existed.

Jamie: How do I delete one when I really do want it gone?

Alex: Open the Gist, find its delete control, confirm the deletion, and then verify it no longer appears in your Gists list. For routine cleanup, that's enough. For leaked secrets, cleanup is only the first step; revocation is the real fix.

Jamie: So the everyday workflow is: use Gists for small shareable material, be clear about visibility, and move to a repository when the work needs a real home.

Alex: Exactly. Gists are small, but they're not throwaway. Used well, they make examples easier to share, easier to revise, and easier for someone else to understand.

Transcript

Alex: Welcome back. Today we're talking about GitHub Discussions, which is GitHub's built-in forum space for a repository or an organization.

Jamie: So not an issue, not a pull request, but still part of the project conversation.

Alex: Exactly. Discussions are for threaded community conversations: questions, ideas, announcements, polls, and show-and-tell posts. They sit beside the more action-focused tools, so the community can talk without turning every question into a task.

Jamie: I like that distinction, because a lot of people hesitate before posting. They wonder, am I making work for someone just by asking this?

Alex: And Discussions gives you a softer place to ask, explore, and learn. It is still public project communication, but it does not carry the same meaning as opening an issue or proposing code.

Jamie: Okay, so when do I use Discussions, when do I use Issues, and when do I use a pull request?

Alex: Use an issue when there is trackable work: a bug, a setup blocker, an accessibility barrier, or a specific feature request. Use a discussion when you have a question, want community input, or want to brainstorm before deciding what work should exist. Use a pull request when you are proposing an actual change to files.

Jamie: So if I ask, "How does this agent work with my screen reader setup?" that sounds like a discussion. If I say, "This button has no accessible name," that sounds like an issue.

Alex: Yes. And if you have already changed the code or documentation to fix that button label, then a pull request is the right container for the proposed fix.

Jamie: What kinds of discussion categories should learners expect to hear about?

Alex: Common ones are Q&A for support questions, Ideas for brainstorming, Announcements for maintainer updates, General for open conversation, and Show and Tell for sharing what you built. Q&A is special because one reply can be marked as the accepted answer.

Jamie: That accepted answer part is helpful. It means the thread can stay conversational, but someone can still find the answer quickly later.

Alex: Right. And for workshop alumni, the support hub is a good example of this split. The support home points you to Discussions for community Q&A, and to Issues for trackable support requests like setup blockers or accessibility blockers.

Jamie: Before posting there, read the pinned Start Here resources and search existing discussions. That saves everyone from having the same conversation five times.

Alex: To find Discussions from a repository, open the repository and move through the main navigation where you hear Code, Issues, Pull Requests, Actions, Projects, and sometimes Discussions.

Jamie: And sometimes you will not hear Discussions at all.

Alex: Correct. Discussions is optional. If the tab is missing, that usually means the maintainer has not enabled it for that repository.

Jamie: What about big communities that are not centered on one repository?

Alex: Organizations can have Discussions too. Those live at the organization level, so they are community-wide conversations instead of conversations tied to one repo.

Jamie: So a repo Discussion is about that project, while an organization Discussion might be about the wider community, support process, roadmap, or shared practice.

Alex: Once you land on the Discussions page, categories become your map. Each category acts like a section, and each one can contain many threads.

Jamie: This is where low-vision learners may notice the layout shifting, right?

Alex: Yes. The category panel may appear on the left or right depending on the width of the window and zoom level. It usually shows category names with item counts, pinned posts or announcements, active discussions, and sometimes tags.

Jamie: Those counts are not just decoration. They help you tell where the activity is.

Alex: For keyboard browsing, heading navigation is useful because category names are headings. You can also use link navigation to move through discussion titles, then press Enter to open the thread you want.

Jamie: And if a screen reader has a quick key for tabs or links, the Discussions tab itself is reachable from the repository navigation without needing to visually scan the page.

Alex: Creating a discussion starts from the Discussions tab. Activate the "New discussion" button, then choose a category.

Jamie: The category comes first because it changes the kind of conversation you are starting.

Alex: Exactly. Pick Q&A for a question, Ideas for brainstorming, General when nothing else fits, and so on. Then write a clear title and a body using Markdown, the same style of editor you use for issues and comments.

Jamie: For Q&A, I would make the title a real question, like "How do I use the daily briefing agent with NVDA?" Not just "Help."

Alex: That is much easier to search later. A screen reader path would be: Tab to "New discussion," press Enter, use the category selector, type the title, move to the body editor, enter focus mode if your screen reader needs it, write the post, then activate "Start discussion."

Jamie: And if Ctrl+Enter submits in that editor, it feels familiar because it matches issue comments.

Alex: After creating the discussion, GitHub may show a success message near the top. If you are zoomed in and do not hear or see confirmation, move back toward the top of the page and check where you landed.

Jamie: Once a discussion exists, what does the page feel like?

Alex: It is similar to an issue page. The original post is at the top, replies follow in order, and the reply editor is usually near the bottom. In Q&A discussions, an accepted answer can also be pinned near the top.

Jamie: So I should not assume the first thing after the original post is just the first reply chronologically.

Alex: Right. If the thread is answered, the accepted answer may appear before the regular timeline so people can get to it quickly.

Jamie: How do you move through replies efficiently?

Alex: Use headings to jump between major parts of the thread, and read down through the content when you find the reply you want. GitHub also marks replies as article elements, so NVDA and JAWS users can often press A to jump between replies.

Jamie: And replying is basically the same as commenting on an issue?

Alex: Yes. Move to the reply editor at the bottom, type your message, and submit. If you want to respond to a specific comment, use that comment's "Reply" button, which opens a nested editor under it.

Jamie: Let's talk about marking answers, because that is one of the big differences between Q&A and a normal conversation.

Alex: In a Q&A discussion, the discussion author or a maintainer can mark a reply as the answer. GitHub then shows the thread as answered, often with a green badge or checkmark, and the accepted answer is easier to find.

Jamie: That helps future readers, but it also helps the person who asked the question close the loop.

Alex: Yes. And if the answer reveals that real work needs to happen, the conversation can move into an issue. Some projects allow maintainers to convert a discussion to an issue, which preserves the context while creating something trackable.

Jamie: So a discussion can be the place where the community figures out what is true, and an issue can be the place where the project tracks what to do about it.

Alex: Exactly. Then a pull request is where someone proposes the file changes that solve the issue.

Jamie: Where do polls fit into all of this?

Alex: Polls are a discussion format for collecting community preference. When you create one, you write a title and prompt, add answer options, and post it so people can vote.

Jamie: So it is not a scientific survey, but it is useful for quick direction.

Alex: Right. After voting, people usually see result bars and percentages for the options. For low-vision users, those bars may use color and fill, so listen for or look for the text percentages too.

Jamie: And upvoting is separate from polls.

Alex: Yes. Use the thumbs-up reaction on a discussion or reply when you agree or want to signal importance. That is much better than posting a comment that only says "+1," because maintainers can often scan or sort by reactions.

Jamie: It keeps the thread readable while still letting the community show what matters to them.

Alex: For screen reader navigation, start by treating the Discussions list like a structured page. Use landmarks to find the main content, headings to move between categories or thread areas, and links to open individual discussions.

Jamie: Inside a discussion, the original post, replies, answer area, and editor each become places to orient from.

Alex: Yes. NVDA users can try A for article navigation between replies, and JAWS users can often do the same. VoiceOver users will usually lean on headings, landmarks, and the VoiceOver rotor to move between controls and page regions.

Jamie: And the tab strip shortcut matters too. If your setup supports it, T can move among tab items, and link navigation can help you find the Discussions link.

Alex: When you reach an editor, remember that typing may require focus mode or forms mode depending on your screen reader. The editor behaves like other GitHub comment boxes, so Markdown, preview, and keyboard submission should feel familiar.

Jamie: How does this connect to the Accessibility Agents work in the curriculum?

Alex: The Accessibility Agents collection is a living catalog, so conversation matters. Challenge 15 is browse-first: learners discover agents and patterns without being required to fork that repository just to complete the challenge.

Jamie: That makes Discussions a natural place for questions like, "Which agent fits this task?" or "Has anyone tried this workflow with my assistive technology?"

Alex: Exactly. Completing Challenge 15 unlocks Challenge 16, the Capstone Project, along with Bonus Challenges A through E as a structured path. The capstone can involve Accessibility Agents, GLOW, or another meaningful repository, and review-ready drafts or contribution plans can count as valid evidence.

Jamie: So Discussions can support planning and feedback, even when the final evidence is not a merged code change.

Alex: Right. And earlier Day 1 contribution practice still happens in the learner's Learning Room repository: issue, branch, commit, pull request, and merge. Discussions does not replace that workflow; it gives the community a better place to talk around it.

Jamie: The appendix also pairs Discussions with Gists. Different tool, but still community content.

Alex: A Gist is a small shareable bundle of one or more files. It is useful for a code snippet, a quick Markdown note, a screen reader configuration example, or a short log you want someone else to inspect.

Jamie: So when would I choose a Gist instead of a repository?

Alex: Use a Gist when the thing is small and self-contained. Use a repository when the work needs project structure: issues, pull requests, branches, documentation, releases, tests, or a longer history of collaboration.

Jamie: Give me the practical creation path.

Alex: Open the Gist page, add a filename, type or paste the content, and choose whether to create a public or secret Gist. If you need more than one file, use the add-file control before creating it. Screen reader users can move by form fields and buttons, and file extensions help GitHub apply the right formatting.

Jamie: And examples would be something like NVDA settings for GitHub web navigation, workshop Day 1 notes, or a code snippet you want to reference in a Stack Overflow answer.

Alex: After a Gist exists, you can edit it, view its revision history, embed it in a web page, clone it with Git, or fork it to make your own copy.

Jamie: Finding your own Gists is usually through your profile or the Gist site, and public Gists can also be discovered through search.

Alex: Yes. Gists can have comments too. Open the Gist, move to the comment editor, type your response, and submit it just like other GitHub comment areas.

Jamie: The privacy part is the one I really want learners to hear clearly.

Alex: Public Gists are visible and can be indexed. Secret Gists are unlisted, but anyone with the link can open them. Never put passwords, tokens, private keys, student data, or sensitive logs in a Gist.

Jamie: Secret does not mean protected. It means hard to find unless someone has the URL.

Alex: Exactly. And if you delete a Gist, treat that as permanent. Before deleting, make sure you have saved anything you still need.

Jamie: For anything that changes over time, check GitHub's current documentation for Discussions and Gists. The interface can shift, but the decision pattern stays pretty stable: talk in Discussions, track work in Issues, propose changes in pull requests, and share small standalone notes in Gists.

Transcript

Alex: Welcome back. Today we're working with pull requests, which is where a change stops being just your local work and becomes a proposal for a project to accept.

Jamie: So a pull request is not the change itself, exactly. It's the conversation around whether that change should be merged?

Alex: Right. A pull request, or PR, proposes merging changes from one branch into another branch. An issue is usually the problem, request, or task. The PR is the proposed fix, with the files, commits, discussion, checks, and review all gathered in one place.

Jamie: That helps. An issue can say, "This link is broken," and the PR says, "Here is the branch where I fixed that link. Please review it."

Alex: Exactly. In the Day 1 Learning Room repository, which is provisioned for each learner, that sequence becomes very concrete. Challenge 04 has you create a safe working branch, Challenge 05 has you edit a file and write a useful commit message, Challenge 06 has you open your first pull request, and Challenge 09 returns to final readiness, merging, and verifying that the linked issue closed.

Jamie: Before someone starts clicking around, what should they know about the screen reader experience on GitHub PRs?

Alex: GitHub has an accessibility guide for pull requests, and this chapter adds workshop context for NVDA, JAWS, VoiceOver, low vision users, and people who prefer the terminal. One important detail is the newer Files Changed experience. It adds better landmarks for the file tree and diff area, and for many accounts it is already part of the standard interface.

Jamie: And if someone hears about a feature preview toggle, they should not panic if they cannot find it?

Alex: Right. If the user menu still lists "New Files Changed Experience," make sure it is enabled. If it is not listed, that usually means the feature has graduated and is active already. For NVDA, use Browse Mode for reading conversations, headings, and diffs, then switch to Focus Mode with NVDA+Space only when you need to type in a comment box or search field.

Jamie: That is a small thing, but it can save a lot of confusion. Reading mode for reading, typing mode for typing.

Alex: Yes. Also maximize the browser window if you can. GitHub's landmarks and panels are more predictable when the layout is not squeezed.

Alex: In the chapter practice, the first mini challenge is intentionally small: create one branch change. You open your assigned Chapter 6.1 issue in the Learning Room, go to the file it names, and make only the requested edit.

Jamie: Those files are things like the welcome document, the keyboard shortcuts reference, and the setup guide, right?

Alex: Yes. One issue might ask you to replace a TODO in docs/welcome.md. Another might ask you to fix an incorrect shortcut in docs/keyboard-shortcuts.md, or repair a broken link in docs/setup-guide.md. From the web editor, you activate "Edit this file," make the focused change, and then use "Commit changes" to create a new branch such as fix/yourname-issue42.

Jamie: And the branch is short-lived on purpose. It keeps this one fix separate from main and separate from other workshop work.

Alex: Exactly. When GitHub asks, choose to create a new branch for the commit and start a pull request. That takes you to the Open a pull request page, which is where Challenge 6.2 begins.

Jamie: What should someone check before they press the button?

Alex: Check that the base branch is main and the compare branch is your fix branch. Give the PR a clear title, use the template if one is provided, and write a body that says what changed, why it changed, and how someone can test it. Include a line like Closes #42, using your assigned issue number, so GitHub can close the issue automatically when the PR is merged.

Jamie: How does that change if the work comes from a fork instead of a branch in the same repository?

Alex: The idea is the same, but the compare side points to a branch in another repository. In a same-repository PR, both base and compare are inside one repo. In a fork-based PR, your fork supplies the compare branch, and the original project receives the proposal.

Jamie: And if someone is using local Git instead of the web editor?

Alex: Start from main, create a branch with a command like git checkout -b fix/yourname-issue42, edit the file, commit the change, push the branch, and then open the PR. The chapter's terminal guidance is conservative: check your current branch with git branch --show-current, keep one focused change per branch, include the Closes line in plain text, check status with gh pr checks, and use gh pr --help when you need the current options.

Jamie: Once the PR exists, the page can feel busy. What are the important parts?

Alex: A pull request page has a title, a description body, a list of commits, a Files changed view, reviewers, labels, status checks, and a timeline of comments and reviews. Across the top, the main tabs are usually Conversation, Commits, Checks, and Files changed.

Jamie: How do you get to PRs in the first place?

Alex: You might arrive from a notification, which often opens the specific PR directly. You can also open the repository's Pull requests tab, review the list of open PRs, and use filters to narrow by author, label, or review status. In the terminal, gh pr list shows open PRs, gh pr list --search "review-requested:@me" can find reviews assigned to you, gh pr view 42 shows one PR, and gh pr view 42 --web opens it in the browser.

Jamie: The Conversation tab is the front door, then?

Alex: Yes. It starts with the PR description, then shows status checks, comments, review threads, bot messages, and events such as commits being pushed. If a reviewer leaves a threaded comment, the author can reply, make a change, and resolve the conversation when it is handled.

Jamie: What about the Commits and Checks tabs?

Alex: The Commits tab lets you inspect the sequence of commits included in the PR. The Checks tab shows automated results in more detail, such as whether validation, tests, or accessibility checks passed or failed. If a check fails, open its details and read the message before guessing at a fix.

Alex: The Files changed tab is where review becomes concrete. It shows the actual diff, meaning the line-by-line difference between the base branch and the proposed branch.

Jamie: This is where people hear "green plus" and "red minus," right?

Alex: Yes. Additions are usually shown in green with a plus sign, and deletions are usually shown in red with a minus sign. A plus line means the PR adds that line. A minus line means the PR removes that line.

Jamie: And for low vision users, color should not be the only cue.

Alex: Exactly. Use the plus and minus signs, line numbers, file headings, and screen reader announcements. The newer Files changed experience includes landmarks for the file tree and the diff, so you can move between regions instead of reading the whole page from the top every time.

Jamie: How would you place an inline comment on a specific line?

Alex: In Files changed, move to the line you want, find the line comment control, activate it, type your note, and either add it to a pending review or submit it as a single comment, depending on what GitHub offers in that context. For multi-line comments, select the range of changed lines first; on Windows this may involve the line controls plus Shift selection, and on macOS the pattern is similar with VoiceOver interacting with the diff controls. After comments exist, they appear both in the diff and in the Conversation timeline, so you can read them in either place.

Jamie: Reviewing a PR sounds more formal than just leaving a comment. What changes?

Alex: A review can gather multiple inline comments and then submit one overall result. You can request a review from someone in the reviewers area, and when they review, they usually read the description, scan the files changed, inspect the diff, and leave comments on specific lines when needed.

Jamie: And the final review choices are approve, request changes, or comment?

Alex: Right. Approve means the reviewer is satisfied. Request changes means the reviewer believes something must be fixed before merging. Comment means they are giving feedback without a formal yes or no.

Jamie: Can the terminal help with review, or is this browser-only?

Alex: The GitHub CLI can help. gh pr diff 42 shows the diff in the terminal. gh pr review 42 --approve approves, gh pr review 42 --approve -b "Looks good" approves with a comment, gh pr review 42 --request-changes -b "Please fix the link text" requests changes, and gh pr review 42 --comment -b "I left a note" leaves a comment-only review.

Jamie: Where do suggested changes fit?

Alex: A suggested change is best when the reviewer can offer an exact replacement for a small piece of code or text. A regular comment is better for a broader question, design concern, or accessibility issue that needs judgment. As the author, you can apply one suggestion or batch several suggestions into one commit, which keeps the history cleaner.

Jamie: The chapter practice also includes passing required checks. What is the learner looking for there?

Alex: After opening the PR, wait a short time for the validation bot to respond on the Conversation tab. It checks whether the body includes the Closes #XX link, whether the description is detailed enough, whether the changed files are in the expected Learning Room area, and whether basic accessibility rules pass, such as heading order, descriptive link text, and valid alt text.

Jamie: If the bot says something failed, that is not a disaster.

Alex: Not at all. Open the Files changed tab, inspect the file, edit the branch, commit the fix to the same branch, and let the PR update. Then read the new bot comment or run gh pr checks to confirm the required checks pass.

Jamie: So by Challenge 09, readiness is not just "I opened a PR." It is "the PR is reviewable, checks are green, feedback is handled, and the linked issue will close correctly."

Alex: Exactly. A merge-ready PR gives the maintainer enough information to make a decision without chasing missing context.

Alex: Maintainers also choose how a PR gets merged. The three common options are merge commit, squash and merge, and rebase and merge.

Jamie: What is the plain-language difference?

Alex: A merge commit preserves the branch history and adds a merge point, which is useful when the sequence of commits matters. Squash and merge combines all commits in the PR into one commit on main, which is great for small workshop fixes or messy work-in-progress histories. Rebase and merge replays the commits onto main for a linear history, which some projects prefer when each commit is already clean and meaningful.

Jamie: Where do draft PRs fit into that story?

Alex: A draft PR says, "Please look if you want, but this is not ready for final review." Use it when you want early feedback, need checks to run, or want to share progress without asking for approval yet. In the browser, you can create a draft, later mark it ready for review, or convert an open PR back to draft if the project allows it.

Jamie: And the CLI has that too?

Alex: Yes. gh pr create --draft creates a draft PR, gh pr ready marks it ready, gh pr view --json isDraft can confirm the state, and gh pr list --draft lists draft PRs. Auto-merge is another maintainer tool: when it is enabled, GitHub can merge after required reviews and checks pass. You can also cancel auto-merge, and after a PR is merged, many projects delete the branch and verify that linked issues closed.

Jamie: What are the common real-world situations learners should be ready for?

Alex: If you are assigned to review a PR, start with the description, then read the checks, then inspect Files changed. If you are responding to review feedback on your own PR, reply to comments, make focused commits, and resolve conversations only when the concern is actually handled.

Jamie: And the scary one: merge conflicts.

Alex: A merge conflict means Git cannot automatically combine two sets of changes. For this chapter, the key move is to stop and read the conflict message carefully. Depending on the project, you may fix it in the web editor, pull the branch locally, or ask a facilitator or maintainer before making a risky edit.

Jamie: What mistakes should people avoid?

Alex: Avoid huge PRs that mix unrelated work, vague titles like "fix stuff," missing Closes lines, missing testing notes, and descriptions that repeat the title without explaining anything. Also avoid changing files outside the issue's scope unless the maintainer asked for it.

Alex: A good PR description answers three reviewer questions quickly: what changed, why it changed, and how to test it.

Jamie: That seems simple, but it is exactly what I look for when I open someone else's PR.

Alex: A useful template might include Summary, Changes made, Related issues, Testing, Screenshots or recordings, and a short checklist. In text-heavy documentation PRs, screenshots may not apply, but testing still does: you can say you checked the Markdown preview, verified the link, or confirmed the heading order.

Jamie: And the Closes #XX pattern belongs in Related issues?

Alex: Yes. Before and after structure also helps. Instead of saying "updated docs," say "Before: setup-guide.md linked to an outdated accessibility settings page. After: the link points to the current setup page and the surrounding sentence explains what the reader will find."

Jamie: Can learners practice by reading a real PR, even before they are comfortable reviewing?

Alex: Absolutely. Open a PR in the Learning Room, read the description, check whether it references an issue, read the bot comment, then move to Files changed and identify what lines were added or removed. You do not have to judge everything at first. Just follow the trail from description to conversation to diff.

Jamie: And later, tools like a PR review agent can help draft observations, but they do not replace reading the PR yourself.

Alex: Exactly. Review at least a couple of pull requests manually before leaning on automation. An agent can summarize a diff, suggest comments, or help organize risks, but you still bring the project context, the accessibility judgment, and the final decision.

Jamie: So the workflow is small branch, useful commit, linked PR, readable description, checks, review, and then a merge strategy that fits the project.

Alex: That is the heart of it. Pull requests are not just a button on GitHub. They are the shared workspace where a change becomes something the project can trust.

Transcript

Alex: Welcome back. Challenge 4 is called Branch Out, and it is one of those small GitHub moves that makes everything after it safer. You're going to create a personal branch for Day 1 work, named `learn/YOUR-USERNAME`.

Jamie: This is the moment where I always want to ask the basic question. Why make a branch at all if I'm just practicing in my own private repository?

Alex: Because `main` is the stable copy of the project. A branch is a separate line of work, so you can try an edit, make a commit, and later open a pull request without changing `main` right away. If something goes sideways, your main branch is still clean.

Jamie: So the branch is not extra ceremony. It's a safety rail.

Alex: Exactly. And in the Learning Room, that safety rail is part of the real workflow: issue, branch, commit, pull request, review, merge. Challenge 4 is where that chain starts to feel practical.

Jamie: And just to ground where we are, this is happening in the Learning Room repository, not in the original template repository.

Alex: Your Learning Room is the private repository GitHub Classroom created for you from `Community-Access/learning-room-template`. Its name looks like `<workshop-org>/learning-room-<your-username>`, and it is where your Day 1 contributions happen.

Jamie: The setup path is: open the Classroom assignment link, identify yourself if GitHub Classroom asks, accept the assignment, and wait while GitHub copies the template into the workshop organization.

Alex: Right. When the repository link appears, open it and check a few landmarks: the repository name includes your username, you see files like `README.md`, and you see folders like `docs/` and `.github/`. Bookmark that page, because you'll come back to it all day.

Jamie: And the first challenge issue appears inside that repository, usually after the Student Progression Bot runs. If it doesn't show up after a couple minutes, refresh the Issues tab, then ask a facilitator if needed.

Alex: It's also worth checking the Actions tab once early on. You should see the pull request validation workflow, often called Gandalf, listed there. You don't need to run it yet; you just want to know that feedback will appear later when you open a pull request.

Jamie: There are two practice tracks in this workshop, right? I hear people mention GitHub Skills modules and the Learning Room, and they can sound similar.

Alex: They reinforce each other, but they are not the same. GitHub Skills modules are optional, self-paced practice in your own account, with GitHub's learning bot guiding isolated skills like opening a pull request or writing Markdown. The Learning Room is the required workshop track, where the Day 1 challenge issues, branches, commits, pull requests, checks, reviews, and merges happen.

Jamie: So the optional modules help build confidence, but the Learning Room is the shared workshop path.

Alex: Yes. In the Learning Room, the practice files are in `docs/`. You'll see `docs/welcome.md` with open source contribution sections to complete, `docs/keyboard-shortcuts.md` with screen reader shortcut references, `docs/setup-guide.md` with setup instructions, and `docs/CHALLENGES.md` as the challenge menu.

Jamie: And the repository is private, so I'm not seeing every other student's work in my copy.

Alex: Correct. Peer-simulation issues and pull requests inside your repository give you realistic collaboration practice. Facilitators may also pair students for real peer review when access is intentionally arranged, but your Learning Room starts as your own safe workspace.

Jamie: Let's create the Challenge 4 branch. Where should I be on GitHub?

Alex: Start on the Code tab of your Learning Room repository. Near the top of the file list, find the branch dropdown. Visually it usually shows `main`; with a screen reader, listen for a button labeled something like `Switch branches/tags`.

Jamie: Then I activate that button and type the branch name?

Alex: Yes. Type `learn/` followed by your actual GitHub username. So if your username is `octocat`, the branch name is `learn/octocat`. If your username is `student42`, the branch name is `learn/student42`.

Jamie: And then GitHub offers an option like `Create branch: learn/student42 from main`.

Alex: Activate that option. Now your branch exists on GitHub, created from the current state of `main`. For the evidence box in the challenge issue, write your branch name and a short sentence about how you created it.

Jamie: The issue also asks for a peer simulation check. Open the peer-simulation pull request, notice its branch name, and if you have a real buddy, ask whether they made their branch or help them find the dropdown.

Alex: The naming pattern for this challenge matters because facilitators and automation can recognize `learn/<username>` quickly. It keeps the room organized when many people are working at once.

Jamie: But I saw examples like `fix/welcome-todo`, `feature/add-schedule-link`, and `docs/update-readme` in the reference. Are those wrong?

Alex: No, those are common branch naming styles for regular project work. A pattern like `type/description` is short and descriptive, and you'll see it often. For Challenge 4, though, use the workshop pattern: `learn/` plus your username.

Jamie: What if GitHub says the branch already exists?

Alex: If you already created `learn/<your-username>`, you're done. Switch to it from the same branch dropdown and confirm the name. If you typed the name wrong, create a new branch with the correct name; the old one won't break anything.

Jamie: So the deeper skill is understanding that my work can live away from `main` until I'm ready to propose it.

Alex: You only need one tool for this challenge, but it's useful to know the same idea exists across tools. In VS Code with Git, you can create a branch from the Source Control area or by selecting the branch name in the bottom-left status bar and choosing to create a new branch.

Jamie: And in the terminal, the Git command would be `git checkout -b learn/your-username`, assuming I'm already in the repository and starting from `main`.

Alex: Exactly. In GitHub Desktop, use the Current Branch dropdown, choose New Branch, enter the name, and confirm it is based on `main`. With GitHub CLI, you might clone your Learning Room repository with `gh repo clone <workshop-org>/learning-room-<your-username>`, change into the folder, and then run the Git branch command.

Jamie: Before pushing later, I should check which branch I'm on, especially in a terminal.

Alex: Yes. `git branch --show-current` is a good habit. And later, when you create short pull request branches, keep them focused, link the related issue in plain text, and use documented command help like `gh pr --help` when you need the current options.

Jamie: How does this branch connect to pull requests? We haven't changed a file yet.

Alex: A pull request is a proposal to merge one branch into another, usually your working branch into `main`. The branch is where your change lives; the pull request is where people and bots review it, discuss it, and decide whether it is ready.

Jamie: So later, if I edit `docs/welcome.md` or fix something in `docs/setup-guide.md`, that edit happens on a branch first.

Alex: Right. In the web editor, GitHub can create a branch for you when you choose to propose changes. In Chapter 6 practice, beginners are usually encouraged to use a short-lived branch like `fix/yourname-issueXX` for a focused pull request, rather than mixing everything into the Day 1 practice branch unless a facilitator says otherwise.

Jamie: When opening the pull request, I need a title, a useful description, and a line like `Closes #42` to connect it to the issue.

Alex: Yes. Then the pull request page gives you several places to read. The Conversation tab has the description, comments, review discussion, and status checks. The Commits tab lists commits, the Checks tab shows automation details, and the Files changed tab shows the diff, which means the exact lines added, removed, or changed.

Jamie: For screen reader navigation, Browse Mode is usually the reading mode for headings, comments, and diffs, and Focus Mode is mainly for typing into fields.

Alex: Good distinction. GitHub's pull request interface also supports landmarks and tabs, and the Files changed experience includes better structure for the file tree and diff areas. If something about the interface seems different from a guide, use headings, buttons, landmarks, and the official GitHub accessibility references to re-orient.

Jamie: There are also draft pull requests for work that is not ready yet, reviewer requests when you want feedback, and review outcomes like comment, approve, or request changes.

Alex: Once you open a pull request in the Learning Room, Gandalf usually posts feedback in about 30 seconds. It may check whether you used a `Closes #XX` line, whether the description is detailed enough, whether the files are in the expected area, and whether there are basic accessibility issues like heading order, link text, or alt text.

Jamie: If the bot finds something, I don't have to panic. I read the comment, update the branch, and the checks can run again.

Alex: Exactly. Peer review works similarly, just with a person. A reviewer reads the description, checks the conversation, opens the diff, may leave inline comments, and may suggest changes. As the author, you respond, make updates if needed, and resolve conversations when the discussion is handled.

Jamie: And when review is approved, or when the workshop allows self-merge, the pull request can be merged into `main`.

Alex: After merging, GitHub may offer to delete the branch, and in real projects maintainers may choose merge commit, squash and merge, rebase and merge, or auto-merge when required checks pass. In the Learning Room, merging also lets the progression automation notice your completed work and open the next challenge.

Jamie: What about common problems? Like a reviewer doesn't respond, or I disagree with feedback, or the bot seems wrong?

Alex: Ask for help in the workshop channel, tag a facilitator when appropriate, and explain what you checked. Study groups are fine for talking through ideas, but your repository work should still show your own understanding. And if you are reading someone else's pull request by assignment, be specific, kind, and focused on the change.

Alex: If you're stuck on Challenge 4, start with the branch dropdown. It is near the top-left of the file list on the Code tab, and it may be announced as `Switch branches/tags`.

Jamie: If I finish and want to verify, I can use that same dropdown to switch to `learn/<my-username>` and confirm GitHub shows the branch name.

Alex: Yes. And for reliable facts beyond the workshop notes, use official GitHub documentation about Git, GitHub Flow, pull requests, the GitHub Accessibility Guide for pull requests, and the GitHub CLI help built into the tool.

Jamie: I like that this challenge is small. No file edit yet, no merge yet, just create the safe place where future work can happen.

Alex: That's the win. You made a branch from `main`, named it in the workshop pattern, recorded evidence in the issue, and practiced the first move of a real contribution workflow. From here, your changes have a place to land before they become a pull request.

Transcript

Alex: Welcome back. Challenge 5 is called Make Your Mark, and this is where your Learning Room starts to feel like a real repository instead of a place you are only reading.

Jamie: Because now we are changing an actual file, not just opening issues or looking around.

Alex: Exactly. You will edit `docs/welcome.md`, replace a TODO with real content, and save that change with a commit message that says what changed and why. A commit is a saved snapshot in Git, so this is your first clear record of contribution.

Jamie: And this happens in the private Learning Room repository that GitHub Classroom created for each learner, right? Not in the original template repository.

Alex: Right. Your Learning Room is your own private copy from the classroom assignment, named something like `learning-room-your-username`. Everyone practices the same issue, branch, commit, pull request, review, and merge flow, but your work stays in your own repo unless facilitators intentionally arrange peer review. Day 1 prioritizes Challenges 1 through 6, so this one is part of the core path.

Jamie: Before I touch the pencil icon, where should I be? I can imagine someone accidentally editing in the wrong place.

Alex: Start in your Learning Room repository, then check the branch dropdown. For Challenge 5, you should be on your `learn/YOUR-USERNAME` branch, which is the practice branch you created earlier so your work is separate from `main`.

Jamie: So the branch is a safety rail. I can make the change there first, and main stays stable.

Alex: Yes. The Learning Room was designed for that kind of practice: safe enough to experiment, realistic enough to build real habits, and paced so you are not blocking anyone else.

Jamie: What if someone is listening and thinking, I do not even see my Learning Room yet?

Alex: Then go back to the GitHub Classroom assignment link, make sure you accepted the assignment, and open the repository link when GitHub finishes creating it. If Challenge 1 was missing earlier, the usual check was the Issues tab and then the Actions tab, where the progression workflow and Gandalf PR validation workflow live. By Challenge 5, you should already have that repo bookmarked and your challenge issue open.

Jamie: Okay, what file are we editing?

Alex: Open `docs/welcome.md`. The `docs` folder also contains practice files like `keyboard-shortcuts.md`, `setup-guide.md`, and `CHALLENGES.md`, but Challenge 5 is focused on the TODO you found earlier in the welcome file.

Jamie: The issue says to replace the TODO with real content. Does that mean there is one correct sentence everyone has to use?

Alex: No. The reference solution gives an example, not a required answer. For instance, it replaces a comment like `TODO: add link to workshop schedule` with a sentence that links to the workshop schedule file.

Jamie: So if my TODO is about who can contribute, I write a clear sentence or two that actually belongs in that section.

Alex: Exactly. Keep it small, useful, and related to the TODO. This is not a redesign of the whole page. It is one focused improvement.

Jamie: Walk me through the browser version, because that is the path a lot of people will use first.

Alex: In your Learning Room, confirm the branch dropdown says `learn/YOUR-USERNAME`. Then navigate to `docs/welcome.md`, open the file, and activate the pencil icon labeled `Edit this file`.

Jamie: Then I find the TODO in the editor and replace it with my actual text.

Alex: Yes. After the edit, move to the commit area. Write your commit message, and for this challenge commit directly to your `learn/YOUR-USERNAME` branch.

Jamie: If I use a screen reader, is the pencil icon findable as a button?

Alex: It should be. With NVDA or JAWS, many learners use button navigation to find `Edit this file`. With VoiceOver, the Buttons rotor can help. The important part is to verify the file name and branch before you start typing.

Jamie: What if GitHub offers to create a new branch?

Alex: For Challenge 5, stay with the challenge instruction and commit to your learning branch. In the next pull request work, you will see short-lived feature branches like `fix/yourname-issueXX`, but this challenge is about making one meaningful branch commit.

Jamie: The commit message feels small, but it is doing a lot of work here.

Alex: It is. A message like `Update welcome.md` tells us the file changed, but not what happened. A stronger message is `Add workshop description to welcome.md` or `Replace placeholder text with actual welcome message`.

Jamie: So I should be able to read the message later and know the purpose of the change without reopening the file.

Alex: That is the goal. A good commit message answers two plain questions: what changed, and why it changed.

Jamie: The solution shows a more formal version too, right? Something like `docs: replace TODO with workshop schedule link`, then a short body underneath.

Alex: Yes, and that format is useful. The first line is a short summary, often around 50 characters if you can manage it. Then a blank line can separate an optional body that explains the reason in more detail.

Jamie: But I do not have to use the fancy prefix to pass the challenge.

Alex: Correct. `Fix TODO in welcome.md` and `Add schedule link to welcome page` are both acceptable because they are clear. The convention is helpful, not mandatory.

Jamie: After I commit, what evidence do I need to give back in the challenge issue?

Alex: Paste the commit URL, share the exact commit message you used, and briefly say what you changed the TODO to say. The issue template asks for all three so a facilitator, bot, or future-you can follow the trail.

Jamie: How do I find the commit URL if I have never copied one before?

Alex: After the commit, GitHub usually shows the latest commit near the file or repository view. Open the commit message link, and copy the URL from the address bar. You can also use the commit history for the file if you need to find it again.

Jamie: There is also a peer simulation check in the issue. What is that asking me to notice?

Alex: Compare your commit message with the peer-simulation PR title and commit message in your repo. Ask yourself whether you can tell what changed just by reading the title or message. If you have a real buddy in the workshop, comparing messages is a good way to practice clarity without judging anyone's writing style.

Jamie: What if the GitHub web editor is not the tool I want to use?

Alex: That is fine. On github.com, the pencil icon path is the most direct. In github.dev, you can press `.` from the repository to open the browser-based VS Code editor, edit the file, and commit from Source Control.

Jamie: And if I am working locally?

Alex: You can use VS Code with Git: edit the file, stage with `git add`, and commit with `git commit`. GitHub Desktop works too: edit in your preferred editor, return to Desktop, write the message, and click Commit.

Jamie: So the tool is flexible, but the outcome is not vague.

Alex: Right. The successful outcome is a real edit in `docs/welcome.md` and a descriptive commit message saved on the correct branch.

Jamie: Let us talk about the mistakes people are afraid of, because this is where anxiety can spike.

Alex: The most common one is editing on `main` instead of your practice branch. If you catch it before committing, switch to `learn/YOUR-USERNAME` with the branch dropdown and make the edit there.

Jamie: What if I cannot find the edit button at all?

Alex: Look near the top-right area of the file view for the pencil icon, or search the buttons for `Edit this file`. If the button is unavailable, check that you are in your own Learning Room repo and signed in with the right GitHub account.

Jamie: And the scary one: I accidentally committed to main.

Alex: Ask your facilitator for help. It is fixable, and this is exactly why the Learning Room exists. You are practicing real work in a place where recovery is part of the lesson.

Jamie: If I finished but I am not sure it is good enough, should I copy the solution exactly?

Alex: Use the solution as a comparison, not as a script. Your edit can be different. Check that it replaces the TODO with real content, that the commit message makes sense, and that your evidence points to the commit.

Jamie: How does this connect to pull requests? Challenge 5 is only a commit, but the chapter around it talks a lot about PRs.

Alex: A pull request, or PR, is how a saved change becomes a proposed contribution for review and merge. Challenge 5 gives you the commit habit first, because every PR is made of commits.

Jamie: So later, when I open a PR, the reviewer will see not only my description but also the commits behind it.

Alex: Exactly. A PR page has several important places: the Conversation tab for the description, comments, and bot feedback; the Commits tab for saved changes; the Checks tab for automated results; and the Files changed tab for the diff.

Jamie: Diff means the before-and-after view of the file, right?

Alex: Yes. Removed lines and added lines are shown so reviewers can understand the change. In later PR work, you will also include a line like `Closes #XX` in the PR description so the related issue closes automatically when the PR is merged.

Jamie: And Gandalf reads the PR too?

Alex: Gandalf posts validation feedback on the PR Conversation tab. It can check things like issue linkage, description detail, and accessibility-related file issues. If something fails, you update the branch and the checks run again.

Jamie: That makes the commit message part of a bigger communication chain.

Alex: Yes. A clear commit helps the PR make sense, a clear PR helps review move faster, and review prepares you for contributing beyond the Learning Room.

Jamie: There are a lot of moving pieces around the Learning Room: optional skills modules, peer review, bots, study groups. How much of that matters for this challenge?

Alex: For Challenge 5, keep your attention on the edit and commit. But it helps to know the larger map: GitHub Skills modules are optional self-paced practice in your account, while the Learning Room is the required workshop track for Day 1.

Jamie: And peers do not automatically see everything in my private repo.

Alex: Right. Facilitators may arrange peer review or sharing when it is useful, but your repo is private by default. The usual PR flow is: you open a PR, automation gives feedback, a reviewer may comment, you respond or update, and then the work is merged when it is ready.

Jamie: What if review takes a while, or I disagree with feedback?

Alex: Ask for facilitator help, respond kindly, and keep the conversation tied to the change. Study groups are fine when the workshop allows them, but your evidence and decisions should still be your own.

Jamie: It sounds like this tiny TODO edit is rehearsal for open source communication.

Alex: It is. And if GitHub's interface changes, use current official GitHub documentation, GitHub's accessibility guidance, or your facilitator as references. The labels may move, but the workflow remains: find the right repo, use the right branch, make the smallest useful change, describe it clearly, and leave evidence someone else can follow.

Jamie: So for Make Your Mark, I check my branch, edit `docs/welcome.md`, replace the TODO, commit with a meaningful message, paste the commit URL and message, and compare whether my message is understandable.

Alex: That is the challenge. Small change, clear record, confident next step.

Jamie: I like that. It is not about writing the perfect sentence. It is about making a real contribution that someone else can understand.

Transcript

Alex: Welcome back. Today we're opening the door that turns a branch change into a contribution: Challenge 6, Open Your First Pull Request.

Jamie: This is the one where the work stops being just, I changed a file, and becomes, I am asking the project to accept this change.

Alex: Exactly. A pull request, or PR, is a proposed change from one branch into another branch. It gives everyone a place to compare the branches, read the reason for the change, run checks, and talk before anything lands in `main`.

Jamie: So the PR is not just a submit button. It's the conversation around the change.

Alex: Yes. And in this challenge, the conversation is small on purpose: one branch, one issue, one clear description, and one PR link as evidence.

Jamie: Where are learners working for this one?

Alex: In the Day 1 Learning Room repository. That's the private repository provisioned for each learner, and it's where the Day 1 path happens: issue, branch, commit, pull request, and eventually merge.

Jamie: And the challenge issue itself is titled Challenge 6: Open Your First PR with the learner's username in it, right?

Alex: Right. The public challenge title is Open Your First Pull Request, and the assigned issue may say Open Your First PR with your username. The important part is that you're opening a PR from your working branch back into `main`.

Jamie: This also connects back to the issue from Challenge 2.

Alex: Yes. You filed an issue to describe a need or a problem. Now your PR connects the change to that reason, so the project history tells a complete story.

Alex: Before the PR exists, you need one small branch change. In the chapter practice path, the Learning Room has files like `docs/welcome.md`, `docs/keyboard-shortcuts.md`, and `docs/setup-guide.md`, each with a small problem to fix.

Jamie: So this is not the time to rewrite the whole repository.

Alex: Please don't. If the issue asks you to replace a TODO, fix one broken link, or correct one keyboard shortcut, do that one thing. A focused PR is easier to review, easier to explain, and easier to fix if a check fails.

Jamie: How does the web editor path work?

Alex: Open the file named in your issue, activate the pencil icon or Edit this file button, make the requested change, and then choose Commit changes. In the commit dialog, create a new branch for the commit and start a pull request. The chapter recommends a short-lived branch like `fix/yourname-issueXX`, while some challenge instructions may name `learn/YOUR-USERNAME`; follow the branch name your assigned issue or facilitator gives you.

Jamie: That branch name is a small thing, but it helps you hear what the branch is for.

Alex: Exactly. And if you're using NVDA, JAWS, or VoiceOver, stay in reading mode while you're moving around the page, then switch into the editor or form fields only when you're ready to type. That reduces the feeling of getting trapped in controls.

Jamie: Now we're on the Open a pull request page. What has to be right before creating it?

Alex: First, check the branch comparison. The base branch should be `main`, and the compare branch should be the branch with your change. That comparison is GitHub asking, what is different between these two branches?

Jamie: And then the title.

Alex: The title should tell the story quickly. Something like, Complete the Who Can Contribute section in welcome.md, Fix broken accessibility settings link in setup-guide.md, or Correct NVDA modifier key in keyboard-shortcuts.md.

Jamie: Then the body is where the issue link goes.

Alex: Yes. For this challenge, use a simple structure: `What this PR does`, one sentence about the change; `Why`, one sentence about the reason; and then `Closes #XX`, replacing XX with the issue number. For larger PRs, you may see sections like Summary, Changes Made, Related Issues, Testing, Screenshots or recordings, and a Checklist.

Jamie: What does `Closes #XX` actually do?

Alex: It creates a two-way link between the PR and the issue. The issue shows that it is referenced by the PR, the PR shows that it closes the issue, and when the PR is merged, GitHub closes that issue automatically. `Fixes #XX` and `Resolves #XX` work the same way.

Jamie: That's a surprisingly powerful line of text.

Alex: It is. It connects the change to the reason for the change, which is one of the habits that makes open source collaboration understandable later.

Jamie: After I activate Create pull request, am I done?

Alex: You're done opening it, but not done checking it. In this Learning Room path, the validation bot usually starts within about 30 seconds and posts feedback on the PR Conversation tab.

Jamie: What is the bot looking for?

Alex: It checks whether the PR references an issue with a closing keyword, whether the description is detailed enough, whether the changed files are in the expected Learning Room area, and whether basic accessibility rules pass. That can include heading order, descriptive link text, and valid alt text.

Jamie: If the bot says something failed, that doesn't mean the learner broke everything.

Alex: Not at all. Read the bot comment, fix the specific problem, and update the PR. If the problem is in the description, edit the description. If the problem is in the file, use the Files changed tab or the file editor, commit the fix to the same branch, and let the checks run again.

Jamie: And passing checks show up as green status, when the repository has them configured.

Alex: Right. A complete challenge submission has a clear PR title, a useful description, a linked issue, and passing checks when checks are present. Then you paste the PR URL into the challenge evidence field.

Alex: Let's make the PR page less mysterious. You can arrive there from a notification, from the Pull requests tab in the repository, or from a Compare and pull request prompt after pushing a branch.

Jamie: And if someone is using the terminal?

Alex: The GitHub CLI can list open PRs with `gh pr list`, show a specific PR with `gh pr view`, check status with `gh pr checks`, and open the PR in the browser with `gh pr view --web`. The safest terminal habits are to check your branch first, keep the change small, include the closing keyword in plain text, and use documented help like `gh pr --help` when you're unsure.

Jamie: On the website, the Pull requests list has filters too, right?

Alex: Yes. You can filter by open or closed state, review status, assignee, author, and draft state. If GitHub keyboard shortcuts are enabled, shortcuts can help you move faster, but the reliable path is still the same: find the Pull requests tab, open the PR title, and verify where you landed.

Jamie: What should I listen for on the list page?

Alex: The PR number, title, author, status, and any check or review indicators. A short title is helpful here because it has to make sense when it's heard in a list with many other PRs.

Jamie: Once the PR is open, there are several tabs. I know people get lost here.

Alex: The main tabs are Conversation, Commits, Checks, and Files changed. Conversation is the overview: the PR description, bot comments, human review comments, and status summaries.

Jamie: So Conversation is where I confirm what the PR claims to do.

Alex: Yes. Read the description first, then the bot or reviewer comments. If a review conversation has been answered and fixed, GitHub may let the author or maintainer resolve that conversation, which marks that thread as handled.

Jamie: What about Commits and Checks?

Alex: Commits shows the sequence of commits included in the PR, which is useful when the author made follow-up fixes. Checks shows automated jobs and logs. If something fails, the Checks tab often gives more detail than the short status summary.

Jamie: And Files changed is where the actual diff lives.

Alex: Yes, and it's the tab people often fear at first. GitHub's newer Files changed experience includes better landmark structure for the file tree and diff area; if your account still shows it as a feature preview, you can check the User Menu and Feature preview area, but for many accounts it may already be standard.

Jamie: Let's slow down on the diff. What am I listening for?

Alex: A diff shows what changed in each file. Added lines are usually announced with a plus sign, removed lines with a minus sign, and unchanged nearby lines are context. The left file tree helps you move between changed files when a PR touches more than one file.

Jamie: Can I navigate that with headings and landmarks?

Alex: Yes. Use headings, landmarks, and the tab bar to move to Files changed, then scan the changed file headings. In the chapter's practice example, if the PR touched `docs/welcome.md`, you might hear added lines where TODO sections were filled in; if it touched `docs/keyboard-shortcuts.md`, you might hear changes inside a table.

Jamie: How do inline comments fit in?

Alex: Inline comments attach feedback to a specific diff line or range of lines. You can comment on one line, or select a range for a multi-line comment, then submit it as part of a review. Existing comments can also appear inside the diff, so it's worth reading both the Conversation tab and Files changed.

Jamie: Challenge 6 has a peer simulation check too.

Alex: Yes. Find the Peer Simulation: Improve contribution guidance PR and leave an encouraging comment. If you have access to a real buddy's PR, you may comment there as well, but the full review workflow comes later.

Jamie: The chapter also mentions draft PRs, reviewers, suggestions, and merge options. Do learners need to master all of that for Challenge 6?

Alex: Not all at once, but it's helpful to recognize the words. A draft PR is for work that should be visible but is not ready for final review. You can create a draft, convert an open PR to draft, or mark a draft ready for review when the work is ready.

Jamie: And requesting reviewers is the moment you ask another person to look.

Alex: Right. Reviewers can leave comments, approve, request changes, or submit a comment-only review. They can also use suggested changes, where a reviewer proposes an exact edit and the author can apply it, sometimes batching several suggestions into one commit.

Jamie: Then maintainers decide how to merge.

Alex: Yes. Depending on repository settings, a maintainer may use a merge commit, squash and merge, or rebase and merge. They may delete the branch after merging, or enable auto-merge so the PR merges when required checks pass.

Jamie: And after merge, the closing keyword does its job.

Alex: Exactly. The PR becomes part of `main`, and the linked issue closes automatically if the PR used `Closes #XX`, `Fixes #XX`, or `Resolves #XX` correctly.

Alex: A complete example might have the title, Fix TODO: add workshop schedule link to welcome.md. The body would say what changed, why it changed, and then `Closes #3`.

Jamie: So, not a novel. Just enough context for a reviewer to understand the change without hunting through the issue first.

Alex: Yes. Good PR descriptions avoid vague lines like fixed stuff, and they avoid leaving out testing or issue links. A before-and-after structure can help when the change is visual, behavioral, or accessibility-related.

Jamie: What are the most common stuck points in this challenge?

Alex: If you can't find New pull request, make sure you're on the Pull requests tab. If GitHub says there isn't anything to compare, check that your branch has a commit that differs from `main`, and that you committed to the intended branch. If you forgot `Closes #XX`, edit the PR description after creating the PR.

Jamie: And success is the PR URL, the issue link, and the checks passing when they apply.

Alex: That's it. You opened a PR, compared branches, connected the work to an issue, and practiced the same contribution pattern used by humans, teams, and AI-assisted workflows. AI can help draft changes later, but you now know how to inspect the PR yourself.

Jamie: That feels like a real milestone.

Alex: It is. The first pull request is where GitHub starts to feel less like a website full of buttons and more like a collaboration system you can move through with confidence.

Transcript

Alex: Welcome back. Today we're taking the fear out of merge conflicts. A conflict can look dramatic on the screen, but most of the time it is Git saying, "I found two edits in the same place, and I need a human to choose."

Jamie: That already makes it sound less like an emergency. I think the scary part is seeing those rows of angle brackets and wondering if you broke the project.

Alex: You did not break the project. Conflicts are a normal part of collaboration, including collaboration with AI tools that may rewrite something a human already changed. The skill is reading the choices calmly, keeping the right content, and leaving the file clean.

Jamie: So this is not a punishment from Git. It's a checkpoint where the person with context makes the final call.

Alex: A merge conflict happens when two changes overlap in the same part of the same file. If you change line 12 to say "Submit form" and I change that same line to say "Send message," Git cannot safely guess which one belongs there.

Jamie: The shared document analogy helps me here. Two people edit the same paragraph, and the document app can tell both edits happened, but it cannot know which wording is better.

Alex: Exactly. Git is very good at combining changes that happen in different places. If you edit the introduction and I edit the footer, Git can usually merge that automatically.

Jamie: But if we both edit the same sentence, delete and rewrite the same section, or one of us deletes a file while the other edits it, Git stops.

Alex: Right. Long-running pull requests are another common cause. The longer your branch sits while main keeps changing, the more likely your work and someone else's work will overlap.

Jamie: So conflicts are not rare, and they are not proof that someone made a mistake. They are part of the normal cost of multiple people moving a project forward.

Alex: The thing you read first is the conflict marker block. It usually starts with a line like <<<<<<< HEAD, then one version of the content, then a separator line made of =======, then the other version, and finally a line like >>>>>>> branch-name.

Jamie: Let me slow that down. The first marker says, "the conflict begins here." The row of equal signs separates the two choices. The final marker says, "the conflict block ends here."

Alex: Yes. In the usual merge view, the content between <<<<<<< HEAD and ======= is your current branch's version. The content between ======= and >>>>>>> branch-name is the incoming version.

Jamie: And resolving the conflict does not mean deleting everything that looks weird as fast as possible.

Alex: Please do not do that. Read both sides. Decide whether to keep your version, keep their version, or combine the useful parts into one clean paragraph, table row, or code block.

Jamie: Could you give a small example?

Alex: Sure. Imagine a file called docs/keyboard-shortcuts.md has a table row for saving work. One student adds "Press Ctrl+S to save," while another adds "Use Command+S on macOS or Ctrl+S on Windows." The best resolution might combine them into one clearer row, then remove all three marker lines.

Jamie: So the final file should read like a normal file. No <<<<<<<, no =======, no >>>>>>>, and no leftover duplicate wording unless you meant to keep it.

Alex: In Challenge 07, the Day 1 stretch challenge called Survive a Merge Conflict, you practice this in a safe file inside your Learning Room repository. That Learning Room repo is provisioned for you, and it is where the Day 1 issue, branch, commit, pull request, and merge workflow happens.

Jamie: I like that it is controlled. You are not being dropped into a huge open source conflict with ten files and a blinking cursor.

Alex: Exactly. You open your assigned Chapter 7 challenge issue, the one titled something like "Chapter 7.1: Resolve Conflict Markers (@yourname)." The issue tells you which practice file contains the markers.

Jamie: Then the first practical move is to search for <<<<<<<, right?

Alex: Yes. Use the find command so you can jump straight to it. The chapter suggests Ctrl+F in the browser, and in VS Code you can use its search or find tools; the important part is that these markers are plain text and screen readers can read them.

Jamie: Once I find the block, I read the current branch side, read the incoming side, choose or combine content, delete the marker lines, and search again to make sure nothing remains.

Alex: That's the core of it. Then commit on a short-lived branch named like fix/yourname-issueXX, for example fix/maria-issue48. Open a pull request titled "fix: resolve conflict markers in [filename]."

Jamie: And the PR body should include Closes #XX, plus a sentence or two explaining what content you kept and why. That explanation is part of the evidence, not just decoration.

Alex: If you're resolving this on GitHub.com, the web editor is the primary path for this chapter. GitHub may show a button to resolve conflicts, or you may open the file from your branch and edit the marker block directly.

Jamie: What does that feel like with a screen reader?

Alex: It is text editing. You find the marker, move through the lines, listen to each side, and edit the final wording. The visual editor may show color-coded regions, but the reliable information is still the marker text and the surrounding content.

Jamie: So low vision learners can use zoom or high contrast, and screen reader users can rely on search and line-by-line reading.

Alex: Yes. The chapter includes learning cards for different ways of working: visual and mouse guidance, low vision notes, NVDA and JAWS on Windows, VoiceOver on macOS, and CLI notes for terminal users. Open the cards that match your setup.

Jamie: After the edit, you commit the change in the web editor, check the pull request, and wait for the bot validation checks. If the bot says markers remain, search for all three: <<<<<<<, =======, and >>>>>>>.

Alex: Some learners prefer doing the same work locally with Git. If you cloned your Learning Room in Block 0, the local flow starts by syncing main, then merging main into your feature branch.

Jamie: Say the commands out loud, because this is where people often lose their place.

Alex: From the repository folder, you can run: git checkout main, then git pull origin main. Then switch back with git checkout your-branch-name, and run git merge main. If there is a conflict, Git tells you which files are affected and pauses the merge.

Jamie: Paused is a helpful word. It is not finished, but it is not destroyed.

Alex: Exactly. Run git status and look for entries like "both modified:" to identify the conflicted files. Then open each one in your editor, such as code docs/welcome.md, read the marker block, choose the final content, delete the markers, and save.

Jamie: Then Git needs to be told that the file is resolved.

Alex: Right. Run git add docs/welcome.md, or whatever file you resolved. Then run git commit. Git may auto-fill a merge commit message, or you can use a message like "Resolve merge conflict in welcome.md." Finally, git push updates your pull request on GitHub.

Jamie: So the conflict workflow is merge, status, edit, add, commit, push. And in the middle, the real work is making a thoughtful content decision.

Alex: VS Code can make conflicts easier to inspect, especially on Day 2 when you are working more locally. It shows the conflict markers in the file, and it may offer actions like accept current change, accept incoming change, accept both changes, or compare changes.

Jamie: Those buttons sound convenient, but I would still want to read the result afterward.

Alex: Absolutely. Whether you click an action or edit manually, the final file needs to be clean and meaningful. Search again for marker text before you commit.

Jamie: What about inspecting a pull request from the terminal?

Alex: The GitHub CLI can help. Use gh pr checks to see whether the pull request checks are passing, failing, or still running. Use gh pr diff to review what changed in the PR, which is especially useful after a conflict resolution because you can confirm that you only changed what you intended.

Jamie: So the terminal can show both readiness and the actual difference. That is useful if the web page is noisy or if you want a compact view.

Alex: Prevention helps too. Keep branches short-lived, ideally one to three days when possible, because a branch that lives for weeks has more chances to drift away from main.

Jamie: And sync with main frequently. From your feature branch, that might mean fetching or pulling updates, then merging main into your branch. If you are comfortable with rebasing, git rebase origin/main is another option, but you do not need to start there.

Alex: Communication matters. If two people are about to rewrite the same page, say so in the issue or pull request. Draft PRs are also useful because they make work visible before it is ready to merge.

Jamie: Small PRs help too. A focused pull request is easier to review, easier to merge, and easier to repair if a conflict appears.

Alex: Also avoid mass reformatting unless the team planned it. Reformatting a whole file can create conflicts with every nearby change, even if the actual idea was small.

Jamie: Pull before you push, work in separate files when you can, and do not let a branch become a private island.

Alex: There is also a useful advanced idea called a fast-forward merge. That happens when the target branch has not moved away from your branch, so Git can simply move the branch pointer forward without creating a separate merge commit.

Jamie: And if main has moved, Git may need a regular merge or a rebase, and that is where conflicts can appear. So frequent syncing keeps surprises smaller.

Alex: Sometimes conflicts are actually good. They stop Git from silently choosing between two different intentions, and they force a human review at the exact spot where the project needs judgment.

Jamie: That reframes it nicely. A conflict can protect the work, especially when accessibility wording, instructions, or code behavior could change meaning.

Alex: If you get stuck, ask for help. Read both versions aloud, pick the clearer one, or combine them. If you deleted too much, use Ctrl+Z and try that block again.

Jamie: And if the bot complains, do the simple checks first: search for <<<<<<<, then =======, then >>>>>>>. If any remain, the file is not resolved yet.

Alex: You can also ask a facilitator to sanity-check the final content before opening the PR, or compare your work with the Challenge 7 reference solution after you have tried it. In a messy local situation, starting fresh can be reasonable, but treat that as a last resort after you understand what you would be throwing away.

Jamie: That is reassuring. The first conflict resolution is usually the hardest because you are learning the shape of the problem and the feeling of editing through it.

Alex: For evidence, once your PR is open and passing checks, comment on your assigned issue. Include that Chapter 7 is completed, name the PR number, name the file, and explain whether you kept your version, their version, or combined both, with a brief reason.

Jamie: The summary I am taking away is simple: find the markers, read both sides, decide on the final content, delete the markers, verify with search, commit the resolution, and connect the PR back to the issue.

Alex: If you want a trusted reference while practicing, use GitHub's guide to resolving merge conflicts and the Git book's basic merge conflict material. Those sources match the behavior you will see in real repositories.

Jamie: And the practice prompt is worth doing even if you only read it at first. Open a conflict block, identify the three marker lines, say which side is current and which side is incoming, and describe what clean final content should look like.

Alex: That small rehearsal builds confidence. Once you have resolved one conflict, the markers stop looking like danger signs and start looking like instructions.

Jamie: Which is a pretty good place to end: merge conflicts are not scary. They are editable text, a decision point, and a normal part of contributing with other people.

Transcript

Alex: Welcome back. Challenge 7 is called Survive a Merge Conflict, and I love that title because it names the feeling pretty honestly. A conflict can look alarming the first time, but it is usually just Git saying, "I found two edits in the same place, and a person needs to decide."

Jamie: And this is happening inside the Day 1 Learning Room, right? The private repository each learner gets for issues, branches, commits, pull requests, and merges.

Alex: Exactly. Challenges 1 through 6 are the live core path, and Challenge 7 is available as stretch practice or async follow-up if the room needs more time. In this challenge, a facilitator intentionally creates the conflict so you can practice on something safe.

Jamie: That already lowers the pressure. If it appears, it is not because you broke the project. It is because the exercise was set up to teach you how to read it.

Alex: A merge conflict happens when two changes touch the same part of the same file in different ways, and Git cannot automatically choose the right result. If one person edits line 12 to say "Submit form" and another edits that same line to say "Send message," Git stops and asks for a human decision.

Jamie: So Git can still merge lots of things on its own, like changes in different files or different parts of a file. The conflict is the overlap.

Alex: Right. Common causes include two people editing the same line, one person deleting a file while another edits it, two people reorganizing the same section, or a pull request staying open so long that the main branch moves far ahead.

Jamie: That last one feels very real. The longer a branch sits around, the more chances the project has to change underneath it.

Alex: You can prevent many conflicts by keeping branches short-lived, syncing with main often, and talking with teammates about who is editing what. Small pull requests help too, because a focused change gives Git and reviewers less to compare.

Jamie: And avoid those giant formatting sweeps unless the team agrees first. Reformatting a whole file can make Git think every line changed, even if the actual idea was tiny.

Alex: Yes. Pull before you push, work in separate files when possible, and use Draft PRs when you want early visibility before the work is ready to merge. In Git, a fast-forward merge is the easy case where your branch is simply ahead of main with no competing history, so Git can move the pointer forward without creating a special merge commit.

Jamie: But conflicts are not always bad news. Sometimes they catch the exact place where two ideas need to be reconciled.

Alex: Exactly. A conflict can protect the project from silently losing someone's work. And as AI-assisted workflows become more common, this skill matters there too: an AI agent may generate a change that overlaps with human-written code, and resolving the conflict is part of supervising that work safely.

Jamie: What should a learner expect to see in Challenge 7 itself?

Alex: You start from your assigned Challenge 7 issue and your existing pull request. The facilitator triggers the conflict, and then the pull request may say something like "Can't automatically merge" or "This branch has conflicts." Look near the merge area for a "Resolve conflicts" button.

Jamie: And if the conflict is not there yet, waiting for the facilitator signal is a valid move. There is no need to hunt for a problem that has not been created.

Alex: Yes. The issue description tells you which practice file contains the conflict markers. The branch guidance is the same short-lived pattern from the previous challenge, something like fix/yourname-issueXX.

Jamie: Learners can do this in the browser on GitHub.com, and people who cloned their Learning Room can use VS Code or the terminal instead.

Alex: The web editor is the main path for this challenge because it keeps the workflow close to the pull request. VS Code and local Git are good alternatives if you are already set up locally.

Jamie: Let's talk about the scary-looking part: the actual markers in the file.

Alex: Git writes three marker lines into the file. You may hear or read a line that starts with seven less-than signs, then a middle separator line of equals signs, and then a closing line that starts with seven greater-than signs. In one common PR example, the first section is the HEAD version, often the version on main, and the second section is your branch version.

Jamie: But the labels can depend on the operation, right? In a local merge, "current" and "incoming" may not mean what a learner assumes.

Alex: Exactly. Read the labels and read the surrounding text instead of trusting memory alone. The content between the first marker and the equals line is one version, the content between the equals line and the closing marker is the other version, and the marker lines themselves are never final content.

Jamie: So the job is not to delete the whole conflicted area. The job is to decide what the final file should say.

Alex: Here is a simple example. Before resolution, the file might contain "Welcome to the Learning Room! This is the main branch version" on one side, and "Welcome to the Learning Room! This is my improved version with more detail" on the other. A valid resolved file might keep the improved sentence, keep the main version, or write a new combined sentence that uses ideas from both.

Jamie: All three can be correct if the final text is meaningful and the project is better for it. The mistake is leaving the conflict markers behind.

Alex: On GitHub.com, open your pull request, find the message about conflicts, and choose "Resolve conflicts." GitHub opens an editor and highlights the conflicted area. Read both versions carefully before changing anything.

Jamie: For finding the area quickly, search for the marker that starts with the less-than signs. In the browser, Ctrl+F works well, and in VS Code the editor find tools can jump you there too.

Alex: Then make the content decision: keep one side, keep the other side, or combine them into one clean paragraph or code block. After that, remove every marker line: the opening marker, the equals separator, and the closing marker.

Jamie: I like saying "every marker line" because there are usually three types to check for. Search for the less-than marker, the equals separator, and the greater-than marker before you commit.

Alex: Once the file reads cleanly, use "Mark as resolved," then commit the merge resolution. Your pull request should update, and if everything is clean, it should become mergeable again.

Jamie: The automated check is looking for practical evidence too. No conflict markers should remain, and the file should still contain real, meaningful content.

Jamie: What changes if someone uses VS Code instead of the browser?

Alex: VS Code highlights conflict regions and may offer actions like "Accept Current Change," "Accept Incoming Change," and "Accept Both Changes." Those buttons are helpful, but still read the actual text because current and incoming depend on the merge situation. After accepting both, you may still need to edit the result so it reads naturally.

Jamie: So the button can start the resolution, but it does not replace judgment.

Alex: Exactly. Save the file, review it, and commit the resolution. If you are using Source Control in VS Code, the changed file should appear there after you save.

Jamie: And for terminal users, what is the local Git shape of this?

Alex: From your Learning Room folder, you would update main, switch back to your feature branch, and merge main into it. If Git reports a conflict, use git status and look for files listed as both modified. Open each conflicted file, remove the markers, keep the content you want, and save.

Jamie: Then the resolution becomes a normal commit.

Alex: Right. Run git add for the file, commit with a message such as "Resolve merge conflict in welcome.md," and push. Your pull request on GitHub updates automatically, and you can check the diff, the PR status, and any validation checks.

Jamie: What if someone gets stuck halfway through and feels like they made it worse?

Alex: First, that is normal. If you do not see a conflict, the facilitator may not have triggered it yet. If you cannot find the button, look in the pull request conversation near the merge section, or search the page for "Resolve conflicts."

Jamie: And if the hard part is deciding which text to keep?

Alex: Read both versions aloud if that helps. Keep the clearer version, combine both if both add value, or ask the facilitator for a sanity check. If you accidentally delete too much, undo with Ctrl+Z and work through that conflicted block again.

Jamie: What about the dreaded bot message that says markers are still there?

Alex: Search the file for all three marker patterns: the less-than line, the equals line, and the greater-than line. There should be zero results for the conflict markers. If you want another comparison point, use the reference solution for Challenge 7 or ask someone to review the final text.

Jamie: The chapter also mentions learning cards for different ways of working.

Alex: Yes. There are cards for visual and mouse users, low vision users, NVDA and JAWS on Windows, VoiceOver on macOS, and CLI users. Open the ones that match your setup, and if you need official background, the GitHub guide to resolving merge conflicts and the Git book's basic merge conflict chapter are reliable references.

Jamie: Once the conflict is resolved, what evidence does the challenge ask for?

Alex: Your pull request should be linked to the issue, usually with "Closes #XX" in the body, and the title can be something like "fix: resolve conflict markers in filename." In the description, include one or two sentences saying which content you kept, or whether you combined both, and why.

Jamie: The issue also asks for a plain evidence comment, right? Something like the conflict was in this file, I chose to keep this content, and I resolved it by removing the markers.

Alex: Yes. There is also a peer simulation check: compare your resolution with the facilitator's conflict seed, or with a buddy if you have one. Two valid resolutions can keep different wording, as long as the final file is clean and intentional.

Jamie: You are done when the pull request passes the bot checks, has no marker lines, and is ready to merge. If live time runs out, this is a good async follow-up because the steps leave a clear trail.

Alex: And in the broader Day 1 path, that trail matters. You have used an issue, a branch, a commit, a pull request, a reviewable change, and now a merge conflict resolution inside your own Learning Room.

Jamie: Let me try the short version. A conflict means Git found overlapping edits and needs a human choice, not that the project is ruined.

Alex: Yes. Read both sides, choose or combine the content, delete the marker lines, save, commit, and verify that the pull request is clean.

Jamie: And the professional habit is staying calm enough to read what is actually there.

Alex: Exactly. Merge conflicts are a normal collaboration checkpoint. If you can identify the markers, make a deliberate content decision, and leave the file meaningful, you have survived Challenge 7.

Transcript

Alex: Welcome back. Today we're talking about the human side of open source: culture, etiquette, and community standards.

Jamie: I like this topic because a lot of GitHub anxiety is not really about Git. It's the fear of saying the wrong thing in a public thread.

Alex: Exactly. Technical skills help you make the change. Communication skills help people understand it, review it, trust it, and welcome you back.

Jamie: And this connects to several challenges, right? Challenge 03 has learners joining the conversation with comments, mentions, and reactions, and Challenge 08 asks them to reflect on community norms.

Alex: Yes. Later, Challenge 12 turns this into practice when you review a classmate's pull request. So today is not extra manners on top of the work. It is part of the work.

Jamie: Before we get into tone and review comments, can we ground this in the actual workflow? Where do these conversations happen?

Alex: Most open source projects use GitHub Flow, a lightweight way to propose changes. You create a branch from main, make focused commits, open a pull request, discuss and review, pass checks, and then a maintainer merges the work into main.

Jamie: So the pull request is not just a button you press after coding. It is the place where the explanation, review, and decision all live.

Alex: Right. GitHub Flow works because main stays ready to use, branches are temporary, and small changes are easier to review. A pull request that changes five files is usually kinder to reviewers than one that changes fifty files.

Jamie: Learners may also hear the phrase Git Flow. Is that the same thing?

Alex: Not quite. Git Flow is an older, more complex branching model with long-lived main and develop branches, plus feature, release, and hotfix branches. It fits teams that ship scheduled versions, like mobile apps, desktop software, firmware, or large enterprise products.

Jamie: And this workshop uses GitHub Flow because it is simpler for open source contribution, especially when people are learning.

Alex: Yes. The unwritten rule is one task per branch. If you are fixing missing alt text, that branch should not also rewrite the README, rename files, and change a build script.

Jamie: What about forks? People hear, keep your fork up to date, and it sounds like another hidden chore.

Alex: It is a maintenance habit. If your fork falls behind the original project, your branch can drift away from the current code, and your pull request may be harder to merge. The easiest method is on GitHub.com: open your fork, find the sync option, and update your branch when GitHub says it is behind.

Jamie: And if someone is working in VS Code or the terminal?

Alex: They add the original project as an upstream remote one time. Then the usual sync is: switch to main, fetch upstream changes, merge upstream's main into your main, and push the updated main back to your fork.

Jamie: GitHub Desktop has a path for this too, right?

Alex: Yes. Desktop can fetch, show that your branch is behind, and help you update from the upstream project. The main idea is to sync before starting new work, before opening a pull request, and whenever a maintainer asks you to update your branch.

Jamie: Let's talk commits. A commit message feels tiny, but reviewers really do read it.

Alex: They do. A helpful commit message starts with a short first line in the imperative voice, like Add keyboard instructions to setup guide. If more context is needed, add a blank line and then a body explaining why the change was made. A footer can reference an issue, such as Closes #42.

Jamie: And atomic commits means each commit should be one coherent change, not a suitcase full of unrelated edits.

Alex: Exactly. Common mistakes are messages like update, fix stuff, or final changes. Better messages say what changed: Fix broken skip link target, Clarify installation steps, or Add tests for empty search results.

Jamie: Now the culture part. Open source communication is mostly written, asynchronous, and public. That changes everything.

Alex: It does. Written means people cannot hear your friendly tone unless you put it into the words. Asynchronous means someone may answer hours or days later. Public means future contributors may read the thread to understand what happened.

Jamie: So a short comment can accidentally sound sharp, especially without vocal cues.

Alex: Yes. Prefer wording that points at the code rather than the person. Say, This function returns null when the list is empty, instead of, You forgot the empty case. Use tentative language when you are unsure, like, I might be missing something, or, Could we consider this approach? Also, avoid urgency markers unless something is genuinely urgent, and remember that people may be writing in a second or third language.

Jamie: A lot of learners first participate by writing an issue. What makes an issue description useful?

Alex: Give context, exact steps, expected behavior, and actual behavior. If it is an accessibility issue, include the page or component, the assistive technology or browser when relevant, and the barrier you encountered. For example: I expected focus to move to the dialog title, but focus stayed behind the dialog.

Jamie: And asking for help has a structure too.

Alex: Yes. Say what you are trying to do, where you got stuck, what you already tried, and what kind of help you need. A clear question might be: I am on step 3 of the local setup, the test command returns this error, I tried reinstalling dependencies, and I need help understanding which file to check next.

Jamie: That also respects the fact that maintainers are often volunteers with limited time.

Alex: Right. Give people enough information to help without making them interview you first. Also choose the right channel: use an issue for bugs or feature discussion, a pull request for change review, a discussion thread for open-ended questions if the project uses Discussions, and private reporting only for security or sensitive conduct concerns.

Jamie: Pull request descriptions are their own genre. What should they include?

Alex: A good PR description answers what changed, why it changed, and how someone can test it. Link the related issue if there is one. If the PR is not ready, open it as a draft and say what kind of feedback would help.

Jamie: Documentation has the same community effect. A README is often the first conversation a project has with a new person.

Alex: A solid README includes the project name, what it does, installation, usage, contributing guidance, license information, and any accessibility notes that help people use or test the project. A good README is specific and current. A weak README assumes too much, hides setup steps, or uses vague phrases like just run it.

Jamie: And community health files are where projects make expectations explicit.

Alex: Yes. CONTRIBUTING.md explains how to contribute. CODEOFCONDUCT.md explains behavior standards and reporting paths. SECURITY.md explains how to report vulnerabilities. LICENSE explains what people are allowed to do with the code. On GitHub, you can usually find these files at the top level of the repository, or through the repository's community profile when it is available.

Jamie: Let's get into feedback. What does helpful review feedback sound like?

Alex: It usually starts by acknowledging what is working, then names a specific concern, explains why it matters, suggests a path forward when possible, and signals how important the concern is. For example: The new labels make the form clearer. One concern: this button text may be ambiguous for screen reader users. Could we change it to Save profile so the action is specific?

Jamie: That is very different from, This is confusing.

Alex: Yes. Review the code, not the person. Ask questions instead of making demands. Distinguish personal preference from project requirements. And when the change is good, approve explicitly so the author is not left guessing.

Jamie: Authors have etiquette too. Receiving review can feel personal, especially when you worked hard.

Alex: It can. Start with thank you, then separate the feedback from your identity. If you made a choice intentionally, explain the reasoning. If you are blocked, say so early instead of disappearing from the thread.

Jamie: Comment threads can get messy. What keeps them usable?

Alex: Keep comments focused on the issue or pull request. If a reviewer asks a question and you answer it, do not leave the conversation hanging forever. Resolve conversations when the concern is addressed, but do not resolve someone else's concern just to make the thread look clean.

Jamie: And no piling on.

Alex: Right. If three people have already said the same thing, use a reaction instead of adding another me too comment. Reactions can be useful for agreement, thanks, or acknowledgment without adding noise.

Jamie: The chapter also calls out saved replies as an accessibility win. Why?

Alex: Saved replies let you reuse comments you write often, like thanks for the report, could you add steps to reproduce, or this looks ready to me. They reduce typing load and help keep tone consistent. You create them in GitHub settings under saved replies, then insert one from the comment editor; with a screen reader, the path is still through settings and the comment box controls, just with careful navigation by labels and buttons.

Jamie: Accessibility comments need special care, because the wording can affect whether people feel blamed or included.

Alex: Yes. Describe the barrier and the user impact without shaming the author or treating disabled people as an afterthought. Say, This control needs an accessible name so screen reader users can identify it, rather than, This is bad for the blind. Inclusive language is precise, respectful, and centered on access.

Jamie: There is also a social contract around good first issues.

Alex: Maintainers should scope those issues clearly and leave enough context for a newcomer to begin. Contributors should read the issue carefully, check whether someone is already working on it, ask before expanding the scope, and follow through or communicate if they need to step away.

Jamie: What happens when the conversation gets uncomfortable?

Alex: If you receive harsh feedback, pause before replying. Pull out any actionable information, ask clarifying questions, and ignore the heat if you safely can. If the comment crosses a line, use the project's Code of Conduct process.

Jamie: And if you disagree with a maintainer's decision?

Alex: Disagree with evidence and respect. Explain the tradeoff you see, link to relevant behavior or documentation, and be willing to accept the decision after discussion. The project maintainers carry responsibility for the project, even when you would choose differently.

Jamie: What if you are the one who accidentally caused offense?

Alex: Do not defend the wording first. Acknowledge the impact, apologize briefly, correct the comment or behavior, and move forward. The Code of Conduct exists to make participation safer and clearer, not to scare people away from honest repair.

Jamie: So Challenge 08 is not asking learners to prove they are perfect communicators.

Alex: No. It is one guided reflection in your assigned Chapter 8 issue in your Learning Room repository. There is no bot grading because communication quality is too nuanced for that. You post a comment with three specific behaviors: one respectful review habit, one clear way to ask for help, and one constructive way to respond to feedback.

Jamie: Specific is the key word there. I will be nice is not as useful as, I will include the exact step where I got stuck and what I already tried.

Alex: Exactly. If you get stuck, write one simple sentence per prompt, draft in a text editor first if that helps, borrow the quick-reference style phrases, and ask a facilitator for an example you can adapt. Your evidence is the reflection comment itself, and when it appears with three actionable behaviors, you can close the issue.

Jamie: This also fits the bigger first-time contributor path. Open source is not only for people who write production code all day.

Alex: Anyone can contribute: documentation, testing, accessibility notes, design feedback, issue triage, examples, translations, and code all count when the project needs them. A good first contribution is small, clear, and reviewable. If the change touches many systems, requires a big redesign, or nobody can explain the expected result, it may be too large for a first attempt.

Jamie: After something is merged, the work is not just over and forgotten.

Alex: Say thanks, pull the latest changes, delete old branches when appropriate, and note what you learned. Bonus Challenge B uses that reflection for documenting your journey with accessible Markdown and portfolio language. Bonus Challenge C adds the team version: divide work, communicate status, and make collaboration visible. And when you want to go deeper, the chapter points to GitHub's contributing documentation, Open Source Guides, and related appendices on accessibility standards, Git security, branch protection, and GitHub Pages.

Transcript

Alex: Welcome back. Today we are in Challenge 8, The Culture Layer, and it is a good reminder that open source is not only branches, commits, and pull requests.

Jamie: It is also how people treat each other while all that work is happening.

Alex: Exactly. In your Day 1 Learning Room repository, this challenge asks you to reflect on what made the workshop welcoming, then practice a small triage task by adding a descriptive label to an issue. There is no autograder for communication quality here, because a bot cannot fairly judge whether a reflection is thoughtful.

Jamie: So the evidence is human-readable: a reflection, the issue you triaged, the label you chose, and why.

Alex: Open source projects are communities that happen to use code, documentation, issues, and pull requests as their shared workspace. A project can have excellent technology and still feel hard to join if the communication is confusing, dismissive, or rushed.

Jamie: That lands. A newcomer may be trying to understand the tool, the project, the norms, and the social expectations all at once.

Alex: Right. That is why files like CONTRIBUTING.md and CODE_OF_CONDUCT.md matter. CONTRIBUTING.md explains how to participate, and a code of conduct explains the behavior the community expects. Those files tell you that filing a clear issue, improving docs, asking a useful question, or testing a fix can all be real contributions.

Jamie: And accessibility is part of that culture, not just a feature checklist. If the issue template is hard to follow, the branch names are confusing, or the docs skip context, people can get blocked before they even reach the code.

Alex: Yes. The project README is part of the welcome mat too. A helpful README usually gives the project name, what it does, how to install or run it, how to use it, how to contribute, the license, and any accessibility notes that help people participate.

Jamie: What does the reflection part look like in Challenge 8?

Alex: Start with your assigned Challenge 8 issue in your Learning Room repository. The prompt asks you to think about your workshop experience and answer two or three questions in one or two sentences each. You might write about what made you feel supported, what moment taught you something new, what would make the community more inclusive, or how a peer helped you.

Jamie: I like that it is not asking for a perfect essay. It is asking for a real observation.

Alex: Yes, and specific beats polished. Instead of writing, I will communicate better, you might write, I will include the exact step where I got stuck and what I already tried. Or, I will start a review comment by saying what is working before I suggest a change.

Jamie: Some versions of the chapter ask learners to commit to three collaboration behaviors: a respectful review habit, a clear way to ask for help, and a constructive way to respond to feedback.

Alex: Same skill, just a slightly different shape. The goal is to leave a comment that a facilitator can read and say, yes, this person has named a behavior they can actually practice today.

Alex: After the reflection, you will find an issue to triage. In this challenge, the suggested issue is called Peer Simulation: Welcome Link Needs Context, unless your facilitator gives you a real classmate's issue and you have access to it.

Jamie: Triage means sorting and describing the work, right? Not necessarily fixing it.

Alex: Exactly. Open the Issues tab, open the issue, and read the title and description before you touch the labels. Then find the Labels area in the right sidebar. Activate it, choose one label that describes the issue, and close the menu if needed. The label should appear on the issue.

Jamie: And the common choices here are bug, enhancement, documentation, good first issue, and question.

Alex: Yes. Bug means something is not working as expected. Enhancement means a suggested improvement. Documentation means the issue is about instructions, help text, or guidance. Good first issue means the work looks suitable for newcomers. Question means the issue needs clarification before the team can act.

Jamie: What if I cannot add a label?

Alex: That can happen if you do not have collaborator permission. In that case, leave a comment recommending the label and explain why, or ask the facilitator to check permissions. If you do not see any labels at all, open the Labels page from the Issues tab, near Milestones, or ask whether the default labels need to be created.

Jamie: This is where Challenge 8 starts touching Challenge 9 material, because labels are the doorway into organizing work.

Alex: Exactly. Labels are colored tags on issues and pull requests. They tell the team what kind of work something is, and screen readers announce them with the issue title, such as Label: bug, or Labels: accessibility, good first issue.

Jamie: So a label is not decoration. It changes how easy it is to scan, filter, and prioritize.

Alex: Right. You can filter the issue list by one label, combine labels, combine labels with open or closed state, or search across label names. Maintainers can also create new labels, give them descriptions, and choose colors, though description quality matters more than color for many learners.

Jamie: Where do milestones and projects fit?

Alex: A milestone groups issues and pull requests around a goal, release, or deadline. A GitHub Project is a planning board or table that can track items across a workflow, with fields like status, priority, or assignee. If you are unsure where an issue belongs, Needs Triage is a valid project status because it says, someone still needs to decide.

Jamie: And cross-references are the little links GitHub creates when one issue or pull request mentions another, like number 42.

Alex: Yes. Typing a number sign and an issue number can connect the conversation. Keywords like Closes number 42 are stronger: they close the linked issue when the pull request is merged into the default branch, so use them only when the PR really resolves the issue.

Alex: The culture layer also makes more sense when you remember the workflow underneath it: GitHub Flow. It is the lightweight pattern this workshop uses for contributions.

Jamie: That is the one where main stays safe, and you work on a branch.

Alex: Exactly. You create a branch from main with a descriptive name, make a small change, commit it, open a pull request, discuss and revise, wait for checks to pass, and then a maintainer merges it. The pull request becomes the shared conversation space for the change: what changed, why it changed, how to test it, and what feedback came up.

Jamie: I have heard of Git Flow too. Is that different?

Alex: It is. Git Flow is an older and more complex branching model with long-lived branches like main and develop, plus feature, release, and hotfix branches. It can fit scheduled releases, mobile apps, firmware, or enterprise products, but it is more machinery than we need for this workshop.

Jamie: So here, the habit is one focused task per branch.

Alex: Yes. A branch for one documentation fix, one accessibility improvement, or one small feature keeps review easier. If a pull request tries to fix five unrelated things, the conversation gets harder for everyone.

Jamie: What about keeping a fork up to date? That comes up in open source all the time.

Alex: It does. A fork is your copy of someone else's repository, and syncing it brings in changes from the original project. You sync so your work starts from current code, your pull request is easier to review, and you reduce the chance of conflicts.

Jamie: What is the easiest way in the browser?

Alex: On GitHub, open your fork and look for the sync option near the branch controls. If GitHub says your branch is behind, use the update option to bring your main branch current. Then create your work branch after that, not before, when you can.

Jamie: And if I am in the terminal?

Alex: The first time, you add an upstream remote that points to the original repository. After that, the usual rhythm is: switch to main, fetch upstream changes, merge upstream's main into your main, and push your updated main back to your fork on GitHub. In commands, that often looks like git checkout main, git fetch upstream, git merge upstream/main, and git push origin main.

Jamie: GitHub Desktop can help too, but labels still need the browser, right?

Alex: Correct. Desktop can fetch, pull, and push repository changes, and you can use Repository, View on GitHub when you need issue settings like labels. Sync before starting a branch, before opening a pull request, and any time a maintainer says your branch is out of date.

Alex: Small commits are another part of respectful collaboration. A commit message should help the reviewer understand what changed without opening every file first.

Jamie: What does a good commit message sound like?

Alex: The first line is required and should be short, specific, and written like an instruction: Add missing alt text, Fix broken welcome link, Update contributing guide. If you need more context, add a blank line and then a body explaining why the change was needed. A footer can reference an issue, such as Closes number 42, when that is accurate.

Jamie: And atomic commits means each commit is one coherent change.

Alex: Yes. Do not mix a typo fix, a feature change, and a formatting cleanup in one commit if they could be reviewed separately. Also avoid messages like update stuff or final final. Future you, and your reviewers, deserve better breadcrumbs.

Jamie: The communication advice in this chapter is practical. A lot of open source happens in writing, later, and in public.

Alex: That means comments need context. A helpful piece of feedback usually starts by acknowledging what is working, identifies the specific concern, explains why it matters, suggests a path forward if possible, and makes clear whether the concern is blocking or optional.

Jamie: So instead of, This is wrong, I might say, The new instructions are clear, but this link target seems to skip the setup step. Could we point to the beginner guide instead?

Alex: That is much better. Review the code or the documentation, not the person. Use we language when it fits, describe uncertainty honestly with phrases like I may be missing something, and avoid urgent wording unless something is truly urgent.

Jamie: There is also etiquette around comments themselves: stay focused, do not pile on, resolve conversations when they are handled, and use reactions when a full comment would just add noise.

Alex: Saved replies can help with that. They let you store reusable comments for common situations, like thanking someone for a report, asking for reproduction steps, or explaining how to add accessibility details. For many learners, a saved reply reduces typing effort and helps keep tone consistent.

Alex: Reviewers and authors both have responsibilities. Reviewers should ask questions instead of issuing commands, explain requirements instead of gatekeeping knowledge, separate personal preference from project standards, and approve explicitly when the work is ready.

Jamie: And authors should not have to pretend feedback never stings. But they can still respond professionally.

Alex: Yes. Say thank you, explain your choices, surface blockers early, and ask for clarification when a comment is unclear. If feedback is harsh, pause before responding. If you disagree with a decision, explain the tradeoff and accept the maintainer's call. If someone is rude, use the project's code of conduct or ask a facilitator for help. If you accidentally caused offense, acknowledge it, apologize plainly, and adjust.

Jamie: The good first issue label has a social promise behind it too.

Alex: It should mean the issue is scoped, understandable, and supported enough for a newcomer to attempt. And for accessibility issues, inclusive comments describe the barrier, the affected users or assistive technology when known, the expected behavior, and the impact without blaming the person who reported it.

Jamie: There are also different places to talk, and picking the right one is part of the culture.

Alex: Yes. Use issues for trackable work, pull request comments for feedback on a specific change, project boards for planning status, and discussions or chat for broader questions if the project uses them. Security reports should follow the project's SECURITY.md instructions, because public issues are not the right place for a private vulnerability report.

Jamie: And those community health files are worth checking before you contribute: CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, LICENSE, and the README.

Alex: They answer different questions. How do I help? How do we treat each other? How do I report sensitive problems? What am I allowed to do with this code? What is this project and how do I start?

Alex: To finish Challenge 8, put your evidence in the challenge form or issue prompt. Include your reflection answers, the issue you triaged, the label you added, and why you chose it.

Jamie: A simple example would be: Reflection: I felt supported when a peer explained how they found the Issues tab. I learned that asking a clear question is a contribution. I triaged issue number 12 by adding the documentation label because the issue asks for more context in the welcome link.

Alex: That is exactly the level of detail needed. If you add an optional comment on the issue itself, keep it short and useful: I added the documentation label because this issue helps new contributors understand the welcome section.

Jamie: Alternate approaches are fine too, right? Someone might focus on the code of conduct, the contributing guide, or compare this repo's norms with another project they have seen.

Alex: Yes. What matters is that the reflection shows you understand open source has cultural norms as well as technical steps. If you get stuck, write one simple sentence per prompt, draft in a text editor first if that helps, and ask a facilitator for one example you can adapt in your own words.

Jamie: So Challenge 8 is small on purpose, but it is not minor.

Alex: Right. A respectful label, a clear reflection, and a thoughtful comment are all part of contribution work. They make the repository easier to navigate, easier to review, and easier for the next person to join.

Transcript

Alex: Welcome back. Today we're looking at the part of GitHub that keeps work from turning into a pile of mystery tabs: labels, milestones, projects, and cross-references.

Jamie: I love this topic because it sounds small at first. A label is just a tag, right? But then suddenly it's how a team decides what needs attention, what belongs in a release, and who can help.

Alex: Exactly. Labels, milestones, and projects are the organizing layer on top of issues and pull requests. They help a team sort work by type, status, priority, goal, and timeline. Cross-references connect related conversations so people do not have to hunt through the repository to understand the story.

Jamie: And for learners using a screen reader, that organization is not just nice. If the issue list announces labels and status clearly, you can scan with more confidence instead of opening every issue one by one.

Alex: Yes. The goal is not to decorate issues. The goal is to make the work understandable enough that another person, or even an automated workflow later, can act on it.

Jamie: So where does this show up in the course workflow?

Alex: Chapter 9 is a guided triage chapter. You're working in your Learning Room repository, which is the per-learner repository used for the Day 1 contribution flow. The challenge asks you to inspect an open issue, decide what labels, milestone, and project placement would make sense, and then post a recommendation in your assigned Chapter 9 challenge issue.

Jamie: So learners might not be changing the real labels themselves?

Alex: Right. If you have write access, you can apply the labels and milestone directly. But the required evidence is a structured issue comment that a maintainer could use immediately. That matters because triage is a contribution even when you do not have permission to click every control.

Jamie: What does that comment need to include?

Alex: It starts with the issue number you reviewed. Then you suggest one to three labels, such as documentation, bug, accessibility, enhancement, or good first issue. You recommend a milestone, or you write none with a reason. You choose a project board column such as To Do, In Progress, or Needs Triage. Then you add one sentence explaining why those choices fit the issue.

Jamie: I can imagine getting stuck on the milestone piece. What if I honestly cannot tell where it belongs?

Alex: Then say none, and explain why. That is valid triage. If the project placement is unknown, Needs Triage is the safe default. If the issue itself is unclear, your recommendation can say that the description needs more detail. The learning pattern here is inspect the issue, classify it with shared vocabulary, and explain your reasoning in writing.

Jamie: That also connects nicely to Challenge 08, the Day 1 stretch around the culture layer. Labels and triage are technical, but the way you communicate your recommendation is part of respectful collaboration.

Alex: Exactly. A good triage note does not scold the reporter. It helps the maintainer understand the work faster.

Alex: Let's start with labels. A label is a colored tag applied to an issue or pull request. It communicates a category, status, priority, or audience at a glance.

Jamie: And screen readers announce them with the issue, right? Something like, "Label: bug," or "Labels: accessibility, good first issue."

Alex: That's right. Most repositories begin with a familiar set. Bug means something is not working as expected. Enhancement means a new feature or improvement. Documentation is for docs-only work. Good first issue signals that a task may be suitable for a new contributor. Help wanted means maintainers are inviting community help.

Jamie: And then there are labels that say more about the decision state, like question, invalid, wontfix, duplicate, and needs triage.

Alex: Yes. Question means more information is needed. Invalid means the issue does not fit the project's criteria. Wontfix means the project will not address it, usually because it is out of scope or intentional behavior. Duplicate points to another issue that already covers the same topic. Accessibility is often added as a custom or project-specific label for accessibility-related work.

Jamie: If accessibility is not already there, that does not mean the project cannot track accessibility work. It may mean the team needs to create the label.

Alex: Exactly. A custom label should have a clear name, a useful description, and a color. The color helps visual scanning, but the name and description are what make the label understandable across tools.

Jamie: How do learners find the full label list without guessing from the issue page?

Alex: Open the repository on GitHub.com, go to the Issues tab, and find the Labels link near Milestones in the issue toolbar. In Windows screen readers like NVDA or JAWS, you can move through links with K until you hear Labels, then press Enter. With VoiceOver on macOS, Quick Nav K can find the link, and VO+Space activates it. The Labels page shows each label name, description, and color.

Jamie: And the command line version is pretty direct too.

Alex: Yes. In the repository folder, gh label list shows the labels. If you want names and descriptions in a structured format, you can run gh label list --json name,description. That can be useful if you want your screen reader to read a clean list from the terminal.

Jamie: Once I know which label I want, how do I apply it to an issue or pull request?

Alex: On GitHub.com, open the issue or pull request and move to the right sidebar. Find the Labels heading, activate the edit or gear button, choose labels from the dropdown, and close the dropdown with Escape when you're done. Selections save automatically. You can type part of a label name, like access, to filter the list.

Jamie: What about the other tools people use in this series?

Alex: github.dev, the web editor, is for editing files, so it does not manage issue labels. In VS Code Desktop, the GitHub Pull Requests extension can show issues and let you add or remove labels from the GitHub side panel. GitHub Desktop does not directly manage labels, so use Repository, then View on GitHub, and do the label work in the browser.

Jamie: And with the GitHub CLI, it is gh issue edit or gh pr edit?

Alex: Exactly. For example, gh issue edit 42 --add-label "accessibility,good first issue" adds two labels to issue 42. gh issue edit 42 --remove-label "needs triage" removes one. For a pull request, gh pr edit 15 --add-label "documentation" applies the documentation label to PR 15.

Alex: Filtering is where labels become really useful. If you want only accessibility issues, you do not need to scan the full issue list. You filter by label.

Jamie: In the browser, that can happen from the issue search field or by activating a label link, depending on where you are.

Alex: Right. In the GitHub CLI, gh issue list --label "accessibility" lists issues with that label. To combine labels, you can use more than one label filter, such as gh issue list --label "accessibility" --label "good first issue". Add --state open if you only want open issues. You can also search text across labeled issues with gh issue list --label "bug" --search "keyboard".

Jamie: That is a nice way to answer practical questions. What accessibility bugs are still open? Which documentation issues are good for a first contribution? What is still marked needs triage?

Alex: Yes, and that is why consistent labels matter. If every maintainer labels differently, filtering becomes unreliable. If the vocabulary is shared, the issue list becomes a useful map.

Alex: Milestones organize issues and pull requests around a release, deadline, sprint, or shared goal. A label tells you what kind of work something is. A milestone tells you what goal or time period it belongs to.

Jamie: So a bug label might tell me the type of issue, while a milestone like Version 1.2 or Workshop launch tells me when the team wants it finished.

Alex: Exactly. To find milestones, open the Issues tab and activate Milestones near the Labels link. A milestone usually has a title, description, due date if one is set, and progress information. GitHub shows how many linked issues or pull requests are open or closed, so the milestone becomes a progress tracker.

Jamie: What should I listen for when reading one?

Alex: Listen for the milestone title first, then the due date, then the open and closed counts. The description often tells you the goal. If the due date is close and several blocking issues are still open, that changes the triage conversation.

Jamie: How do you create one?

Alex: In the browser, go to Issues, then Milestones, then New milestone. Give it a short title, add a description, and set a due date if the team has one. From the command line, GitHub CLI can create a milestone through the GitHub API, for example: gh api repos/OWNER/REPO/milestones -f title="Workshop launch" -f due_on="2026-06-30T00:00:00Z". Replace OWNER and REPO with the repository owner and name.

Jamie: And adding an issue to a milestone is similar to labels?

Alex: Very similar. On the issue page, use the Milestone control in the right sidebar and choose the milestone. With the CLI, gh issue edit 42 --milestone "Workshop launch" assigns issue 42. gh issue edit 42 --remove-milestone removes it. To list issues in a milestone, use gh issue list --milestone "Workshop launch".

Jamie: Cross-references feel related, but they are not labels or milestones. What are they doing?

Alex: A cross-reference is a link between GitHub items, usually created when you mention another issue, pull request, or commit. If you type #42 in the same repository, GitHub links to issue or PR 42. If the item is in another repository, you can use OWNER/REPO#42.

Jamie: So if an issue report mentions that it is related to another bug, I can type the number instead of copying the whole URL.

Alex: Yes. You can cross-reference from an issue comment, a pull request description, a commit message, or another discussion area where GitHub supports it. The linked item may also show a timeline event, so people can follow the relationship in both places.

Jamie: Then there are the magic words: closes, fixes, and resolves. I always worry about using those accidentally.

Alex: Good instinct. Closing keywords are powerful. If a pull request description says Closes #42, GitHub will close issue 42 when that pull request is merged into the default branch. A normal comment saying Closes #42 does not close it by itself. Use closing keywords when the work truly completes the issue; otherwise, say related to #42 or see #42.

Alex: GitHub Projects are the planning boards for organizing issues, pull requests, and notes across a team. The current GitHub Projects experience is flexible: you can view the same work as a table, a board, or a roadmap.

Jamie: So the project is not replacing labels or milestones. It is another layer that helps people see status and coordination.

Alex: Exactly. In table view, items are rows, and fields like status, assignee, labels, milestone, repository, or priority appear as columns. Screen readers may announce the row information as you move cell by cell, so column names matter. In board view, work is grouped into columns such as To Do, In Progress, and Done. Roadmap view is timeline-oriented, useful when date fields are part of the project.

Jamie: Where do learners find a project?

Alex: A repository may have a Projects tab, and organizations or user profiles can have projects too. If a project is linked from an issue, you may also find it in the issue sidebar. Permissions matter here: some learners can recommend project placement even if they cannot add the issue directly.

Jamie: And if they can add it?

Alex: Open the issue, find the Projects area in the sidebar, and choose the project. After the issue is in the project, fields like Status can place it in a board column. For the Chapter 9 recommendation, naming a column like Needs Triage, To Do, or In Progress is enough when you do not have direct access.

Jamie: Let's put the pieces together. If I am helping organize work during a hackathon, what would a practical setup look like?

Alex: Start with a small label set people can actually use. Documentation, bug, accessibility, enhancement, good first issue, help wanted, and needs triage are a solid base. If the team has agentic workflows later, labels like needs-review or accessibility-check can also be useful because an automation or agent can watch for them and respond.

Jamie: Then create a milestone for the shared goal, not for every tiny task.

Alex: Right. A milestone such as Hackathon MVP, Workshop launch, or Day 1 cleanup gives the team a target. Issues in that milestone should all support that target. The project board then shows movement: Needs Triage for unclear work, To Do for accepted work, In Progress for active work, and Done when it is complete.

Jamie: That gives maintainers a quick read. The label says what it is, the milestone says where it belongs, and the project says what is happening with it.

Alex: Yes. A simple practice exercise is to open an issue, add or recommend one label, link a related issue with #number if there is one, and write a short triage comment. If you can change the issue, make the update. If you cannot, leave a clear recommendation.

Jamie: And the evidence for Chapter 9 is still the comment in the assigned challenge issue.

Alex: Correct. Close your Chapter 9 challenge issue when the recommendation is posted, and mention whether you also applied labels or a milestone directly. By the end, you should be able to read an issue, classify it thoughtfully, explain your reasoning, and leave a note a maintainer can act on.

Jamie: I like that this chapter makes organization feel like contribution, not admin busywork.

Alex: It really is contribution. Open source depends on people making work easier to understand. If you want more practice after this, GitHub's official documentation covers labels, milestones, and Projects in detail, and the GitHub Skills course on repository management gives an interactive path through related settings. But the core habit starts here: read carefully, choose clear categories, and explain your reasoning kindly.

Transcript

Alex: Welcome back. Today we're taking a deeper look at GitHub Projects, the project management tool built right into GitHub.

Jamie: This is the feature that can look like a board, a spreadsheet, or a timeline, right? I have seen all three and wondered whether they are the same thing wearing different outfits.

Alex: They are views of the same underlying project data. The current GitHub Projects experience is often called Projects v2, and it replaced the older Classic project boards for most day-to-day planning.

Jamie: So if someone sees older references to Projects Beta or Classic Projects, they should not assume those screens are what they will use now.

Alex: Exactly. Classic projects were mainly Kanban boards. Current Projects can use Board, Table, and Roadmap layouts; they support custom fields, stronger filtering, cross-repository tracking, built-in workflows, GitHub Actions integration, and a fuller API through GraphQL.

Alex: A project can start from either an organization or a repository. From an organization page, you open the Projects tab, activate New project, choose a template such as a blank table or blank board, name it, and create it.

Jamie: And from a repository, it is similar, except the Projects tab may offer Link a project or New project depending on what already exists.

Alex: Right. With a screen reader, the creation flow is pretty direct: go to the org or repo Projects tab, tab to the New project button, press Enter, use arrow keys in the template modal, press Enter on the template you want, type the project name, then tab to Create project and press Enter.

Jamie: Low vision learners should also know that the template picker is a grid, so zooming in can make the card names and descriptions easier to compare. And after creation, the Add item row may be near the bottom, so it can be easy to miss at high zoom until you scroll.

Alex: The default layout is Table view. It works like a spreadsheet: every row is an issue, pull request, or draft item, and the columns are fields such as Title, Status, Assignee, Labels, Repository, Priority, or any field you add.

Jamie: That sounds like the safest place to do careful editing. What are the keyboard moves people should recognize?

Alex: In Table view, T can jump you to the table when GitHub keyboard shortcuts are active. Up and down move through rows, left and right move through columns, Enter opens the item detail panel, Escape closes it, Space on a cell edits the value, and F2 on a title cell edits the title inline. A screen reader might announce a row as something like: Fix keyboard trap in modal dialog, Status In Progress, Assignee alice, Priority High, Labels bug and accessibility.

Jamie: Board view is the Kanban one, with columns like Todo, In Progress, and Done. But I want to call out the awkward part: dragging cards is not a good keyboard workflow.

Alex: Yes. To move a card without dragging, open the card with Enter, move to the Status field in the detail panel, open the dropdown, choose the new status, and press Escape to close the panel. Board view is useful for work-in-progress conversations and quick status reviews, but Table view is usually better for precise keyboard editing.

Jamie: And Roadmap view is the timeline. It is helpful for release planning or sprint planning, but because it is chart-based, the data should still be edited in Table view.

Alex: Exactly. Roadmap uses date information, such as Start Date, Due Date, or milestone timing. Items without dates can show up outside the dated timeline, often in an ungrouped area, so if something is missing from the roadmap, check its date fields first.

Jamie: Custom fields are where Projects start to feel less like a static board and more like a planning system. What field types are available?

Alex: You can add Text fields for notes like acceptance criteria or design links. Number fields work well for estimates or story points. Date fields handle deadlines or start dates. Single select fields create a dropdown, which is great for Priority, Size, Type, or Risk. Iteration fields track cycles or sprints.

Jamie: How does someone create one without hunting around forever?

Alex: Table view is usually easiest. Move across the column headers until you reach the plus button at the end, activate it, choose the field type, give the field a name, and configure any choices or date settings. With a screen reader, listen for the column header area and the add field control; after the field exists, you can edit an item's value either in the table cell or from the item's right-side detail panel.

Jamie: Projects can hold real issues and pull requests, but they can also hold draft items. That distinction is easy to miss.

Alex: An existing issue or pull request is already connected to a repository. You can add one to a project from the Add item control, by searching for it, pasting its URL, or using project controls from the issue or pull request itself. A draft issue is lighter weight: it lets you capture work before you know which repository it belongs in or before it is ready to become a real issue.

Jamie: And when the draft becomes real work, you can promote it to an issue in a repository.

Alex: Yes, and for bigger cleanups you can bulk edit items. Select multiple rows or cards, then change a field like Status, Assignee, Iteration, or Priority for all selected items at once.

Jamie: This is also where cross-repository projects come in. One project can track work from more than one repository, especially at the organization level.

Alex: Right. You can connect repositories to a project and use the Repository field to see where each item lives. That field becomes powerful when you filter or group by repo, because one team can track accessibility bugs in a web app, documentation tasks in a docs repo, and release work somewhere else without splitting the plan into separate boards.

Jamie: Manual tracking is useful, but nobody wants to update every field by hand forever. What automation is built in?

Alex: Projects include workflows you can configure from the project settings or workflows area. Common ones include automatically adding matching issues or pull requests, changing Status when an item is added, moving closed issues to Done, updating pull requests when they are merged, and archiving completed items after a period of time.

Jamie: Auto-add sounds especially helpful. Could I say, add every new issue with the accessibility label from this repository into the project?

Alex: Yes. Auto-add rules can watch repositories and match criteria such as labels or other issue properties, depending on the rule options available to your account and project. And for more advanced cases, GitHub Actions can interact with Projects too, often by using GitHub's API or command-line tooling to add items, update fields, or report project state as part of a workflow.

Jamie: Where do iterations fit in? Are they just another name for milestones?

Alex: They are different. A milestone usually represents a release or deadline, while an iteration field represents a repeating cycle, such as a one-week or two-week sprint. You create an Iteration field, set a start date and duration, optionally add breaks, and then assign items to the current or upcoming cycle. Over time, iteration views can help a team notice capacity, spillover, and what actually got finished.

Alex: Views let you save different ways of looking at the same project. One view might be a table of everything, another might be a board grouped by Status, and another might be a roadmap filtered to a release.

Jamie: So a view is not a copy of the work. It is a saved lens on the work.

Alex: Exactly. You can create a new view, choose the layout, apply a filter, group items, sort them, and save it. Filter syntax can include terms like status:In Progress, assignee:octocat, label:accessibility, repo:org/name, is:open, or milestone:v1, plus custom field values such as priority:P0 if your project has that field.

Jamie: Grouping and sorting are the pieces that make the same project useful to different people. A maintainer might group by repository, a project lead might group by iteration, and a contributor might sort by due date or priority.

Alex: Exactly. The trick is to make views serve a question: what is blocked, what is due soon, what is assigned to me, what belongs to this repo, or what is in the current sprint.

Jamie: Let's talk about navigation, because a project can feel busy fast.

Alex: On the project home page, you are usually moving through a list of projects. Inside a project, listen for the view tabs, the filter bar, the main layout, and the right-side detail panel. In Table view, row and column movement gives the most complete text access. In Board view, Tab moves through columns and cards, and Enter opens a card. In the detail panel, fields such as Status, Assignee, Labels, Date, Repository, and custom fields can be reviewed and changed.

Jamie: And the filter bar is worth learning because it can shrink a huge project down to the few items you need.

Alex: Yes. If you lose your place, a good recovery pattern is to return to the view tabs, confirm the active view, check the filter bar, then move into the table, board, or detail panel again.

Jamie: The appendix also mentions an Accessibility Agents command, /project-status. How should learners understand that?

Alex: The Accessibility Agents collection is a living catalog, so available helpers can grow over time. The /project-status helper is meant to summarize project health: what is open, what is in progress, what may be blocked, what is overdue, and where attention is needed. You would use it before a standup, before a review, or when you need a plain-language snapshot instead of manually scanning every row.

Jamie: The practice work in this appendix is practical rather than theoretical.

Alex: Yes. One exercise is to create a personal tracking project, add a few real or draft items, and try Table, Board, and Roadmap views. Another is to set up automation, such as auto-adding matching issues or moving completed work. A third is to create a sprint view with an Iteration field. The advanced exercise is to build a cross-repository project and use the Repository field to filter or group the work.

Jamie: I like that progression. First you make a project, then you make it easier to maintain, then you make views for planning, and finally you coordinate across repositories.

Alex: Exactly. And if you want to verify behavior beyond this walkthrough, use GitHub's official documentation for Projects, labels, milestones, and the API. Projects change over time, so the strongest habit is learning where the controls live and how to confirm what a view is actually showing.

Transcript

Alex: Welcome back. Today we're talking about GitHub advanced search, which sounds like a power-user feature, but it is really a way to stop wandering around the site when you already know what you want.

Jamie: I love that framing, because search is where I go when I can't remember which repo, issue, pull request, or file I saw something in.

Alex: Exactly. GitHub search can reach across repositories, code, issues, pull requests, commits, users, organizations, and topics. The trick is learning the small query language that narrows the results before you ever press Enter.

Jamie: So instead of opening menus and checking boxes, I can type a more precise sentence into the search field.

Alex: Yes. And if you use a screen reader or high zoom, that can be a big relief. A typed query often gives you a clean results page faster than moving through filter dropdowns, sidebars, and checkbox menus.

Jamie: Where do you start from on GitHub?

Alex: On most GitHub pages, press slash to focus the global search bar at the top. Type your query, press Enter, and GitHub opens a results page grouped by type, such as Code, Issues, Pull requests, Repositories, and Users.

Jamie: Global search is the one at the top of the page. But GitHub also has search boxes inside repositories, right?

Alex: Right. The global search bar starts broad, across all of GitHub unless your query narrows it. Inside a repository, the Issues tab and Pull requests tab have their own search fields, and those are already scoped to that repository.

Jamie: So if I'm in a repo's Issues tab, I don't need to type the repo name unless I want to be extra explicit.

Alex: Exactly. But when you're starting from the top search bar, you can scope the search yourself with qualifiers like repo:owner/name, org:orgname, or user:username. A qualifier is a key and a value separated by a colon.

Jamie: Give me a concrete one.

Alex: repo:community-access/accessibility-agents in:title keyboard searches that repository for results with keyboard in the title. The in:title part says, do not search every body and comment; focus on the title field.

Jamie: That would reduce a lot of noise. What about in:body and in:comments?

Alex: Those work the same way. Use in:body when the important detail is likely in the description, and in:comments when you're looking for discussion after the issue or pull request was opened.

Jamie: And if I do lose the search bar visually at high zoom, slash brings me back there.

Alex: Yes. After results load, screen reader users can jump by headings to move between result groups. Low vision users can also use browser zoom to make GitHub's bold matched terms easier to find, and the Advanced Search page at github.com/search/advanced is a good bookmark if you want labeled form fields instead of compact syntax.

Alex: The query language itself starts simple. If you type two words, GitHub treats that as both words. So keyboard navigation means results should match keyboard and navigation.

Jamie: And if I want either word?

Alex: Use OR in capital letters, like keyboard OR focus. For an exact phrase, put it in straight quote marks, like "skip link". To exclude a word, put a minus sign in front, like -deprecated.

Jamie: I have definitely needed that last one. Sometimes one noisy term takes over the whole search.

Alex: You can also exclude a qualifier. For example, -label:bug means results should not have the bug label. That same key:value pattern is the heart of GitHub search.

Jamie: Let's unpack the issue and pull request qualifiers people see all the time.

Alex: is:open means open items only, and is:closed means closed items only. is:issue limits results to issues, and is:pr limits results to pull requests. For pull requests, is:merged finds merged PRs, and is:unmerged finds PRs that were not merged.

Jamie: And labels?

Alex: label:accessibility finds items with that label. If the label has spaces, quote it, like label:"good first issue". no:label finds items with no labels, no:assignee finds items assigned to nobody, and no:milestone finds items not attached to a milestone.

Jamie: What about the human side, like who made it or who owns it now?

Alex: author:@me finds items you created. assignee:@me finds items assigned to you. mentions:username finds places where that user was mentioned, and involves:@me is broader: it can include things you created, were assigned to, were mentioned in, or commented on.

Jamie: Dates use the same style?

Alex: Yes. created:>2025-01-01 means created after that date. updated:<2026-01-01 means updated before that date. A range looks like created:2025-01-01..2025-03-31.

Jamie: Let's use this for issues and pull requests, because that is where a lot of contribution work starts.

Alex: A good direct place is github.com/issues for issues involving you, and github.com/pulls for pull requests involving you. Those pages are already focused on repositories you have access to, so the result list can feel more manageable than a full global search.

Jamie: What would I type if I wanted open accessibility issues in an organization, but only ones nobody has claimed yet?

Alex: org:community-access is:issue is:open label:accessibility no:assignee. That says: search this organization, only issues, only open ones, with the accessibility label, and no current assignee.

Jamie: That is much more precise than searching the word accessibility and hoping.

Alex: For beginner-friendly work across GitHub, try is:issue is:open label:"good first issue" no:assignee. If you want a language filter, add language:python or language:javascript.

Jamie: Does language always make sense for issues?

Alex: It depends. GitHub can use repository language signals, so it is useful when you want issues from projects mostly written in a language. It does not mean the issue text itself is written in Python or JavaScript.

Jamie: What about pull request review?

Alex: A daily review query is is:pr is:open review-requested:@me. If you need pull requests where someone mentioned you, use is:pr is:open mentions:@me. To find your own open issues, use is:issue is:open author:@me.

Jamie: And stale work?

Alex: Use a date qualifier. For example, is:issue is:open repo:owner/name updated:<2024-08-01 finds open issues in one repository that have not been updated since before that date.

Jamie: Pull requests have a few special qualifiers too, don't they?

Alex: They do. review:approved can find PRs with an approving review. draft:true finds draft pull requests, while is:draft is another common way to express that. head:branch-name searches by the source branch of a PR, and base:main searches by the target branch.

Jamie: So base:main is useful when I only care about PRs trying to merge into main.

Alex: Exactly. And once the results are right, sorting helps. sort:created-asc puts the oldest created results first, while sort:updated-desc puts the most recently updated results first.

Alex: Code search feels related, but it has its own behavior. GitHub's modern code search is built for files, symbols, paths, and exact strings, not just issue text.

Jamie: So if I want to find aria-label in JavaScript files inside one repo?

Alex: Use repo:owner/name language:javascript aria-label. That combines a repository scope, a language filter, and the text you want to find.

Jamie: What if I know the function name?

Alex: Try symbol:handleKeyDown with a repo scope, like repo:owner/name symbol:handleKeyDown. Symbol search is meant for named code things such as functions or classes, where GitHub can recognize them.

Jamie: And across an organization?

Alex: org:community-access aria-hidden="true" searches across repositories in that organization for that exact pattern. You can tighten it with path:src/ to search only files under a path, extension:md to search Markdown files, filename:config.yml for a specific file name, or content:"exact string" for an exact string in file content.

Jamie: I like path:src/ because it lets me ignore docs or generated files when they are not relevant.

Alex: Exactly. And org: and repo: are useful here too. repo:owner/name means one repository, while org:orgname means all repositories in that organization.

Jamie: Commits are searchable too, but I always forget that.

Alex: They are. A query like repo:owner/name fix keyboard navigation can find commits with those words in the message. repo:owner/name author:username finds commits by a specific author, committer-date:2025-01-01..2025-03-31 narrows by date range, and path:docs/README.md finds commits touching a specific file.

Jamie: Search is not only for work items and files. It can also help you discover projects.

Alex: Yes. Repository search is great for finding communities and examples. topic:accessibility stars:>50 is:public finds public repositories tagged with the accessibility topic and more than 50 stars.

Jamie: And if I want TypeScript projects related to screen readers?

Alex: language:typescript topic:screen-reader sort:stars-desc. That filters by language and topic, then sorts with the most-starred repositories first.

Jamie: What other repository qualifiers are useful?

Alex: stars:>100, forks:>10, archived:false, and pushed:>2025-01-01 are common ones. You can use them to avoid abandoned projects, or to find active projects with a certain amount of community activity.

Jamie: Can I search for people and organizations the same way?

Alex: Yes. User and organization search supports qualifiers like type:user, type:org, location:, and fullname:. You might search accessibility type:user, or accessibility type:org, then use the result type filters to narrow what GitHub shows.

Alex: In this workshop, search becomes especially useful when you're looking for contribution opportunities or checking whether a report already exists.

Jamie: So before I file a new issue, I can search for the problem first.

Alex: Exactly. In a repository, use terms from the problem plus is:issue. If the issue is about keyboard focus, a query like repo:owner/name is:issue keyboard focus in:title can quickly show whether someone already filed something similar.

Jamie: And for the Accessibility Agents work, we should treat that collection as a living catalog, not a fixed set.

Alex: Right. Challenge 15 is browse-first, so search can help you discover what is already there without requiring a fork. A query like repo:community-access/accessibility-agents is:issue is:open label:accessibility can help you find current discussion or possible work, depending on the repository's labels.

Jamie: Then Challenge 16, the Capstone Project, is broader than one repo.

Alex: Yes. A meaningful capstone contribution might be to Accessibility Agents, GLOW, or another repository where the work matters. Review-ready drafts and contribution plans can count as completion evidence, so search can help you gather proof, locate related issues, and avoid duplicating work.

Jamie: What about proof after the fact?

Alex: Use is:pr is:merged author:@me to find your merged pull requests. Add org:community-access or repo:owner/name if you need proof from a specific place. For recent discussion about a topic, combine the topic words with updated:>2025-01-01 and maybe in:comments.

Jamie: I know I can bookmark a results page, but is there a better habit than leaving a pile of random bookmarks?

Alex: Build a small personal search library. Save the searches you actually reuse: review requests, your open issues, beginner-friendly issues, stale issues in a repo you maintain, and proof of merged work.

Jamie: Because the query is stored in the URL after I run the search.

Alex: Exactly. You can bookmark that URL, keep it in a notes file, or make a Markdown table with the name of the search, the query, and when you use it. That turns search from a one-time trick into part of your workflow.

Jamie: And if I live in the terminal?

Alex: The GitHub CLI has gh search commands. For example, gh search issues "is:open label:accessibility no:assignee" can bring issue search into your command line, and gh search prs "is:open review-requested:@me" can help you check review requests without opening the browser first.

Jamie: So the same mental model carries over: words, qualifiers, scopes, dates, and sorting.

Alex: That's the key. Start broad only when you need to explore. When you know the repository, organization, state, label, author, date, or file path, put that knowledge into the query.

Jamie: And the payoff is not just faster search. It is fewer wrong turns, fewer duplicate issues, and a cleaner path to the contribution you were trying to make.

Alex: Well said. Advanced search is one of those skills that makes GitHub feel smaller, calmer, and much more navigable.

Transcript

Alex: Welcome back. Today we're talking about GitHub notifications, which are the little signals GitHub sends when something might need your attention.

Jamie: And I am glad we are doing this, because notifications can feel like a second inbox that nobody warned you about.

Alex: Exactly. GitHub can notify you because you participated in a thread, because someone mentioned you, because you were assigned, because someone requested your review, or because something happened on a repository you chose to watch.

Jamie: So participating and watching are not the same thing.

Alex: Right. Participating means GitHub sees you as directly involved. You commented, opened the issue or pull request, got assigned, were requested as a reviewer, or someone typed your username with an at sign. Watching is a repo-level choice that can add more notifications, sometimes a lot more.

Jamie: That explains why one repository can be quiet and another can suddenly flood you.

Alex: Yes. Common notification reasons include a mention, a review request, an assignment, activity on a subscribed thread, a failed CI check on your pull request, or a release from a repo you watch for all activity. CI means continuous integration, the automated checks that run tests or validation after code changes.

Jamie: For the workshop, what are learners actually expected to do with this?

Alex: Chapter 10 is guided practice, not an autograded automation task. Notification settings belong to your GitHub account, so the Learning Room bot cannot reliably grade them. The pattern is configure, filter, and act, then leave evidence in your assigned Chapter 10 challenge issue.

Jamie: And this uses the GitHub website, not email, right?

Alex: Right. The practice happens at github.com/notifications, or by using the bell icon in the GitHub header. You do not need email delivery to complete it, because email depends on mail settings, spam filters, and other things outside the workshop. The web inbox is consistent, and the habits transfer later if you choose to use email or mobile notifications.

Jamie: This also connects back to Challenge 09, the Day 1 stretch, because final pull request readiness depends on seeing review signals and knowing when a PR is ready to merge.

Alex: Yes. Challenge 09 is where you pay attention to review requests, status checks, merging, and verifying that a linked issue closes. Chapter 10 gives you the inbox skills behind that work, and Bonus Challenge D goes deeper into notification hygiene, mentions, subscriptions, and avoiding overload.

Alex: Start in your Learning Room repository on GitHub.com. That repo is provisioned for your Day 1 practice, including issues, branches, commits, pull requests, and merges. Near the top right of the repository page, in the same general area as Star and Fork, find the Watch control.

Jamie: What should screen reader users listen for there?

Alex: With NVDA or JAWS, you can move by buttons until you hear Watch, Unwatch, or something similar. Press Enter to open the dropdown, move through the choices with the arrow keys, and press Enter on the level you want. With VoiceOver on macOS, use Quick Nav or VO navigation to find the Watch button, use VO+Space to open it, move through the choices, and use VO+Space to choose.

Jamie: And the recommended choice for most workshop repos is Participating and @mentions.

Alex: Yes. That keeps you informed when you are involved, without subscribing to every comment on every issue. Other levels matter too: All activity means every issue, PR, and comment; Ignore means no notifications from that repository; Custom lets you pick certain types, like issues, pull requests, or releases. You may also hear not watching in GitHub language, which usually means you are not asking for broad repo updates, though direct participation can still reach you.

Jamie: Where does starring fit? I have definitely confused Star and Watch before.

Alex: A star is a bookmark or a public signal that you like or want to find a repository later. Watching changes notifications. A common mistake is starring a repo you like, then also choosing too many watch updates by accident. If that happens, go back to the Watch dropdown and choose Participating and @mentions, Custom, or Ignore, depending on how quiet you need it to be.

Jamie: Once the watch level is set, the action moves to the inbox.

Alex: Yes. Go to github.com/notifications, use the bell icon, or, if GitHub keyboard shortcuts are active for your account, press G then N. The page usually has navigation and filters around the list, with tabs or controls for unread, done, and saved notifications.

Jamie: What does each notification sound like when you move through the list?

Alex: The list is made of links and controls. A notification normally announces the title, the repository, and the reason, such as mention, review requested, assignment, or status. Open one by activating its title link, read enough to understand why it appeared, then return to the inbox.

Jamie: And then there are actions: read, done, saved, and mute.

Alex: Right. Marking read or unread changes whether it appears as new. Marking done removes it from the active inbox, but future activity can bring it back. Saving keeps something available for later. Muting or unsubscribing from a thread stops future updates unless something directly pulls you back in, such as a new mention, depending on GitHub's current rules.

Alex: Filtering is where the inbox becomes useful instead of noisy. In the Chapter 10 walkthrough, activate the Review requested filter first, then clear it and activate Assigned.

Jamie: Review requested is probably the one people will use constantly in real projects.

Alex: Absolutely. It shows pull requests where someone wants your review. Assigned shows issues or PRs assigned to you. You can also filter by repository or organization, which is helpful when your personal work, class work, and open source work all share the same inbox.

Jamie: What about a pull request where the notification is really about a failing check?

Alex: Open the notification, go to the pull request, and look for the checks or status area. If a CI check failed, you are not just reading a message; you are deciding whether the failure needs your action before merge. That is especially important during final PR readiness work in Challenge 09.

Jamie: Let's talk about mentions, because typing someone's username feels simple, but it can also be a little loaded.

Alex: A mention is written as @ followed by a GitHub username, like @alex-example. It is a direct attention signal, so use it when you need that person to see the comment. A team mention looks like @org/team-name, and it notifies members of that team according to their organization settings and permissions.

Jamie: So a mention is not decoration. It is more like saying, please look at this.

Alex: Exactly. Good mentions include context, such as what you need reviewed, what decision is blocked, or what question you are asking. If you receive a mention you did not expect, first check whether it needs action. If it was accidental or no longer relevant, it is fine to reply briefly, mark it done, or unsubscribe from the thread.

Alex: When your inbox grows, do not try to treat every notification the same way. First handle the things that directly name you: mentions, assignments, and review requests. Then scan repo or organization filters for anything you chose to follow.

Jamie: I get nervous about mark all as done. It sounds like deleting everything.

Alex: It is not deletion. Done means the notification leaves the active inbox, but the issue or PR still exists, and future activity can notify you again if you are still subscribed. Still, use mark all as done only after a quick scan, and save anything you truly need to revisit.

Jamie: Where do account settings come in?

Alex: In GitHub Settings, you can configure notification preferences for web, email, and other delivery choices. Email can be useful, but it is optional for this challenge. The web inbox is the shared baseline, and the GitHub mobile app is a useful reference if you want notifications on your phone later.

Jamie: So mobile is allowed as a personal workflow, but it is not the thing being tested here.

Alex: Correct. And if your screen reader intercepts a shortcut like E, I, M, or Shift+M, focus the notification row or use the visible action menu instead. NVDA, JAWS, and VoiceOver each have their own browsing modes, so the reliable path is: find the notification, confirm the title and reason, then choose the action intentionally.

Jamie: What if someone wants a command-line style workflow too?

Alex: The gh CLI can help with notification-like checks, even though the browser inbox is still the focus here. You can list pull requests requesting your review, view issues assigned to you, check the status of a pull request, and open the notification page in your browser with gh browse. For example, gh pr list with a review-requested search, gh issue list assigned to you, and gh pr checks can help you find work without hunting through pages.

Jamie: And VS Code?

Alex: With the GitHub Pull Requests extension, VS Code can show items needing attention and open related issues or pull requests. GitHub Desktop is different; it is great for commits, branches, and syncing, but it does not manage the notification inbox. For notification triage, use the browser, the GitHub mobile app if you choose, or CLI-supported checks.

Alex: To complete the Chapter 10 practice, change the watch level on your Learning Room repository, test the Review requested and Assigned filters, and perform one inbox action on a non-critical thread. That action can be mute, unsubscribe, mark done, mark read or unread, or save, depending on what is available and appropriate.

Jamie: Then the evidence is a comment on the assigned challenge issue.

Alex: Yes. Post a short completion comment that says Chapter 10 completed, the watch level you set, the filters you tested, and the inbox action you performed with a brief thread description. Then close your Chapter 10 challenge issue.

Jamie: And if the inbox is empty or the filters show nothing?

Alex: That is okay. Check the Done tab for older notifications, clear active filters before trying a new one, and ask a facilitator to model an inbox action if you need to hear the workflow once. If you are unsure how this connects to merge readiness, compare your final PR checks with the Challenge 9 reference solution.

Jamie: The confidence check is pretty practical: can you reduce noise, find review requests, find assigned work, and choose what to do with a notification?

Alex: Exactly. If this was your first time, you have already learned a professional maintenance habit: set sane watch levels, filter for signal, act on each item, and keep a daily rhythm that does not depend on panic. Between days, keep the Learning Room inbox manageable, and when Day 2 adds broader collaboration, you will have a calmer way to notice what needs you.

Transcript

Alex: Welcome back. Challenge 09 is Merge Day, and it is exactly what it sounds like: your Day 1 pull request becomes part of the main branch.

Jamie: This is the moment where the work stops being a practice change on a side branch and becomes the shared version of the repository.

Alex: Yes. In your private Learning Room repository, you have already filed an issue, made a branch, committed a change, and opened a pull request. Now you are checking that the pull request is ready, merging it, and confirming the linked issue closed the way you expected.

Jamie: I like that this is not just click the big green button and hope. There is a final check before the celebration.

Alex: Exactly. Merging is a real collaboration signal. It says the change was reviewed enough, the checks are acceptable, and the repository is ready to include your work on main.

Jamie: Before we touch the merge button, what should be true about the pull request?

Alex: Start with the basic readiness signals. Your PR should not have conflict markers like less-than signs, equals signs, and greater-than signs from a merge conflict. If GitHub says the branch has conflicts, pause and go back to the conflict workflow before merging.

Jamie: And the pull request description still matters here, right? Even this late?

Alex: Very much. The description should say what changed, why it changed, and which issue it closes. The key line is `Closes #XX`, with the number of the issue you filed earlier, because that text is what lets GitHub close the issue automatically when the PR merges.

Jamie: So if I wrote a vague description in Challenge 6, Merge Day is a good time to clean it up.

Alex: Yes. A strong PR usually has a short summary, a list of changes made, related issues, testing notes, and sometimes screenshots or recordings if the change is visual. For today's Learning Room work, it may be simple, but the habit scales to larger projects.

Jamie: Let's say I have my repo open and I am trying to find the PR. What is the path?

Alex: Open the Pull requests tab in your Learning Room repository, then open the PR you created in Challenge 6 or the later PR you are using for Day 1. If GitHub keyboard shortcuts are enabled, the repository shortcut G then P can move you toward the pull request list. You can also arrive from a notification, from the bell inbox, from GitHub Desktop opening the PR in the browser, or from the GitHub CLI with a command like `gh pr view --web`.

Jamie: Once I am on the PR page, I sometimes feel like there are too many tabs and regions. Where do I read first?

Alex: Begin on the Conversation tab. That is where you find the description, the review discussion, bot comments, status checks, and the merge area. With a screen reader, headings and landmarks are your friends here; in NVDA, browse mode is usually best for reading, and focus mode is for typing in fields.

Jamie: Then the other tabs are for confirming the details?

Alex: Right. Commits shows the commit history. Checks gives more detail about automated tests and validation. Files changed shows the diff, where added lines are marked with plus, removed lines with minus, and unchanged lines give context. If there are review comments, unresolved conversations, or suggested changes, read those before merging.

Jamie: What review signals should make me stop instead of merge?

Alex: If the PR is still a draft, do not treat it as ready until it is marked ready for review. If a reviewer requested changes, read the comments and respond with another commit or a reply. If required checks are failing, open the Checks tab or the bot comment and fix the issue first.

Jamie: And if the checks are green, the description links the issue, and the diff looks right, then we are looking for the merge button.

Alex: Yes. Near the merge area, GitHub should offer a green Merge pull request button when the PR can be merged. Some repositories use branch protection, which can require a review, passing checks, or facilitator approval before that button becomes active.

Jamie: What about merge options? Sometimes I hear merge commit, squash, and rebase, and I freeze.

Alex: For this challenge, use the default option your repository presents unless your facilitator tells you otherwise. A merge commit preserves the branch history as a merge. Squash and merge combines the branch's commits into one commit. Rebase and merge replays the commits onto main. Those are maintainer choices; today, your main responsibility is to avoid merging before the PR is ready.

Jamie: All right. Walk me through the actual merge, slowly.

Alex: Open the PR, move to the merge area, and activate the green Merge pull request button. GitHub may ask you to confirm, so activate Confirm merge. After that, the page should report that the pull request was successfully merged, and the PR status changes to merged, often with a purple merged icon.

Jamie: And if there is a dropdown asking how to merge?

Alex: Choose the normal merge option unless your facilitator has given a different instruction. In some repositories you may also see auto-merge, which waits and merges later after required checks pass. That can be useful in professional work, but for Challenge 09, most learners are doing a direct merge when everything is already ready.

Jamie: Should I delete the branch afterward?

Alex: If GitHub offers Delete branch after the merge, it is usually safe for this short Learning Room branch. The work is already on main, and deleting the branch removes clutter. If you are unsure, ask before deleting, but for a completed feature branch this is a normal cleanup step.

Jamie: The PR says merged. How do I prove the change actually landed on main?

Alex: Go back to the Code tab of the repository. Check the branch dropdown and make sure it says `main`, not your feature branch. Then open the file you changed, often `docs/welcome.md` in this challenge path, and confirm your new welcome text is there instead of the TODO.

Jamie: That part seems important because the PR page alone tells me the PR merged, but the Code tab shows what everyone gets on main.

Alex: Exactly. The second verification is the linked issue. Open the Issues tab, find the issue from Challenge 2, and confirm it is closed. If the PR description used `Closes #XX` with the correct number, GitHub should close it automatically when the PR merges.

Jamie: What if the issue did not close?

Alex: First, check whether the PR description had the correct issue number before the merge. If you have not merged yet, edit the description and include the correct `Closes #XX` line. If the PR is already merged, ask your facilitator whether to close the issue manually with a comment linking back to the merged PR.

Jamie: The challenge asks for evidence. What should a good completion comment include?

Alex: Keep it concrete. Include a link to the merged PR, a link to the issue that closed, and one thing you are proud of from Day 1. For example, you might say that PR number 5 fixed the TODO in `welcome.md`, linked to issue number 3, and taught you how issues and pull requests connect.

Jamie: I like the proud-of line. It makes the evidence more than a receipt.

Alex: It does. You can also mention what surprised you, such as how much of open source is communication: issue descriptions, PR summaries, comments, review replies, and clear commit messages. The alternate ways to recap are also fine: a comment on the challenge issue, a short summary in the workshop discussion channel, or a brief reflection file if your facilitator wants that.

Jamie: But the core proof is still the loop: issue, branch, commit, PR, merge.

Alex: Yes. If you merged at least one PR and can explain what you learned, you completed the Day 1 workflow. The evidence is there to help you and your facilitator see the full path, not to make the celebration harder.

Jamie: There is also a wrap-up piece involving peers and notifications. How does that fit Merge Day?

Alex: After merging, leave a wrap-up comment on the peer-simulation issue or PR. If you have real buddy access in your cohort, congratulate your buddy on completing Day 1. That reinforces the social part of GitHub: people need acknowledgment, not just code review.

Jamie: And notifications are how those social signals find us.

Alex: Right. This course uses GitHub's web notification inbox at `github.com/notifications`, not email, because the web inbox is available to everyone and works consistently. A practical repository watch level is Participating and @mentions, which notifies you when you are involved without flooding you with every event.

Jamie: So Star and Watch are not the same thing.

Alex: Correct. Starring is more like bookmarking or showing interest. Watching controls notifications. If a repository gets noisy, check whether you accidentally subscribed to All activity, and move it back to Participating and @mentions or another level that fits your role.

Jamie: What should learners practice in the inbox before they call Day 1 done?

Alex: Open the notification inbox from the bell icon or by visiting `github.com/notifications`. Try the Review requested filter to find PRs where someone asked for your review, then clear it and try Assigned to find issues or PRs assigned to you. Open one notification, read its title, repository, and reason, then return to the inbox.

Jamie: And then take one action, right?

Alex: Yes. On a non-critical thread, mark it done if you are finished with it, or mute it if you do not want future updates from that thread. Keyboard shortcuts can help, such as E for done and Shift+M for mute, but if your screen reader captures a key, move focus to the notification row first or use the visible controls.

Jamie: What if the inbox is empty?

Alex: That is not a failure. You can check the Done tab, practice reading the layout, or ask a facilitator to model a notification action. The goal is to understand how to filter and act so review requests, mentions, assignments, and failed checks do not get buried later.

Jamie: Let's talk blockers. What are the common Merge Day problems?

Alex: If your PR still has conflicts, do not force anything. Return to the conflict challenge and resolve the conflicting lines first. If the merge button is disabled, look for the reason near the merge area: it may need a passing check, a review approval, or facilitator action because of branch protection.

Jamie: What if I am just not sure whether the file change is the right one?

Alex: Open Files changed and read the diff again. Use the file tree if it is available, then move through the changed file. Added lines should reflect the content you intended, and the change should stay focused on the assigned issue. If you need a second set of ears, ask someone to review the PR rather than guessing.

Jamie: And if I am using the terminal?

Alex: The same ideas apply. Check your branch with `git branch --show-current`, keep the change small, confirm the `Closes #number` text, and use GitHub CLI commands such as `gh pr checks`, `gh pr view`, and `gh pr list` to inspect status. Use documented help with `gh pr --help` when you are unsure of an option.

Jamie: This is a good moment to name what learners have actually done today, because it is a lot.

Alex: It really is. You navigated a real GitHub repository, filed an issue with structured information, used comments and @mentions, created a safe branch, made a meaningful commit, opened a linked pull request, and brought that work onto main.

Jamie: And somewhere in there, many people also met a merge conflict and lived to tell the story.

Alex: Yes, and that matters. Merge conflicts are normal when people edit the same area of a project. They are not a sign that you broke GitHub; they are a collaboration problem with a fixable shape.

Jamie: So when the PR is merged, the issue is closed, the evidence is posted, and the peer comment is done, Day 1 is complete.

Alex: Exactly. Take the celebration seriously. You completed the professional GitHub contribution path in your Learning Room repository, and you now have a mental map for how issues, branches, commits, pull requests, reviews, merges, and notifications fit together.

Transcript

Alex: Welcome back. Bonus D is all about Notifications, and you may also see the issue describe it as Notification Mastery.

Jamie: I like this topic because notifications sound small until they take over your day.

Alex: Exactly. GitHub notifications are how GitHub tells you that something may need your attention: a mention, a review request, an assignment, a reply, or a failed check. The goal is to stay reachable without letting every repository become an interruption machine.

Jamie: So this is not about getting to inbox zero for the sake of it. It is about knowing which signals deserve attention and which ones can wait.

Alex: This bonus is web-first. The main place to practice is the GitHub notification inbox at github.com/notifications, not your email app. Email can be useful, but it depends on spam filters, mail servers, personal settings, and other things the workshop cannot control.

Jamie: That makes sense. If two learners have different email providers, they could do the same GitHub work and still have completely different email results.

Alex: Right. The reliable workflow is to use the notification bell or go straight to github.com/notifications. Bonus D unlocks after Challenge 15, along with Challenge 16 and Bonus Challenges A through E. And the Day 1 practice that this builds on happens in your own Learning Room repository, where you created an issue, branch, commit, pull request, and merge.

Jamie: And Chapter 10 itself is guided practice, not an autograded bot check, correct?

Alex: Correct. Notification settings live at the account level, so the Learning Room PR bot cannot safely validate them. The original Chapter 10 walkthrough is short, about five to eight minutes, and the evidence is a structured comment on your assigned challenge issue.

Jamie: Before we touch settings, what actually causes a GitHub notification?

Alex: Several things. Someone can type @your-username in an issue, pull request, or discussion. You can be requested as a reviewer on a pull request, assigned to an issue or pull request, or subscribed to a thread because you commented on it. You can also get notified when a continuous integration check fails on your pull request, or when a release is published in a repository you are watching for that kind of activity.

Jamie: That explains why review requests are such a common notification. They are not just chatter; they are a specific request for your attention.

Alex: Yes, and unexpected mentions deserve a calm check too. Sometimes someone tags you by mistake, and sometimes they really do need your input. Open the thread, decide whether to respond, mute it, or leave it in your workflow, and do not assume every mention is equally urgent.

Jamie: The Watch button is where a lot of notification overload starts, right?

Alex: It is. Each repository has a subscription level. Participating and @mentions means you hear about threads where you commented, were assigned, were requested, or were mentioned. All Activity means every issue, comment, and pull request can come to you. Ignore means no notifications from that repo, and Custom lets you choose categories like issues, pull requests, or releases.

Jamie: If I am in my Learning Room repository, how do I change that without relying on a mouse?

Alex: On the repository page, the Watch control is near Star and Fork. With NVDA or JAWS on Windows, use button navigation, often the B key, until you hear Watch or Unwatch, press Enter, move through the options with the arrow keys, and press Enter on the level you want. With VoiceOver on macOS, use Quick Nav to find the Watch button, open it with VO+Space, move through the choices, and select with VO+Space. The button label should update, which confirms the change.

Jamie: And starring is different from watching, which is an easy thing to mix up.

Alex: Very easy. Starring is more like bookmarking or showing interest in a repository. Watching changes what notifications you receive. A good workshop default is Participating and @mentions for most repositories, All Activity only for repositories you actively maintain or contribute to every day, Custom for repositories you read occasionally, and Unwatch for repositories you are finished with.

Jamie: Once the watch level is reasonable, the inbox itself becomes much less scary.

Alex: Yes. Open github.com/notifications, or use the notification bell in the GitHub header. If GitHub keyboard shortcuts are enabled for your account, G then N can also open notifications. The page is organized around tabs, filters, and a list of notification items.

Jamie: What should a screen reader user expect to hear in that list?

Alex: Each notification is a link or row that usually announces the title, the repository, and the reason, such as mention, review requested, or assignment. You can move through the list with your usual reading commands or link navigation, then press Enter to open one. For practice, use the Review requested filter to find pull requests asking for your review, clear that filter, then use Assigned to find issues or pull requests assigned to you. If you open a pull request notification, check the conversation and status area so you know whether review, tests, or another action is needed.

Jamie: What if the inbox is empty? That can feel like you did something wrong.

Alex: An empty inbox is fine. You may simply have no current notifications. You can switch to Done to look at older items, or ask a facilitator to model one notification action live. If filters show nothing, clear active filters first, then apply one filter at a time, including repository or organization filters when you need to narrow a busy inbox.

Jamie: Okay, so I have a notification in front of me. What are the main actions?

Alex: You can mark a notification as done, mark it read or unread, mute a thread, or open it and respond. In the browser inbox, E commonly marks an item done, I toggles read and unread, and GitHub's shortcut help may show mute as M or Shift+M depending on the current interface. If a screen reader captures the shortcut, move focus to the notification row or use the visible action menu instead.

Jamie: I always wonder about the difference between done and mute.

Alex: Done removes it from your inbox for now, but future activity can notify you again. Mute says you do not want future updates from that thread, so save it for noisy or no-longer-relevant conversations. For a large backlog, mark all as done can be useful after you have checked for review requests and assignments, but do not use it to hide work you actually need to do.

Jamie: That is the balance: reduce noise, but do not make yourself unreachable.

Alex: Exactly. A practical daily routine is to check filtered notifications once or twice a day, handle review requests and assignments first, then mute or finish the rest intentionally.

Jamie: Bonus D also sends learners to github.com/settings/notifications. What changes are worth considering there?

Alex: Start with the defaults and change one thing at a time. A common configured setup is email on and web on for Participating, because replies to your own conversations matter. For Watching, many people turn email off and keep web on, so watched repository activity waits in GitHub instead of interrupting their email. For GitHub Actions, successful runs usually do not need email, while failed runs can be worth sending because they may block a pull request.

Jamie: And if someone uses more than one email address?

Alex: They can use custom routing. For example, organization notifications for Community-Access can go to a workshop email, while personal project notifications go to a personal address. If they use the GitHub mobile app, they can also tune push notifications there, but mobile is a reference option, not required. VS Code can show notification-related items through the GitHub Pull Requests extension, GitHub Desktop does not manage notifications, and the browser inbox remains the shared workshop path.

Jamie: What does a good Bonus D evidence comment include?

Alex: It should describe your notification configuration and your strategy. Answer how you will know when someone requests your review, how you will avoid being overwhelmed by busy repositories, and how you plan to use the GitHub inbox: read everything, triage with filters, or check specific categories first. The checklist asks you to review email notifications, web notifications, repository watching, custom routing if you have multiple emails, and mobile push settings if you use the app. In Chapter 10, your completion comment can also say your watch level, the filters you tested, and whether you muted or marked a thread done, then you close the assigned challenge issue.

Jamie: So completion is not a perfect screenshot of every setting. It is proof that you made intentional choices and can explain them.

Alex: Yes. If you changed at least one default setting and can explain how that keeps you informed while reducing noise, you have met the heart of the bonus. If you cannot find settings, go to github.com, open your profile menu, choose Settings, then Notifications in the left sidebar. If there are too many options, start with review request email or web notifications, then adjust watching. For current details, use the official GitHub documentation and GitHub's changelog, because interface labels can change over time.

Jamie: This also wraps up a lot of Day 1 skills, doesn't it?

Alex: It does. By this point, you have practiced the flow of noticing work, opening the right GitHub page, taking an action, and leaving evidence. If it was your first time using these tools, the confidence check is simple: can you find work assigned to you, find review requests, change a watch level, and quiet a noisy thread?

Jamie: And Day 2 adds more collaboration where that matters: reviews, ongoing issues, and planning contributions without losing track of conversations.

Alex: Exactly. Notification hygiene is part of being a dependable contributor. You are not trying to hear everything. You are building a system that helps you hear what matters when it matters.

Transcript

Alex: Welcome back. Today we're setting up VS Code as an accessible place to do GitHub work, especially the kind of Markdown, review, and contribution work that shows up throughout this course.

Jamie: And VS Code can sound a little intimidating if you've only used GitHub in the browser. Is this a whole new world, or just another way into the same projects?

Alex: A bit of both. VS Code is a free, extensible code editor from Microsoft, and extensible means you can add features through extensions. GitHub.com is excellent for reading issues, reviewing pull requests, and having discussions, while VS Code is where editing, checking files, using Copilot, and moving through a repository can feel more direct.

Jamie: So the browser is still important. We're not replacing it.

Alex: Not at all. You're adding a stronger workspace for creating. VS Code gives you a file tree, a full text editor, a built-in terminal, source control tools, settings, keyboard shortcuts, extensions, and accessibility features that can announce problems while you're working.

Jamie: That last part is big. Finding an error after you push is stressful. Hearing about it while you're still editing is much better.

Alex: Exactly. This is Day 2 foundation work. The assumption is that you already completed the Day 1 walkthrough in GitHub's browser interface, including the Learning Room repository that was created for you.

Jamie: So today is less about making a big contribution and more about making sure the editor is usable, signed in, and ready.

Alex: Before installing anything, you can try VS Code right in your browser with github.dev. Open a repository on GitHub.com, then press the period key. After a few seconds, the repository opens in a VS Code-style editor in that same browser tab.

Jamie: That period key shortcut feels almost hidden. Where does it work?

Alex: Use it from a repository code page, such as the main page of your Learning Room repository or a folder or file view in the repository. It won't work from an issue page, a pull request conversation, or a random GitHub settings page.

Jamie: And if the period key doesn't do anything?

Alex: You can go directly by changing the address to github.dev and the same owner and repository path, or look for repository page options that open the web editor. The period key is just the fastest route when you're already in the right place.

Jamie: What do I get in github.dev once it opens?

Alex: You get the Explorer file tree, the editor, search, source control views, many keyboard commands, Markdown editing, and a familiar VS Code layout. It's great for quick edits, reading a project, and practicing navigation without installing desktop VS Code.

Jamie: But it's not exactly the same as desktop VS Code, right?

Alex: Right. github.dev doesn't have a full local terminal, it can't run every tool, and Copilot support may require desktop VS Code or a Codespace depending on what you're trying to use. Desktop VS Code is better when you need installed extensions, command-line tools, local files, or deeper Copilot workflows.

Jamie: So github.dev is perfect for quick orientation, and desktop VS Code is better when the project needs more power.

Alex: Yes. For this workshop, github.dev is a low-friction bridge. You can open the Learning Room repository, test the interface, enable accessibility support, and confirm the main surfaces before doing heavier work.

Jamie: The first thing I would want to do is make sure my screen reader and the editor are cooperating. How do I turn on screen reader mode?

Alex: On Windows with NVDA or JAWS, press Shift+Alt+F1. You should hear confirmation that screen reader accessibility mode is on. On Mac with VoiceOver, VS Code is often already optimized, but if navigation feels wrong, open the Command Palette with Cmd+Shift+P and run Toggle Screen Reader Accessibility Mode.

Jamie: What should change after it's on?

Alex: VS Code adjusts the editor so screen readers get better announcements, including cursor movement, line content, suggestions, errors, and navigation context. It may change how some editor features behave so text editing is more reliable with assistive technology.

Jamie: Are there screen reader-specific habits worth knowing?

Alex: Yes. NVDA and JAWS users may need focus mode or forms mode when editing text, and browse mode can get in the way inside the editor. VoiceOver users should pay attention to whether focus is moving through the editor, sidebar, and panels as expected, and use the screen reader mode toggle if things feel off.

Jamie: And VS Code has an accessibility help dialog too, right?

Alex: Yes. Press Control+Shift+H to open accessibility help. It tells you useful commands for the current context, including navigation help and ways to reach accessible views. If you forget a keyboard path, that help dialog is a good place to recover.

Jamie: I want the editor to be chatty enough to be useful, but not so chatty that I can't think.

Alex: That's where settings matter. In Settings, search for editor.accessibilitySupport and set it to on if automatic detection doesn't work well for you. Also search for screen reader announcements or accessibility verbosity settings so you can tune what VS Code speaks.

Jamie: Audio cues are part of that too?

Alex: Yes. Audio cues are short sounds that can signal things like errors, warnings, breakpoints, folded regions, or terminal command completion. They don't replace speech, but they can add quick confirmation without making you stop and inspect the screen.

Jamie: So the baseline is: turn on support, confirm announcements, and adjust speech and sounds until the editor gives useful feedback.

Alex: Once accessibility support is stable, the next skill is knowing the main areas of the VS Code window.

Jamie: Give me the landmarks.

Alex: There are five big areas to recognize: the Activity Bar, the sidebar, the editor, the panel area, and the Status Bar. The Activity Bar is the vertical strip of major tools, the sidebar changes based on the tool you picked, the editor is where files open, the panel is where things like Terminal and Problems can appear, and the Status Bar runs along the bottom.

Jamie: The Activity Bar is the place with Explorer, Search, Source Control, Run, and Extensions?

Alex: Exactly. Explorer shows the file tree. Search finds text across the project. Source Control shows Git changes. Extensions lets you install add-ons. Accounts is usually near the bottom, and it is where GitHub sign-in lives.

Jamie: And if I don't want to hunt through the interface?

Alex: Use the Command Palette. Control+Shift+P on Windows or Linux, Cmd+Shift+P on Mac. It's the most important VS Code shortcut because you can type the action you want, like Toggle Word Wrap, Preferences, or Accessible Diff Viewer, and run it from the keyboard.

Jamie: How do I move between the sidebar, editor, terminal, and panels without getting lost?

Alex: Use the keyboard commands for the surface you want, then listen for the announcement. Control+Shift+E opens Explorer, Control+Shift+F opens Search, Control+Shift+G opens Source Control, and Control+Shift+X opens Extensions. Control+` opens the integrated terminal in desktop VS Code, and Escape often returns focus out of temporary popups.

Jamie: What's the difference between opening a folder and opening a file?

Alex: Opening a file gives you one document. Opening a folder gives VS Code the project context: the file tree, search across files, Git status, extensions that activate for the project, and settings that belong to that workspace. For repository work, opening the folder is usually the better choice.

Jamie: And for a Markdown file, headings can become navigation points, yes?

Alex: Yes. Open README.md, then press Control+Shift+O, or Cmd+Shift+O on Mac, to open the outline or symbols view. For Markdown, it lists headings, which makes long files much easier to scan with a keyboard and screen reader.

Jamie: Where does GitHub sign-in happen inside VS Code?

Alex: The most direct place is the Accounts button near the bottom of the Activity Bar. Activate it, choose the GitHub sign-in option, and follow the browser prompt. You can also open the Command Palette and search for Accounts if the button is hard to find.

Jamie: How do I know sign-in worked?

Alex: Return to the Accounts control and listen for your GitHub username. VS Code may also show account-related items in the Status Bar or ask permission for GitHub features when you first use them.

Jamie: Status Bar is one of those places I forget about. What's usually in it?

Alex: From left to right, it can include Git branch information, sync state, problems counts, live share or account indicators, line and column, indentation, encoding, language mode, notifications, and sometimes Copilot status. You can tab or arrow through many Status Bar items, and your screen reader should announce what each one does.

Jamie: Copilot status is part of this setup check too.

Alex: Yes. In desktop VS Code, look for the Copilot indicator in the Status Bar, use the Command Palette to search for Copilot commands, or try a small suggestion in a scratch file. If you're in github.dev and Copilot doesn't appear, that may be expected; you may need desktop VS Code or a Codespace.

Jamie: And the Menu Bar is still there for people who prefer menus.

Alex: Right. The Menu Bar includes File, Edit, Selection, View, Go, Run, Terminal, and Help. On Windows and Linux, Alt usually moves focus to the Menu Bar. On Mac, the system menu is at the top of the screen, and VoiceOver users can navigate it with standard macOS commands.

Jamie: There are a lot of entry points, but the pattern is reassuring: use a direct shortcut when you know it, and use the Command Palette when you don't.

Alex: Settings are where you make VS Code feel less generic and more like your workspace.

Jamie: Which settings should accessibility learners check first?

Alex: Open Settings from the Command Palette or the menu, then search for accessibility. Check editor.accessibilitySupport, screen reader announcement or verbosity options, audio cues, font size, word wrap, cursor style, and line numbers if they affect how you navigate. The Settings editor also supports filters like modified settings and extension settings, which helps when you need to find what changed.

Jamie: What about carrying those settings to another computer?

Alex: That's Settings Sync. When you enable it, VS Code can sync settings, keyboard shortcuts, snippets, user tasks, extensions, and interface state across machines. If two machines disagree, VS Code may ask you to resolve a conflict instead of silently overwriting your setup.

Jamie: Profiles sound related, but not identical.

Alex: Exactly. A profile is a named set of settings, extensions, and UI state. You might create a workshop profile with the accessibility settings, extensions, and shortcuts you want for this course, then switch back to another profile for different work. Profiles can also be exported and shared, and they can work alongside Settings Sync.

Jamie: If shortcuts conflict with my screen reader, can I change them?

Alex: Yes. Open the Keyboard Shortcuts editor from the Command Palette, search for the command, activate the edit control, press the new key combination, and save it. If VS Code detects a conflict, review it before accepting the new shortcut.

Jamie: I know this chapter focuses on setup, but learners also hear about terminals, extensions, and diffs. Can we place those on the map?

Alex: Definitely. The integrated terminal is a command line inside VS Code, usually opened with Control+` on Windows or Linux, and from the Terminal menu as well. In github.dev, terminal support is limited, so use desktop VS Code or a Codespace when you need real commands.

Jamie: Extensions are add-ons, right?

Alex: Right. Open the Extensions view with Control+Shift+X, search for an extension, read its details, and install it if it fits your workflow. Extensions can add language support, GitHub tools, linters, themes, accessibility helpers, and project-specific features.

Jamie: What about reviewing changes accessibly?

Alex: VS Code includes an Accessible Diff Viewer. Open the Command Palette, search for Accessible Diff Viewer, and run it when you're reviewing file changes. It presents differences in a way that is easier to move through with speech than a purely visual side-by-side comparison.

Jamie: Where does Source Control fit?

Alex: The Source Control view shows changed files, lets you inspect diffs, stage changes, write commit messages, and work with Git. The full contribution workflow comes later, but recognizing the Source Control icon now makes later Git work less surprising.

Jamie: And Copilot Chat and agents are desktop-focused?

Alex: For serious use, yes. Desktop VS Code gives you the richer Copilot Chat experience, and later chapters use agent files and the living catalog of Accessibility Agents as part of contribution planning and review. For this setup chapter, you just need to know whether Copilot is available in your current environment.

Jamie: So we're not trying to master every tool today. We're making sure the doors open, the announcements make sense, and the important rooms are findable.

Alex: The practice for this chapter is a quick accessibility baseline. Plan about 10 to 15 minutes, and use either github.dev or desktop VS Code.

Jamie: Walk me through it like I'm doing it now.

Alex: Open your Learning Room repository on GitHub.com. Press the period key to launch github.dev, or open the same repository folder in desktop VS Code. Turn on screen reader mode, open Explorer with Control+Shift+E, open README.md, use Control+Shift+O for the outline, open the Command Palette with Control+Shift+P, check Accounts, and check Copilot status in the Status Bar if your environment supports it.

Jamie: And then the evidence goes back to GitHub.com, not inside VS Code?

Alex: Correct. Return to the assigned setup or Day 2 readiness issue and post a completion comment. Record whether you opened github.dev, enabled screen reader mode, signed in to GitHub, checked Copilot status, opened a file in Explorer, opened the outline or symbols view, and opened the Command Palette.

Jamie: What if one of those answers is no?

Alex: Say where you got stuck. If the period key did nothing, check that you were on a repository code page. If the Explorer is empty, wait a few seconds and open Explorer again. If screen reader mode didn't announce, use the Command Palette and search for Screen Reader.

Jamie: And if Accounts or Copilot are hard to find?

Alex: Use the Command Palette as your fallback. Search for Accounts to manage sign-in, and search for Copilot to see available commands. If Copilot doesn't show in github.dev, try desktop VS Code or a Codespace, or note that it was not available in your environment.

Jamie: This makes setup feel like contribution work, not busywork.

Alex: It is contribution work. A stable, accessible editor reduces friction and helps you make cleaner changes. When you can open the tool, sign in, confirm accessibility support, move through files, use the Command Palette, and report what worked, you're ready for the VS Code-based chapters that follow.

Transcript

Alex: Welcome back. Today we're going deeper into VS Code accessibility, the parts that make local work feel manageable instead of crowded.

Jamie: And this is especially important before Challenge 10: Go Local, right? Once you're making a local commit, VS Code becomes the place where you edit, check, search, run commands, and recover when something gets confusing.

Alex: Exactly. This chapter continues the VS Code setup work from the previous chapter, but it moves from basic orientation into power tools. We're talking keyboard navigation, the Problems panel, the terminal, Copilot Chat, Accessible Help, Accessible View, Accessible Diff, accessibility signals, speech features, and Markdown authoring.

Jamie: So not one magic setting. More like a set of reliable paths through a busy app.

Alex: Let's start with focus. In VS Code, you can jump to the major areas directly: Ctrl+Shift+E for Explorer, Ctrl+Shift+F for Search, Ctrl+Shift+G for Source Control, Ctrl+Shift+X for Extensions, Ctrl+` for the terminal, Ctrl+Alt+I for Copilot Chat, Ctrl+Shift+P for the Command Palette, Ctrl+1 for the editor, and Ctrl+Shift+M for Problems.

Jamie: Mac listeners should translate those as Cmd for Ctrl and Option for Alt where appropriate. That's easy to forget when you're listening instead of looking at a table.

Alex: Right. Those shortcuts are your reset points. If VS Code feels noisy, don't hunt around the screen first. Send focus somewhere known, like Ctrl+1 for the editor or Ctrl+Shift+P for the Command Palette.

Jamie: I like that because focus loss is one of those moments where people blame themselves. But the fix can just be, go back to a known area.

Alex: Inside the editor, the movement shortcuts matter just as much. Ctrl+Home and Ctrl+End move to the beginning or end of a file. Ctrl+G lets you jump to a line number, or to a line and column with a pattern like 10:5. Ctrl+P opens a file by name, Alt+Z toggles word wrap, Ctrl+= and Ctrl+- change the editor font size, Ctrl+M toggles Tab focus mode, and Ctrl+Shift+; opens breadcrumb navigation.

Jamie: Tab focus mode is worth calling out. When it's on, Tab moves between interface controls instead of inserting a tab character into the file. That's a big difference for screen reader users moving through widgets.

Alex: Find is another anchor. Ctrl+F opens Find in the current file, and the toggles are Alt+C for match case, Alt+W for whole word, and Alt+R for regular expression search. Screen readers announce those toggles as checkboxes, Space changes them, and the match count is announced as you type. F3 and Shift+F3 move through results, and Escape closes Find while returning focus to the last cursor position.

Jamie: And replace is Ctrl+H. Then Ctrl+Shift+1 replaces the current match, while Ctrl+Alt+Enter replaces all matches. That's one of those shortcuts where I want people to pause before using replace all.

Alex: Global search is Ctrl+Shift+F, and it searches across the workspace. The same case, word, and regex toggles work there, and you can Tab to include or exclude file filters. Useful glob patterns include docs/*.md for Markdown files in a docs folder, *.agent.md for agent definition files, .github/** for everything inside the .github folder, and !node_modules/** to keep that folder out of results.

Jamie: Tree views have their own fast filter too. In Explorer or Source Control, focus the tree and start typing part of a filename. VS Code opens a little filter field, narrows the tree, and Escape clears it.

Alex: For Markdown, Ctrl+Shift+O opens a symbol picker filled with headings. Type a few letters, press Enter, and you're there. In Explorer, Up and Down move through items, Right Arrow expands a folder, Left Arrow collapses it, Enter opens a file, F2 renames, Delete deletes, and Ctrl+N starts a new file that you'll save with Ctrl+S.

Jamie: The learning-card version is pretty practical: use Ctrl+G for line jumps, listen for Find counts, use Ctrl+Down in the Keyboard Shortcuts editor when your screen reader announces that hint, turn on word wrap at high zoom, and use breadcrumbs or Quick Open when the file tree is too much.

Alex: The Problems panel is where VS Code collects errors, warnings, and informational messages from tools like markdownlint, eslint, or Pylance. Open it with Ctrl+Shift+M, or jump through problems from the editor with F8 and Shift+F8.

Jamie: What does a problem entry actually contain? Because a red icon alone doesn't help if you aren't using the screen visually.

Alex: Each entry includes severity, the message, the source tool, the file name, and the line number. A screen reader should read those pieces together, and pressing Enter on a problem row jumps straight to the source line. The status bar also shows the current errors and warnings count, and it updates as files change.

Jamie: So if markdownlint complains about a heading, I can open Problems, hear the message and line, press Enter, fix it, and use F8 for the next issue without manually searching the file.

Alex: The integrated terminal is where local Git work often happens. Ctrl+` opens it, and from there you can run commands like git status, git add, git commit, or test commands for a project.

Jamie: Terminals can be the noisiest part of the whole editor. A command prints a lot of text, focus moves, a prompt appears, and suddenly you're not sure what changed.

Alex: VS Code's terminal shell integration helps by making command boundaries clearer. When shell integration is available, VS Code can better identify prompts, command output, command success, and command failure. That improves navigation, accessibility signals, and the ability to review output after the fact.

Jamie: So the habit is not just type a command and hope. Run the command, read the output, and confirm whether the prompt has returned.

Alex: Yes. If output streams quickly, use Accessible View or the terminal's accessible reading features to review it in a calmer reading surface. You can also create or switch terminals from the terminal controls or Command Palette, but the key idea is to keep track of which terminal is active before running a command.

Jamie: And if the terminal steals focus when I didn't expect it, Ctrl+1 gets me back to the editor. That one shortcut can save a lot of frustration.

Alex: Copilot Chat in VS Code has its own accessibility patterns. You can open it with Ctrl+Alt+I or by running Chat: Open Chat from the Command Palette.

Jamie: And Chat has modes now. Learners may hear Ask, Edit, and Agent mode and wonder which one they are in.

Alex: Ask mode is for questions and explanations. Edit mode helps propose changes to files. Agent mode can plan and work across files, and may ask for confirmation or interact with the terminal. Chat participants, such as @workspace, @vscode, or @terminal, help aim the question at a particular context.

Jamie: The accessibility issue I hear most is, Copilot answered, but I don't know how to read the whole response without getting lost.

Alex: That's where Accessible View is useful, especially for streamed responses. After Copilot responds, open Accessible View and read the response in a stable text surface. In Agent mode, pay attention to question prompts, confirmation choices, and terminal focus, because the workflow can move between chat, editor, and terminal.

Alex: Accessible Help is a context-aware keyboard guide. If you're in the editor and press Alt+H, or open the Accessible Help command from the Command Palette, VS Code gives shortcuts and guidance for the current area.

Jamie: So it changes depending on where focus is. Help in the editor is not the same as help in the terminal or a list.

Alex: Exactly. In the editor, Accessible Help might remind you about navigation, selection, and screen reader commands for that context. It's useful when you know where you are but can't remember the local controls.

Jamie: Accessible View is a little different. That's for reading content that may be dynamic, temporary, or hard to reach directly.

Alex: Yes. Open it with the Open Accessible View command, or use the assigned shortcut if your setup has one. It can present things like Copilot responses, hover documentation, terminal output, or other dynamic content in a readable view. For Copilot, ask the question, wait for the answer, open Accessible View, read, copy anything you need, then return to chat or the editor.

Jamie: And for hover documentation, the pattern is similar. Trigger the hover, open Accessible View, read it without chasing a floating box, then close it when you're done.

Alex: The Accessible Diff Viewer helps with changes. Open a diff, then use the Accessible Diff Viewer command to review additions, deletions, modifications, and line information without visually scanning side-by-side panes. During the workshop, that's useful before committing, when checking a pull request, or when reviewing Markdown edits.

Jamie: Diff audio cues can help too, as long as they don't become noise. A sound for an inserted or deleted line can be helpful when you're moving through a change.

Alex: Accessibility signals are VS Code's way of giving nonvisual feedback for events. They can use sound, announcements, or both, depending on the signal and your settings.

Jamie: So this is not just one beep for everything. Different events can have different signals.

Alex: Right. There are signals for editor events, diffs, terminals, chat and Copilot, debugging, editor actions, voice features, and code actions. To explore them, use the commands that list signal sounds and signal announcements. You can also control volume, which matters if you rely on a screen reader, system audio, and VS Code sounds at the same time.

Jamie: When do you actually want them on?

Alex: For this workshop, I would prioritize signals that help you catch problems and state changes: errors and warnings, terminal command failed, chat response received, and meaningful diff changes. I would be careful with position-based signals if they fire too often while you arrow through code. If you used older audio cue settings, search Settings for accessibility signals and audio cues so you can migrate to the current signal settings.

Jamie: So audio can reduce uncertainty, but only if it's tuned. Too many cues can make VS Code feel busier, not clearer.

Alex: VS Code Speech adds voice input and output features through the VS Code Speech extension. Once it's installed, you can dictate into the editor, speak prompts to Copilot Chat, and listen to chat responses.

Jamie: That's useful for fatigue too, not only for vision access. Typing a long prompt or a paragraph of Markdown can be tiring.

Alex: Exactly. Editor dictation turns speech into text where the cursor is. Voice in Copilot Chat lets you speak your request instead of typing it. Text-to-speech can read Copilot responses automatically after voice input, or you can manually trigger read-aloud for a response.

Jamie: And then there's Hey Code, the hands-free activation phrase.

Alex: Yes, if it's supported and enabled in your environment. Speech settings also cover language configuration, voice behavior, and related commands. If voice is central to your workflow, it's worth assigning custom keybindings for the commands you use most and checking platform support before you rely on it during a timed activity.

Jamie: I would also test it in a quiet moment, not five minutes before a live commit. Microphone permissions and language settings are much easier to fix when you're not under pressure.

Alex: Markdown authoring in VS Code comes up constantly in this course. You're editing READMEs, issue text, contribution notes, and sometimes agent definition files.

Jamie: Markdown preview helps, but I don't want listeners to feel like preview is the only way to understand the document.

Alex: Right. The preview is useful, and you can open it when you want to check rendered structure. But the Outline view and Ctrl+Shift+O are often faster for headings. The markdownlint extension catches common formatting issues, and Copilot can help revise Markdown, draft summaries, or suggest clearer wording.

Jamie: What about shortcuts?

Alex: Use the Keyboard Shortcuts editor to find or assign Markdown-related commands, including preview commands and any formatting helpers you prefer. The bigger workshop reason is quality: clean Markdown makes issues, pull requests, plans, and documentation easier for maintainers and other contributors to read.

Jamie: What should someone do when VS Code just feels tangled? Too many panels, too much speech, not sure where focus went.

Alex: Start simple. Press Escape once or twice to close transient widgets, then Ctrl+1 to return to the editor. If you need a tool, open it directly: Ctrl+Shift+M for Problems, Ctrl+Shift+F for Search, Ctrl+` for terminal, or Ctrl+Shift+P for the Command Palette. If content is hard to read, try Accessible View. If you don't know the local controls, open Accessible Help.

Jamie: And if the problem is not your memory but the interface changing, go back to trusted references.

Alex: Yes. The VS Code accessibility documentation and the GitHub guide for Copilot accessibility in VS Code are the main references for these features. The course appendices on VS Code and screen reader shortcuts are also useful when you want a compact reminder.

Jamie: The real win here is confidence. You can move to a known area, inspect messages, read dynamic content, tune audio feedback, and keep working locally without losing the thread.

Transcript

Alex: Welcome back. Today we're talking about Git authentication, which is the part of GitHub that proves you are who you say you are before GitHub lets you change something.

Jamie: So this is the moment where Git stops being just, I can read this project, and becomes, I am allowed to push changes here.

Alex: Exactly. GitHub asks you to authenticate when you push commits, clone a private repository, or access organization repositories that require certain permissions. You usually do not need authentication to clone a public repository, view public code on GitHub.com, or read public issues and pull requests.

Jamie: And if somebody is only using the GitHub website or GitHub Desktop, they may not have to touch this appendix right away.

Alex: Right. This becomes most relevant when you're using VS Code with command-line Git and you want to push commits to your fork or another repository. The reference is set up with two main paths, a Personal Access Token path and an SSH key path, plus troubleshooting by exact error message. If you use a screen reader, heading navigation and numbered steps are useful here; if you use magnification, the code blocks and separate method sections help you keep the two paths apart.

Jamie: Okay, two paths. Is that the same as HTTPS versus SSH?

Alex: Yes. With HTTPS, your remote URL usually starts with https://github.com, and Git asks for a username and a credential. With SSH, your remote URL usually looks like git@github.com:owner/repo.git, and Git proves your identity with a key stored on your computer.

Jamie: The HTTPS credential is the Personal Access Token, right? Not my GitHub password.

Alex: Correct. A Personal Access Token, or PAT, is a password-like string you generate on GitHub and paste when Git asks for a password. GitHub has fine-grained tokens, which can be limited to specific repositories and permissions, and classic tokens, which are broader and still appear in many workshop instructions. The workshop reference recommends a classic token because it is straightforward to create through the web interface, but the security habit is the same either way: grant only the access you need.

Jamie: The nice part is that tokens work everywhere and are easy to revoke. The less nice part is that you have to store them safely, and they expire.

Alex: That's the tradeoff. SSH uses a key pair instead: a public key that you add to GitHub, and a private key that stays on your computer. Once SSH is set up, it usually stops prompting you, but the first setup is more command-line heavy. And the private key is secret; never paste it into GitHub, email, chat, or a repository.

Jamie: If I'm following the recommended workshop route, how do I make the token?

Alex: Start at github.com/settings/tokens. Choose Tokens classic, then generate a new classic token. Give it a clear note, such as Workshop Laptop Token, choose a short expiration like 30 or 60 days, and select the scopes you need. The common workshop scope is repo, and workflow is only needed if you will update GitHub Actions workflow files.

Jamie: And when GitHub shows the token, copy it right then. You don't get to come back and view it later.

Alex: Yes. If you're using a screen reader, the token appears as a long string in a text field, so select all, copy, and move it directly into a safe place. A password manager is best, an encrypted note can work, and a plain text file should only be temporary and only inside an encrypted folder.

Jamie: What should people avoid?

Alex: Do not paste the token into an unencrypted document that syncs to the cloud. Do not email it to yourself. And definitely do not save it in a public GitHub file. The next time Git asks for credentials, enter your GitHub username, and paste the token where Git asks for a password.

Jamie: This is where credential storage helps, because nobody wants to paste that long token every time.

Alex: Exactly. Git Credential Manager is the recommended cross-platform helper because it stores credentials securely and integrates with GitHub sign-in flows. On Windows, Git Credential Manager often remembers the token after first use. On macOS, Keychain may ask to save it, and you can choose Always Allow. On Linux, you can use Git Credential Manager too, or a temporary cache with git config --global credential.helper cache.

Jamie: What about the SSH path? I know people like it, but the words public key and private key can sound a little mysterious.

Alex: Start by checking whether you already have one. In a terminal, run ls -al ~/.ssh and look for files like id_rsa.pub or id_ed25519.pub. The .pub file is the public key, and the matching file without .pub is the private key.

Jamie: If there is no key, the command is ssh-keygen, right?

Alex: Yes. A common modern command is ssh-keygen -t ed25519 -C "your-email@example.com". When it asks where to save the key, pressing Enter accepts the default location. A passphrase is optional, but recommended, because it protects the key if someone gets access to your computer.

Jamie: Then we copy the public key, not the private one.

Alex: Exactly. In Windows PowerShell, you can use Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard. On macOS, use pbcopy < ~/.ssh/id_ed25519.pub. On Linux, you can run cat ~/.ssh/id_ed25519.pub, then manually select and copy the output.

Jamie: And that output should start with something like ssh-ed25519 or ssh-rsa.

Alex: Right. Then go to github.com/settings/keys, choose New SSH key, give it a title like Workshop Laptop SSH Key, set the key type to Authentication Key, paste the public key, and add it. GitHub may ask for your password or 2FA code. After that, test with ssh -T git@github.com, and a successful response starts with Hi username, you've successfully authenticated.

Jamie: Here's a very real question. What if I set up SSH perfectly, but my repository was cloned with HTTPS?

Alex: Then Git will still try to use the HTTPS route, because the remote URL controls the method. Run git remote -v to see the current remote. If you want SSH, set it with git remote set-url origin git@github.com:your-username/repo.git.

Jamie: And to go the other direction?

Alex: Use git remote set-url origin https://github.com/your-username/repo.git. This is worth checking before you regenerate tokens or keys, because the wrong remote URL can make a working credential look broken. HTTPS expects a token or credential helper, and SSH expects a configured key.

Jamie: Authentication errors can feel personal, but they usually have pretty specific causes.

Alex: They do. If you see Authentication failed when pushing, the token is often expired, mistyped, or stored incorrectly. Generate a new PAT, clear the old saved credential from Windows Credential Manager, macOS Keychain, or on Linux with git credential-cache exit, and push again so Git asks for credentials.

Jamie: What about Permission denied publickey?

Alex: That means SSH did not find a key GitHub accepts. Check that the public key is added at github.com/settings/keys, then run ssh-add -l to see what your SSH agent knows about. If your key is missing, add it with ssh-add ~/.ssh/id_ed25519.

Jamie: And Host key verification failed?

Alex: That means your computer does not recognize GitHub's host key yet, or the stored host key does not match. The reference gives ssh-keyscan github.com >> ~/.ssh/known_hosts as the direct fix. If anything about the warning seems unusual, pause and verify against GitHub's official SSH documentation before accepting a host key.

Jamie: Let's talk security habits, because tokens and keys are powerful.

Alex: Treat a PAT and a private key like passwords. Use the smallest token scopes that will do the job, set expiration dates on tokens, use a passphrase on SSH keys, and revoke old tokens when you're done with a project or device. Also, do not commit tokens, private keys, or local config files that contain secrets; use .gitignore for files that should stay on your machine.

Jamie: But the public key is different.

Alex: Yes. The public key is meant to be uploaded to GitHub and can be shared in that limited sense. The private key and tokens are the pieces that must stay protected.

Jamie: Commit signing sounds related, but it is not exactly the same as logging in, is it?

Alex: Right. Authentication lets you push or access a repository. Commit signing marks individual commits with a cryptographic signature, and GitHub can show a Verified badge when the signature matches a key connected to your account.

Jamie: So maintainers can see that the commit really came from a trusted key, not just from a name and email typed into Git config.

Alex: Exactly. There are two common signing methods. SSH signing is simpler for many learners because it can reuse an SSH key you already have, though you still add it to GitHub as a signing key and configure Git for SSH signing. GPG signing is the older traditional method and has more setup steps.

Jamie: Give me the short version of SSH signing first.

Alex: You tell Git to use SSH for signing with git config --global gpg.format ssh. Then you set your signing key, usually pointing Git at your public SSH key file, and turn on signing with git config --global commit.gpgsign true. In GitHub settings, add the same public key as a signing key, not just an authentication key.

Jamie: And the GPG route is the one with key IDs and the public key block.

Alex: Yes. You generate a GPG key with gpg --full-generate-key, choose RSA and RSA, 4096 bits, and usually no expiration if that is what your organization expects. Use the email address associated with your GitHub account. Then find the key ID with gpg --list-secret-keys --keyid-format=long; the output includes something like sec rsa4096/XXXXXXXXXXXXXXXX, and the X part is the key ID.

Jamie: Then export the public part and add it to GitHub.

Alex: Right. Export it with gpg --armor --export followed by the key ID, and copy the block that starts with BEGIN PGP PUBLIC KEY BLOCK. Add that public key in GitHub's SSH and GPG keys settings. Then configure Git with your signing key ID and turn on commit.gpgsign true so future commits are signed automatically.

Jamie: Where does Vigilant Mode fit into this?

Alex: Vigilant Mode is a GitHub account setting that makes commit verification more visible and stricter in how unsigned or unverified commits are shown. Some maintainers use it because they want a clearer signal about which commits were signed by trusted keys. As a contributor, you may see badges such as Verified, Unverified, or Partially verified beside commits.

Jamie: If you're using a screen reader, don't just assume the icon color tells the whole story.

Alex: Right. Move to the badge text near the commit, and open the badge details when you need the reason. GitHub will usually explain whether the signature is valid, missing, attached to an unknown key, or tied to an email mismatch.

Jamie: For this workshop, the practical recommendation is still pretty calm.

Alex: Use a Personal Access Token if you need a straightforward way to push from the command line. Use SSH if you're comfortable with terminal setup and want a smoother long-term flow. Commit signing is valuable, especially in security-conscious projects, but it is usually something to add after your basic push workflow is working unless a repository specifically requires it.

Jamie: So the pattern is: choose HTTPS with a token or SSH with a key, store secrets safely, check your remote URL, and troubleshoot from the exact error message.

Alex: Exactly. Authentication is GitHub checking whether the person asking to change a repository is allowed to do it. Once that is set up, push, pull, and contribution work get much quieter.

Transcript

Alex: Welcome back. Today we're slowing down just enough to make Git feel less like a magic trick and more like a set of places where your work moves.

Jamie: I like that, because Git commands can sound small, like add, commit, push, pull. But when one of them surprises you, it suddenly feels like the floor disappeared.

Alex: Exactly. On Day 1, GitHub.com handled a lot for you behind the scenes. You edited a file, clicked a button, and GitHub created the commit and kept track of the branch.

Jamie: And on Day 2, learners start doing that locally, on their own computer.

Alex: Right. Challenge 10, Go Local, is where this becomes practical: cloning, local branches, commits, pushing, and sorting out what is local versus what is on GitHub. The rest of the Day 2 Git work also leans on this model, and the habit is to understand local Git mechanics first, then connect them to GitHub workflows and the gh command line later.

Jamie: So when people say Git has a working tree, staging area, and repository, what are those in plain language?

Alex: The working tree, also called the working directory, is the project folder on your computer. If you open the project in VS Code and browse files in the Explorer, those files are in your working tree. They are real files you can edit, rename, or delete.

Jamie: So changing a file there does not mean Git has saved that change forever.

Alex: Correct. Git notices the change, but it waits for you to choose what belongs in the next commit. That choosing happens in the staging area, which is also called the index.

Jamie: That is the part I used to skip over. Staging is not just a speed bump; it lets me decide which changes travel together.

Alex: Yes. You might fix a typo in one file and experiment with a larger rewrite in another. You can stage the typo fix, leave the experiment unstaged, and make a clean commit that only contains the typo fix. Then, when you commit, Git records what you staged into the repository, which lives in the hidden .git folder inside the project.

Jamie: The packing box comparison helps me here. The desk is the working tree, the open box is staging, and the sealed box is the commit.

Alex: That is a good way to remember the movement. Edit files in the working tree, stage the changes you want, then commit the staged changes into Git's stored history. In command form, that is the path from editing a file, to git add file.md, to git commit -m 'short description'.

Jamie: And if you are not relying on visuals, there are ways to check where things are.

Alex: Definitely. In the terminal, git status tells you which files are changed, which are staged, and whether there is anything ready to commit. In VS Code Source Control, Ctrl+Shift+G opens the panel, where files appear under Changes before staging and Staged Changes after staging. Pressing Enter on a file opens the diff, and many screen readers announce added and removed lines with change labels; low vision users can also use zoom, panel width, file badges like M or U, and editor gutter indicators for added, modified, or deleted lines.

Jamie: A commit is often described as a save point. Is that accurate enough?

Alex: It is accurate as a starting point, but there is one important detail. A commit is a snapshot of the project at a moment in time, not just a list of edits. Each commit records the staged file content, a message, the author name and email, and a pointer to the commit that came before it.

Jamie: And each commit gets one of those long IDs, right?

Alex: Yes. Git gives every commit a SHA hash, which is usually shown as a long 40-character identifier. In daily work, you often see the short version, like the first 7 characters, and that is usually enough for commands and conversation.

Jamie: Do learners need to memorize those hashes?

Alex: No. Treat them like confirmation numbers. They are useful when you want to point to a specific commit, but you can copy them from git log, GitHub, or VS Code.

Jamie: The source says commits are permanent, mostly. What is the 'mostly' doing there?

Alex: Once a commit is in the repository history, you normally do not erase it. If you made a mistake, you usually add another commit that fixes or reverses the problem. Git does have advanced history rewriting tools, but for this course, the safer mental model is that commits give you a history you can inspect and recover from.

Jamie: That connects back to Day 1. When I clicked Commit changes on GitHub.com, GitHub staged and committed for me in one action.

Alex: Exactly. Locally, you get more control because staging and committing are separate. In VS Code, you type a commit message in the Source Control message box and commit from there, often with Ctrl+Enter. Afterward, git log --oneline -5 gives you the last few commits, and the Timeline view can show a file's history in order.

Jamie: Branches are another place where people get nervous. Is a branch a copy of the whole project?

Alex: Not in the way people often imagine. A branch is a movable label that points to a commit. The default branch is usually main, and when you create a new branch, that new label starts at the commit you are currently on.

Jamie: Then when I commit on that branch, the label moves forward?

Alex: Exactly. Your new commits extend that line of work, and the branch name follows the newest commit on that line. Git also uses HEAD to track where you are currently working, usually meaning which branch is checked out.

Jamie: So HEAD is not another branch I have to manage. It is Git's marker for my current position.

Alex: Right. If HEAD is on your feature branch, new commits go there. If HEAD is on main, new commits go to main, which is why it is worth checking your branch before you start editing.

Jamie: And branches are what let me work without disturbing main.

Alex: Yes. You can create a branch for a fix, make commits there, push it to GitHub, and open a pull request when it is ready. Later, merging brings that work back into main or another target branch.

Jamie: Local versus remote is the other big dividing line. What lives where?

Alex: Your local repository is the copy on your computer, including the working tree and the .git history. The remote repository is the copy hosted somewhere else, usually GitHub. They are related, but they are not the same place.

Jamie: So clone is the first movement from GitHub to my computer.

Alex: Yes. git clone copies the remote repository to your machine and sets up a connection, commonly named origin. After that, you can make local commits even if GitHub has not seen them yet.

Jamie: That two-copy idea explains a lot. My computer can be ahead, GitHub can be ahead, or both can have different new work.

Alex: Exactly. A local commit stays local until you push it. Changes made on GitHub or by other contributors do not update your working copy until you fetch or pull.

Jamie: Can we slow down on those direction words?

Alex: Push sends your local commits up to the remote. Fetch contacts the remote and downloads information about new commits without merging them into your current branch. Pull gets remote work and integrates it into your current branch, usually by doing a fetch followed by a merge, though some projects configure pull to rebase instead.

Jamie: So fetch is the cautious check, pull is the check plus bring it in, and push is share my work.

Alex: That is the practical version. In Challenge 10, those words stop being abstract because you clone your Learning Room repository, create a local branch, commit locally, and push back to GitHub. The Learning Room repository is the learner's provisioned space for the Day 1 issue, branch, commit, pull request, and merge workflow, and now you are seeing the same Git ideas from your computer.

Jamie: Merge conflicts sound like Git being angry. Are they actually an error?

Alex: They are not a moral failure, and they are not rare. A merge conflict happens when Git cannot safely combine two sets of changes. The classic case is two branches editing the same lines in the same file, but conflicts can also happen when one side edits a file and the other side deletes it.

Jamie: What does a conflict look like when you open the file?

Alex: Git may insert conflict markers into the file. You might hear or see lines beginning with seven less-than signs, then a section of one version, then seven equals signs, then the other version, and finally seven greater-than signs. VS Code often adds controls to accept current change, accept incoming change, accept both, or compare them.

Jamie: That sounds alarming, but at least it is visible in the file.

Alex: Exactly. To resolve it, you open the conflicted file, decide what the final text should be, remove the markers, save, stage the resolved file, and commit the merge result if Git asks for one. The important part is to read the surrounding text, not just pick a button as fast as possible.

Jamie: So a conflict means Git needs a human decision because both sides changed something Git cannot judge on its own.

Alex: Yes. And once you understand working tree, staging, branch, and remote, the recovery path is less mysterious. git status will usually tell you which files are unmerged and what Git expects you to do next.

Jamie: I want to talk about the timeline idea, because history can feel like a pile of commit messages.

Alex: Git history is a chain of commits connected by parent pointers. When you read git log from the newest commit backward, you are walking that chain in reverse time. The commit message tells you the human reason, while the hash gives Git a precise reference.

Jamie: And branching creates more than one line in that timeline.

Alex: Yes. A branch lets work continue in parallel from a shared earlier commit. When the work is merged, the timelines reconnect, sometimes with a merge commit that records the moment two lines came together.

Jamie: That is where Bonus E, Git History, fits nicely.

Alex: It does. Bonus E uses history as a learning tool: reading commits over time, noticing how a project changed, and using the log to answer questions like when a file changed, what branch introduced a fix, or why a change was made. It turns history from something hidden into something you can study.

Jamie: This also makes VS Code Source Control less spooky. The panel is not inventing a separate system; it is showing Git's areas.

Alex: Exactly. The Changes list is your working tree. Staged Changes is the staging area. The message box plus the commit action writes a commit to your local repository. Sync, push, pull, and fetch are all about moving commits between your local repository and the remote on GitHub.

Jamie: And if something feels wrong, the first move is not to panic-click around the interface.

Alex: Right. Check which branch you are on, then run git status. If you need context, run git log --oneline -5, or fetch before deciding whether to pull. Do not delete the .git folder to 'start over'; that folder is the repository history. If authentication is the problem, use the course material on Git authentication, and for deeper reading, the Pro Git book and GitHub's About Git, GitHub flow, and pull request docs are reliable references.

Jamie: So the compact checklist is: where are my files, what is staged, what branch am I on, what commits exist locally, and what has or has not reached GitHub.

Alex: Yes. If you can answer those questions, Git becomes much easier to recover from. The commands are still commands, and you will still look things up, but you will know what kind of movement each command is trying to perform.

Transcript

Alex: Welcome back. Today we're moving Git out of the browser and into VS Code, where you can clone a repo, edit files, stage changes, commit, push, pull, and open the path toward a pull request.

Jamie: This is the moment where Git starts feeling real, right? Not just buttons on GitHub.com, but a local copy on your own machine.

Alex: Exactly. This supports Challenge 10, Go Local, where you clone your private Learning Room repository, create or use a learn/<username> branch, make one commit, push it, and use that work as evidence. Then Challenge 11 builds on it by opening a Day 2 pull request from that pushed branch and reading the PR in VS Code.

Jamie: And just to be very clear, the Learning Room repository is the one GitHub Classroom created for each learner. It is not the facilitator template repository.

Alex: Right. Use the private repo URL that looks like https://github.com/<workshop-org>/learning-room-<your-username>.git. Also, the shortcuts are mostly Ctrl on Windows and Linux, and Cmd on Mac, so Ctrl+Shift+P becomes Cmd+Shift+P, Ctrl+Shift+G becomes Cmd+Shift+G, and Ctrl+Enter becomes Cmd+Enter.

Jamie: Let's start with cloning, because that word sounds simple until you have three different tools offering to do it.

Alex: Cloning means making a full local copy of a Git repository. In VS Code, the most reliable path is the Command Palette: press Ctrl+Shift+P, run Git: Clone, paste the repository URL, choose a folder you can find again, and then open the cloned repository when VS Code asks.

Jamie: So VS Code is still using Git underneath, but it gives you prompts instead of making you remember the whole command.

Alex: Yes. The terminal version is git clone followed by the repository URL. The GitHub CLI version is gh repo clone owner/name, which is shorter and can handle GitHub authentication nicely once gh is signed in. VS Code also has a Start Page clone button, and GitHub.com has a Code button where you can copy the URL.

Jamie: What should a screen reader user expect while the clone is happening?

Alex: VS Code usually shows a progress notification. NVDA often reads it automatically, and if nothing seems to happen, you can run Notifications: Focus Notification Toast from the Command Palette. When the clone finishes, open Explorer with Ctrl+Shift+E and confirm you hear files such as README.md and folders such as docs.

Jamie: And after cloning, you might only see main locally, even if there are branches on GitHub.

Alex: Yes. A fresh clone checks out the default branch, often main. In the terminal, git branch -a lists local branches and remote-tracking branches like remotes/origin/learn/yourname. The star marks your current branch, and git switch learn/yourname or git checkout learn/yourname can create a local branch that follows the one on GitHub.

Jamie: The chapter also gives a low-stakes practice clone with the Sci-Fi Themes repo, which is helpful if you want to rehearse before touching your Learning Room work.

Alex: That's a good warm-up. You can clone with gh repo clone owner/name, cd into the folder, and open it in VS Code with code . if the code command is installed.

Alex: Once the repository is open, the Source Control view becomes your main Git dashboard in VS Code.

Jamie: That's the branch-looking icon in the Activity Bar, and the shortcut is Ctrl+Shift+G, or Cmd+Shift+G on Mac.

Alex: When it opens, you get the commit message input near the top, then groups of files such as Changes and Staged Changes. A changed file might be modified, added, deleted, renamed, or untracked. You can open a file's diff, stage it with the plus button, or use the context menu with Shift+F10.

Jamie: I like that the panel separates what changed from what is ready to commit. That reduces the mystery.

Alex: Git is tracking three areas. The working tree is the folder you are editing. The staging area is the set of changes you have selected for the next commit. The repository is Git's saved history after you commit.

Jamie: So the file states are untracked for a new file Git is not tracking yet, modified for a tracked file that changed, and staged for a change that is queued for the next commit.

Alex: Exactly. In the terminal, git status gives the same overview, git status -s gives a compact one-letter view, git diff shows unstaged changes, and git diff --staged shows what is ready to commit. Those command cards in the chapter are worth keeping nearby because they give you another way to verify what VS Code is showing.

Jamie: Branches are where a lot of people get nervous. What is the practical version?

Alex: A branch is a named line of work. For Challenge 10, you either switch to your existing learn/<username> branch or create it if it does not exist yet. In VS Code, use the Command Palette and run Git: Checkout to... for an existing branch, or Git: Create Branch... for a new one.

Jamie: And naming matters because maintainers and facilitators read those names later.

Alex: Yes. A name like learn/yourname or docs/improve-welcome is easier to understand than random-test. After you switch, the status bar shows the current branch. You can focus the status bar to hear it, and you can also run git branch --show-current.

Jamie: What happens when you switch branches?

Alex: VS Code updates the files in your working tree to match that branch. If you have uncommitted changes that would be overwritten, Git will stop and ask you to commit, stash, or discard them first. In the CLI, git switch -c branch-name creates and switches, git switch branch-name switches, git branch lists local branches, and git branch -a includes remote-tracking branches.

Jamie: And after a pull request is merged, deleting the branch is cleanup, not part of making the contribution real.

Alex: Right. You can delete a merged local branch with git branch -d branch-name, and delete a remote branch with git push origin --delete branch-name. Use force deletion only when you are certain the work is no longer needed.

Alex: Staging is the part of Git that lets you choose exactly what goes into a commit.

Jamie: Why not just commit everything that changed?

Alex: Sometimes that is fine, but staging gives you control. Maybe you fixed a typo and also started a bigger edit that is not ready. You can stage one file, stage all changes, or stage only selected lines or chunks, which Git often calls hunks.

Jamie: That is especially useful in workshop practice because a small commit is easier to explain and easier to review.

Alex: In VS Code, use the plus button next to one file to stage that file, or the plus button on the Changes group to stage everything. For line or chunk staging, open the diff and use the stage controls for the selected change. In the CLI, git add path stages one file, git add . stages current folder changes, and git add -p walks you through hunks interactively.

Jamie: And if you stage the wrong thing?

Alex: You can unstage it. In VS Code, use the minus button in Staged Changes. In the terminal, git restore --staged path removes it from the staging area without deleting your edit. Then check again with git status or by reading the Source Control groups.

Jamie: What about throwing changes away? That feels risky.

Alex: It should feel serious. Discard only when you are sure you do not need the edit. VS Code can discard one file or all unstaged changes, while git restore path does the same in the terminal. If you might need the work later, stash it instead; and if you truly want to remove a file from the repository, use Git Delete in VS Code or git rm path so the deletion is tracked and can be committed.

Jamie: Now we have changes staged. What makes a good commit?

Alex: A commit is a saved snapshot plus a message. A good subject line is short, specific, and written like an action, such as docs: improve welcome.md introduction. Many teams use a prefix like docs, fix, chore, or feat, followed by a colon and a plain-language summary.

Jamie: And the commit message input is at the top of Source Control.

Alex: Yes. Type the message there, then press Ctrl+Enter, or Cmd+Enter on Mac. Screen readers usually announce the Source Control state changing afterward because the staged files disappear. That is your signal that the commit was created locally.

Jamie: Local is the key word there.

Alex: Exactly. A commit on your computer is not on GitHub yet. In the terminal, the equivalent is git commit -m followed by your message. You can also use git commit without -m to write a longer message in an editor, or git commit -am for tracked files only, but beginners should be careful because that skips untracked new files.

Alex: Pushing sends your local commits to GitHub.

Jamie: So if I commit and then close my laptop, GitHub does not know about that commit until I push.

Alex: Correct. In VS Code, run Git: Push from the Command Palette, or use the sync and publish controls in the Source Control area. If the branch is new, VS Code may say Publish Branch. That creates or connects the branch on GitHub, often called origin, so your local branch has a remote tracking branch.

Jamie: Remote tracking branch is one of those phrases that sounds bigger than it is.

Alex: It means your local branch knows which branch on GitHub it normally pushes to and pulls from. In the CLI, the first push for a new branch is often git push -u origin branch-name. After that, git push is usually enough because Git remembers the relationship.

Jamie: Pulling is the opposite direction, then?

Alex: Mostly, yes. Pulling downloads commits from GitHub and integrates them into your current branch. Technically, git pull is git fetch plus a merge by default. If you want to see what changed before integrating, run git fetch, then git status or git log.

Jamie: When would git pull --rebase come up?

Alex: Use it when your local branch and the GitHub branch both have new commits, and you want your local commits replayed on top of the latest remote commits for a cleaner history. It is common on personal feature branches, but be careful on branches other people are also using. If a conflict appears during rebase or pull, stop, read the conflicting files, resolve them, then continue the operation.

Jamie: And if push fails, the usual reason is that GitHub has commits you do not have yet.

Alex: Right. Run git fetch, check git status, pull or pull with rebase if appropriate, resolve any conflicts, and then push again. For forked projects, GitHub.com may also offer a Sync fork button, and the terminal version is to add an upstream remote once, fetch upstream, merge or rebase the default branch, and push the updated branch back to your fork.

Jamie: Challenge 11 starts right after that push, because now the branch exists on GitHub and can become a pull request.

Alex: Yes. On GitHub.com, use Compare and pull request if the banner appears, or open Pull requests, choose New pull request, set base to main, compare to your branch, and include plain text like Closes #XX so the PR links to the challenge issue. If you prefer the web workflow for a small edit, you can still edit directly on GitHub.com, commit in the browser, and open a PR there, but Challenge 10 is about practicing the local path.

Jamie: Once work exists in history, how do you look back without getting lost?

Alex: VS Code has a Timeline view for a file. You can open it from the Explorer sidebar or through the Command Palette, and it shows recent saves and Git commits related to that file. Opening a commit lets you inspect what changed.

Jamie: And Git blame is the line-by-line history tool, right?

Alex: Yes. Blame shows which commit and author last changed each line. It is not about blaming a person; it is about finding context. In the terminal, git log shows repository history, git log -- path shows history for one file, git log -p includes patch details, git blame path shows line history, and git show commit-hash displays a specific commit.

Jamie: Conflicts are another kind of history lesson, but less friendly.

Alex: A merge conflict happens when Git cannot safely combine two edits to the same area. VS Code marks the file as conflicted and offers actions such as accept current, accept incoming, accept both, or compare changes. Do not just pick a button blindly; read the file and make the final content correct.

Jamie: The accessible diff view helps because you can move through changes in a more structured way than searching for conflict markers by hand.

Alex: Yes. Use the diff viewer, review one hunk at a time, save the resolved file, stage it, and complete the merge or rebase. If you realize you are in the wrong operation, git merge --abort can back out of a merge, and git rebase --abort can back out of a rebase.

Jamie: We touched stash earlier, but it deserves one more pass because it solves a very real problem: I changed files, and now I need to switch tasks.

Alex: Stash temporarily shelves uncommitted work. In VS Code, use the Command Palette for Git: Stash, then later Git: Apply Stash or Git: Pop Stash. Apply restores the changes and keeps the stash entry; pop restores the changes and removes the stash entry.

Jamie: The terminal version is git stash push -m with a message, git stash list, git stash show, git stash apply, and git stash pop.

Alex: Exactly. If you need to include new untracked files, use git stash push -u. You can drop one stash when you are done, or clear all stashes, but clear is a careful command because it removes every stash entry.

Jamie: And then there is reflog, the emergency tool.

Alex: Reflog records where your local branch tips and HEAD have been. If you deleted a branch or moved away from a commit, git reflog can help you find the old commit hash. The safer recovery move is usually to create a new branch at that hash, using git branch recovered-name hash, before doing anything destructive.

Jamie: But reflog is local. It is not a GitHub backup service.

Alex: Right. It exists on your machine and eventually expires entries. For everyday work, use steady habits: git status before acting, git branch --show-current before pushing, git fetch before assuming you are up to date, and clear PR text like Closes #XX.

Jamie: There are also alternatives if VS Code is not the best fit for a specific moment.

Alex: GitHub Desktop offers a visual Git interface. GitHub CLI gives commands like gh repo clone, gh pr create, gh pr view, and gh pr checkout. The Git CLI gives the most direct commands: clone, switch, add, commit, push, pull, fetch, status, log, restore, stash, and reflog.

Jamie: So the expected result for Challenge 10 is not a giant feature. It is evidence that the local workflow happened: the right branch name, a meaningful commit, a pushed branch, and PR metadata that links back to the issue.

Alex: Exactly. If you get stuck, confirm the repository URL, confirm you are on the intended branch, run git status, fetch before pushing, and ask for help with the exact message Git gave you. Small, verifiable steps make this workflow much less mysterious.

Transcript

Alex: Welcome back. Day 2 begins with Challenge 10: Go Local, and the shift is pretty big. Yesterday, GitHub.com handled a lot for you in the browser. Today, you bring the repository down to your computer, make a change locally, and send it back up.

Jamie: So this is the moment where Git stops feeling like a website button and starts feeling like an actual development workflow.

Alex: Exactly. The goal is simple: clone a repository, create a branch, edit a file, commit your change, and push that branch to GitHub. The change itself can be tiny. The workflow is the thing you're practicing.

Jamie: And the challenge title is doing a lot of work there: Go Local. We're proving that work done on your computer can still become part of a GitHub project.

Alex: Before the steps, let's steady the mental model. A remote repository is the copy on GitHub. A local repository is the copy on your computer, including a hidden .git folder where Git stores history.

Jamie: That two-copy idea helps. If I edit locally, GitHub doesn't magically know yet.

Alex: Right. Your local work moves through three areas. First, the working directory, which is the folder and files you can open and edit. Then the staging area, which is a holding place for the changes you want in the next commit. Then the repository history, where the commit is saved as a snapshot.

Jamie: So editing is not the same as committing. And staging is that middle step where I choose what belongs in the save point.

Alex: Yes. A commit records the staged snapshot, a message, the author, and a pointer to the previous commit. Git also gives it a unique hash, though most of the time you'll only hear or see the short version, around seven characters.

Jamie: And branches are how we keep work separate from main, right?

Alex: That's it. The default branch is usually main. When you create a branch, you're making a parallel line of work so your edit can be reviewed or tested without disturbing main. Git uses HEAD to track which branch you're currently on.

Jamie: Then push is the moment I share my local commits with GitHub. Pull brings GitHub's changes down and merges them, and fetch checks what's new without changing my files yet.

Alex: Perfect. And if two people change the same part of the same file, Git may need help deciding what to keep. That's a merge conflict. It is normal, and VS Code gives tools for reviewing those changes when it happens.

Jamie: What should learners have ready before starting this one?

Alex: You should have VS Code available for Day 2, though GitHub Desktop and the command line are also supported paths. If you're joining Day 2 without Day 1, that's okay if you already know the basics: repositories, issues, pull requests, and reviewing changes. The Day 2 Quick Start is there to check accounts, tools, and comfort level in about 30 minutes.

Jamie: And the repository choice matters here, because there are practice repos and learner repos floating around.

Alex: Use the repository URL given in your Challenge 10 issue or by your facilitator. In many cohorts, that is your private Learning Room repository, the one GitHub Classroom provisioned for you. Some practice material uses the sci-fi themes repository, with the URL https://github.com/Community-Access/vscode-sci-fi-themes.git. What you should not do is clone the facilitator template unless you were specifically told to maintain it.

Jamie: So if the instructions say Learning Room, I clone my own private Learning Room copy. If the issue gives the sci-fi themes URL, I use that. Either way, the pattern is the same.

Alex: Let's walk the VS Code path first, because it's the recommended Day 2 route. Open VS Code, then open the Command Palette with Ctrl+Shift+P, or Cmd+Shift+P on Mac. Type Git: Clone, choose that command, paste the repository URL, and choose a folder on your computer where you can find it again.

Jamie: After it clones, VS Code usually asks whether to open the cloned repository. Say yes, because opening the folder is what makes Source Control and the file tree line up with the repo.

Alex: Exactly. You can verify the clone by opening Explorer with Ctrl+Shift+E, or Cmd+Shift+E on Mac. You should hear or see files like README.md, and possibly a docs folder, depending on the repo.

Jamie: Then we need to get off main before editing.

Alex: Yes. Open the Command Palette again and run Git: Create Branch. In the challenge issue, the branch name may be fix/YOUR-USERNAME, where you replace YOUR-USERNAME with your GitHub username. In Learning Room practice, you may use a learn/<username> branch if your cohort is using that convention.

Jamie: I like checking the branch name in the status bar after that. It makes it harder to accidentally commit on main.

Alex: Good habit. Now open README.md or the file named in your issue, make a small edit, and save with Ctrl+S or Cmd+S. A typo fix, a clearer sentence, or one helpful comment is enough.

Jamie: Then Source Control time.

Alex: Open Source Control with Ctrl+Shift+G, or Cmd+Shift+G on Mac. Your changed file appears under Changes. Move to the file and activate the plus button, which stages it. Then type a commit message like docs: improve README wording, and commit with Ctrl+Enter or Cmd+Enter.

Jamie: After the commit, the change list should clear because the snapshot is now saved locally.

Alex: Right. But it is still only local. To share it, open the Command Palette, run Git: Push, and if VS Code asks to publish the branch or set upstream, confirm it. Setting upstream just links your local branch to a branch on GitHub so future pushes know where to go.

Jamie: What if someone prefers the terminal? I know some learners hear command line and immediately worry they're doing the harder version.

Alex: The terminal path is direct, not automatically harder. Start by cloning the repo URL your facilitator gave you, for example git clone followed by the URL. Then cd into the folder. A good check before changing anything is git status, and another is git branch --show-current.

Jamie: And to create the branch?

Alex: Use git checkout -b fix/YOUR-USERNAME, replacing the placeholder. Some newer materials also use git switch -c for the same create-and-switch action. Then edit a file in any text editor. You can use VS Code with code README.md, or another editor you already know.

Jamie: Stage and commit are the part where the mental model pays off.

Alex: Yes. Use git add with the file you changed, such as git add README.md or git add docs/welcome.md. Then commit with a clear message, for example git commit -m 'docs: fix typo in welcome page'. A descriptive message helps future you understand why the commit exists.

Jamie: Then push with the upstream link the first time.

Alex: Right: git push -u origin fix/YOUR-USERNAME. The -u connects your local branch to the remote branch named origin, which is GitHub in most cloned repos. After that, plain git push usually works from that branch.

Jamie: Where does GitHub CLI fit in?

Alex: GitHub CLI can shorten the clone step with gh repo clone owner/name, and it often handles authentication smoothly. But even if you use gh to clone, the Git ideas are the same: check status, know your branch, stage intentionally, commit locally, and push.

Jamie: GitHub Desktop is the other supported route, and it can feel calmer if you want labeled controls instead of commands.

Alex: Yes. In GitHub Desktop, choose File, then Clone repository. Use the URL tab, paste the repo URL, choose a local path, and select Clone. Once the repo is open, use the Current Branch menu or Branch menu to create a new branch, often fix/YOUR-USERNAME, based on main.

Jamie: Then you open the file in an editor, make the tiny change, and save it.

Alex: When you return to GitHub Desktop, it lists the changed file and shows the diff, which is the before-and-after view of the edit. Write a summary in the bottom-left box, such as docs: improve README wording. Then select Commit to your branch, and finally Publish branch at the top.

Jamie: So Desktop still does clone, branch, edit, commit, push. It just wraps the Git commands in a different interface.

Alex: Let's spend a minute on accessible Source Control habits, because they make local Git much less mysterious. In VS Code, Ctrl+Shift+G opens the Source Control panel. Files are grouped by state, so you can tell what is changed, what is staged, and what is ready to commit.

Jamie: When you use a screen reader, the names and states matter. Modified, added, deleted, staged... those words tell you where you are in the process.

Alex: Exactly. Press Enter on a changed file to review the diff. Added and removed lines are identified by the viewer, and you can stage a whole file with the plus button. More advanced users can stage selected lines or chunks, which is useful when one file contains two unrelated edits.

Jamie: And unstaging is allowed. If I staged the wrong file, I can move it back out before committing.

Alex: Yes, staging is reversible before the commit. Committing is more durable, so slow down there and write the message in plain language. A good message often starts with a type like docs or fix, then says what changed: docs: improve welcome page introduction.

Jamie: How do I know I actually succeeded after pushing?

Alex: Go to the repository on GitHub.com. You may see a banner saying your branch had recent pushes, with a Compare & pull request button. You should also be able to find your branch in the branch selector and see your commit in that branch's history.

Jamie: And the challenge asks for evidence, not a huge essay.

Alex: Right. In the issue's evidence box, describe the tool you used, the branch name, what file you edited, and your commit message. The automated check is looking for at least one commit on a non-default branch that was pushed from a local tool.

Jamie: Some versions also ask for a peer simulation check, comparing your workflow with a buddy or with the peer-simulation PR notes.

Alex: That's a useful reflection. Maybe your buddy used Desktop while you used VS Code, or they pushed from terminal while you clicked Publish Branch. The interface changed, but the Git workflow stayed recognizable.

Jamie: And to unlock Challenge 11, reply to the issue with a joyful message that you pushed your code, then activate Close issue.

Alex: Yes. Celebrate it. Your computer and GitHub are now talking to each other through Git.

Jamie: Let's talk about getting stuck, because cloning and pushing are the two places where people often feel blocked.

Alex: If cloning fails, first check the URL. Make sure you copied the HTTPS or SSH URL from the Code button for the right repository. If it is a private Learning Room repo, you need access with your own GitHub account; if access is denied, ask a facilitator to confirm the Classroom setup.

Jamie: Authentication errors can sound scary, but they often mean the tool needs you to sign in again or use the right credential method.

Alex: Exactly. The Git authentication appendix is there for that setup. If VS Code seems quiet during clone or push, check notifications; the command Notifications: Focus Notification Toast can bring the progress message into focus.

Jamie: What about push rejected?

Alex: First, confirm you committed. Push sends commits, not just saved files. Then run git status to see what Git thinks is happening. If GitHub has changes you do not have locally, fetch or pull before trying again, and make sure you are on the branch you meant to push.

Jamie: And if Source Control doesn't show anything?

Alex: Make sure you opened the cloned folder as the workspace, not just a single file. Press Ctrl+Shift+G or Cmd+Shift+G, and check that the folder is actually a Git repository. If you're unsure what to edit, choose the smallest helpful change: fix a typo, improve a sentence, or add a short note.

Jamie: There are also safety tools for mistakes, right?

Alex: Yes. If you do not want to keep an uncommitted change, you can discard it, but read the prompt carefully because discard can remove work. If you need to temporarily set work aside, stash is safer. Timeline and Git history help you review past commits, blame shows who last changed each line, and reflog can sometimes recover lost local commits or deleted branches.

Jamie: Reflog is local-only, though. If the work never existed on your machine, reflog won't invent it.

Alex: Correct. And with conflicts, remember that a conflict is not a failure. It means Git found overlapping edits and needs a human decision. VS Code can guide you through choosing, combining, or reviewing those changes before committing the resolution.

Jamie: I like where this challenge lands. It is not asking for a masterpiece edit. It is asking for a complete loop.

Alex: Clone gives you a local copy. Branch protects main. Edit changes a real file. Stage selects what belongs in the snapshot. Commit saves it locally. Push backs it up on GitHub and makes it visible to the project.

Jamie: And once that branch appears on GitHub with your commit, you've crossed an important line. You're not just using GitHub in the browser anymore. You're working like a contributor with local tools.

Transcript

Alex: Welcome back. Today we're doing Bonus E, Git History, and the goal is to read a repository's past instead of only looking at its current files.

Jamie: I like that framing, because history can feel like a wall of mysterious messages. This challenge makes it visual, right?

Alex: Exactly. You'll explore the learning-room repository, which is the per-learner repo where your Day 1 issue, branch, commit, pull request, and merge work happened. The challenge asks you to use GitHub Desktop, or GitHub.com if you prefer, to see commits, branches, and merges over time.

Jamie: And this is one of the bonus challenges that unlocks after Challenge 15, yes?

Alex: Yes. After Challenge 15 unlocks the next path, Bonus Challenges A through E become available as a structured set. You can choose this one without waiting for Challenge 16, and Challenge 16 itself is the Capstone Project.

Jamie: Before we open a history view, I want the Git model in my head. What am I actually looking at when I see all those commits?

Alex: You're looking at saved snapshots. When you work locally, Git separates your project into the working directory, the staging area, and the repository. The working directory is the folder you edit, the staging area is where you choose what will go into the next commit, and the repository is the saved record in the hidden .git folder.

Jamie: So a commit is not just a note that says something changed. It is a saved point in the project.

Alex: Right. A commit records the snapshot, a message, the author, and a pointer to the commit that came before it. It also gets a unique ID called a SHA hash, usually shown as a short seven-character version like a1b2c3d. You do not need to memorize hashes, but they are useful when you want to identify one exact moment.

Jamie: Where do branches fit into that?

Alex: A branch is a movable name that points to a commit. The default branch is often main, and your learning branch may be named something like learn/YOUR-USERNAME. HEAD is Git's way of saying which branch or commit you are currently on.

Jamie: And local versus remote is the two-copy part: one copy on my computer, one copy on GitHub.

Alex: Yes. Push sends your local commits to GitHub. Pull brings remote updates down and merges them into your current branch. Fetch checks what changed on the remote without merging, which is useful when you just want to update what your tools know before reading history.

Jamie: Now the timeline view makes more sense. It is not just decoration. It is showing how snapshots connect.

Alex: That's the core of this challenge. A straight line of commits shows one path through time. A branch creates another path, and a merge brings paths back together. In a visual graph, those paths may appear as parallel lines that split and reconnect.

Jamie: The challenge asks some very specific observation questions, too.

Alex: It does. You're asked to find how many branches exist right now, locate your Challenge 5 commit, see where your learn/YOUR-USERNAME branch diverges from main, find the merge commit from your Challenge 9 pull request, and identify the oldest commit in the repository.

Jamie: That oldest commit is often the one that created the starting project structure, sometimes called the initial commit.

Alex: Exactly. And the merge commit is interesting because it usually has two parent commits. That means it connects two lines of work: the main line and the branch that was merged.

Jamie: Let's start with GitHub Desktop, because the challenge is really built around that visual timeline.

Alex: Open GitHub Desktop and choose the learning-room repository. If it is not already visible, use the repository picker to find it. Then open the History tab, where the left side lists commits and the right side shows details for the commit you selected.

Jamie: What should I listen for or look for once I'm in that tab?

Alex: Move through the commits and pay attention to the message, author, date, and changed files. Click or select a commit to inspect the diff, which is the set of lines added, removed, or modified. Some commits will be yours, and some may be seeded peer-simulation commits that make the repository history more realistic.

Jamie: What if GitHub Desktop does not show all the branches I expect?

Alex: Fetch from the remote first. In GitHub Desktop, use Repository, then Fetch origin. That updates Desktop's knowledge of remote branches without forcing you to merge anything into your current work.

Jamie: So after fetching, I can compare what I remember doing with what the timeline actually records.

Alex: Yes. Look for your Challenge 5 commit message, then look for the branch line that contains it. Then look for where that branch separates from main and where your Challenge 9 pull request came back in as a merge.

Jamie: If someone does not want to use Desktop, GitHub.com gives them another path.

Alex: It does. In the learning-room repository on GitHub.com, the Code tab usually has a commits link near the top showing the number of commits. Open that to see the linear commit history, with the most recent commits first.

Jamie: That page includes the author, date, message, and SHA for each commit, right?

Alex: Yes. Select a commit and GitHub shows the diff. Visually, added lines are commonly shown in green and removed lines in red, and the text diff still carries the actual line changes for assistive technology to read.

Jamie: And the branch graph is under Insights, then Network.

Alex: Correct. The Network graph can show branches as lines that diverge and merge, but it can be busy in repositories with several contributors or simulation commits. If it is hard to read, narrow your attention to a date range, search commit history for your username, or use the branch filter where available.

Jamie: So GitHub.com gives me both a simple list and a more graph-like view.

Alex: That's a good way to say it. The commits page is easier for reading one commit at a time. The Network graph is better for seeing how branches relate.

Jamie: Where does VS Code fit into this challenge? It is mentioned as another history tool, but not quite the same as Desktop.

Alex: VS Code's Timeline view is file-focused. In the Explorer sidebar, you can open Timeline for the current file, and it shows commits that changed that file. That is excellent when you want to know how one document evolved.

Jamie: So if I open a README, the Timeline view is not necessarily showing the whole repository's story.

Alex: Right. It is a narrower lens. For the bonus evidence, GitHub Desktop or GitHub.com is better for branches and merges, while VS Code Timeline is great for answering, who changed this file, when, and why.

Jamie: That also helps when a file suddenly looks unfamiliar. I can inspect its history instead of assuming I broke something.

Alex: Exactly. And if you use VS Code Source Control, files are grouped so you can tell what is changed, what is staged, and what is ready to commit. Running git status in the terminal gives the same kind of orientation in text.

Jamie: This bonus also connects to the advanced Git appendix, because a lot of advanced commands start with reading history carefully.

Alex: They do. Cherry-pick, for example, begins by finding the SHA for one specific commit, then applying that commit to your current branch. You might find the SHA in VS Code Timeline, with git log branch-name --oneline, or through a GitHub API query with gh, then run git cherry-pick a1b2c3d.

Jamie: And if cherry-pick runs into a conflict, it pauses like a merge conflict.

Alex: Yes. You resolve the marked files, stage them, and run git cherry-pick --continue. If you decide this was the wrong move, git cherry-pick --abort returns you to where you started.

Jamie: Interactive rebase is another history tool, but it sounds more powerful and more dangerous.

Alex: It rewrites commits, so use it with care. With git rebase -i HEAD~3, you can edit the last three commits: keep them, squash them together, reword messages, drop one, or pause to amend one. It is best for commits that have not been pushed to a shared branch.

Jamie: That explains why history is not just something you read after the fact. Sometimes you clean it up before asking people to review your pull request.

Alex: Exactly. A tidy history can make review easier, but safety comes first. If you get into trouble during a rebase, git rebase --abort is the escape hatch, and git status will usually tell you what Git is waiting for.

Jamie: Undo commands are where I always want extra caution. Reset and revert sound similar, but they are not the same.

Alex: Good instinct. git reset moves where your branch points and can keep changes staged, keep them unstaged, or discard them depending on the mode. git revert is safer for shared branches because it creates a new commit that undoes an older commit, leaving the existing history intact.

Jamie: Tags are history markers too, right? Like naming an important release point.

Alex: Yes. A lightweight tag is a simple name for a commit, and an annotated tag includes extra metadata and is commonly recommended for releases. You can create tags in Git, push them to GitHub, list them, show details, or delete local and remote tags when needed.

Jamie: What about detached HEAD? That phrase sounds worse than it is.

Alex: It means you are looking directly at a commit instead of being on a branch. If you only meant to inspect history, switch back to your branch. If you made commits there and want to keep them, create a new branch at that point so the work has a name.

Jamie: And force pushing is the one where the appendix says to prefer --force-with-lease over plain --force.

Alex: Right. --force-with-lease checks whether someone else pushed since your last fetch, and it fails instead of overwriting their work. A common flow is rebase your feature branch onto main, resolve conflicts, continue the rebase, then push with --force-with-lease because the remote branch still has the old commit shape.

Jamie: Branch protection can block that kind of direct push or merge too.

Alex: Yes. Protected branches may require pull requests, reviews, passing checks, or up-to-date branches. The reliable flow is to work on a branch, commit, push that branch, open a pull request, wait for review and checks, and merge through the pull request when the rules are satisfied.

Jamie: Two more advanced tools are very history-centered: bisect and clean.

Alex: git bisect helps find the commit that introduced a bug. You mark the current commit as bad, mark an older known-good commit, and Git checks points in between until it narrows down the first bad commit. You can do it manually or have Git run a test script at each step, then finish with git bisect reset.

Jamie: git clean is less about commit history and more about clearing untracked files, but it can affect your working folder fast.

Alex: Exactly, so dry-run first. git clean -n shows what would be removed, while -f actually removes files, -d includes directories, -x includes ignored files, and -i lets you confirm interactively. If you are unsure, do not jump straight to deletion.

Jamie: The appendix also mentions using GitHub Copilot for Git operations, not as a substitute for understanding, but as help with confusing output.

Alex: Yes. You can paste git status, git log, git show, a conflict message, or a branch protection error into Copilot Chat and ask what it means. Copilot can also help draft clearer commit messages or suggest which Git command matches the result you want, but you still verify before running anything that rewrites or deletes work.

Jamie: If a learner gets stuck during this bonus, what are the simple recovery moves?

Alex: If Desktop looks incomplete, fetch origin. If the Network graph is overwhelming, use the commits list instead or focus on a smaller time period. If you cannot find your own work, search for your username, your branch name, or a commit message you remember.

Jamie: And the evidence box is not asking for a perfect diagram. It is asking what they discovered.

Alex: Right. Include the tool you used, the number of branches you found, your Challenge 5 commit, where your learning branch diverged from main if you could identify it, the Challenge 9 merge commit if you found it, the oldest commit, and one surprising thing you noticed. If you explored at least one commit diff and can explain what the history tells you about the project, you have done the work of this bonus.

Jamie: I like that because it turns Git history into a study tool. You can learn from the path the project took, not only from the final file state.

Alex: Exactly. Git history is a navigable record of change: who changed what, when it changed, and how separate lines of work came back together. Once you can read that record, advanced Git becomes much less mysterious.

Transcript

Alex: Welcome back. Today we're staying in VS Code and bringing pull requests into the editor with the GitHub Pull Requests and Issues extension.

Jamie: This is the one that lets you look at PRs, read diffs, comment, and even merge without constantly jumping back to the browser, right?

Alex: Exactly. A pull request, or PR, is the conversation around a proposed change. The extension gives that conversation a home inside VS Code, right beside your files, source control, and terminal.

Jamie: That sounds especially useful on Day 2, because learners are no longer only clicking through GitHub.com. They are pushing branches from VS Code and then trying to understand what changed.

Alex: Yes. On Day 1, your Learning Room repository gave you the web workflow: issue, branch, commit, pull request, merge. This workflow maps those same ideas into the editor, so when Challenge 11 asks you to open a Day 2 PR from a locally pushed branch, the pieces already feel familiar.

Jamie: Before anyone reviews anything, they need the extension installed. What should they have open?

Alex: Open VS Code desktop with your Learning Room repository loaded. Then open the Extensions sidebar with `Ctrl+Shift+X`, or `Cmd+Shift+X` on Mac, search for `GitHub Pull Requests`, choose the GitHub-published extension, and activate Install.

Jamie: And if someone prefers commands over sidebars, they can use the Command Palette?

Alex: Yes. Open it with `Ctrl+Shift+P`, or `Cmd+Shift+P` on Mac, and run the command to install extensions, then search from there. After installation, VS Code usually prompts you to sign in to GitHub, opens a browser for authorization, and then returns you to VS Code.

Jamie: How do I know the sign-in worked? Because OAuth windows can feel a little mysterious.

Alex: Open the Explorer sidebar with `Ctrl+Shift+E`. You should see a GitHub section with Pull Requests and Issues. If an install or sign-in notification disappeared too quickly, run `Notifications: Focus Notification Toast` from the Command Palette and listen for the message.

Jamie: Once the extension is ready, where do pull requests actually show up?

Alex: You have a couple of routes. You can use the GitHub icon in the Activity Bar, or run `GitHub Pull Requests: Focus on Pull Requests View` from the Command Palette. You can also find a GitHub section inside Explorer, which is handy if you already live in the file tree.

Jamie: And the list is not just one giant pile of every PR on GitHub, I hope.

Alex: No, it is organized. You can see PRs assigned to you, PRs you created, open PRs, and PRs waiting for your review. The tree usually groups by repository and status, and a screen reader may announce something like pull request number, title, author, branch, and review state.

Jamie: If I open one from the list, what am I reading first?

Alex: Usually the PR detail view: title, description, status, checks, reviewers, comments, and changed files. If you want the browser version, open the PR on GitHub.com and use the Conversation and Files changed tabs. If you want the terminal version, `gh pr list`, `gh pr view`, and `gh pr status` cover the same basic orientation.

Jamie: Reading a PR is one thing. Checking it out sounds more serious. Why would I do that?

Alex: Checking out a PR means VS Code switches your working copy to the branch from that pull request. That lets you run the code, test the docs locally, or inspect files with all your usual editor tools instead of only reading the web diff.

Jamie: So in Challenge 12, when I review a classmate's PR, checking it out helps me verify what they changed instead of only reacting to the summary.

Alex: Right. From the PR detail view, activate Checkout. From the PR tree, open the context menu with `Shift+F10` on Windows, or `Ctrl+Return` on Mac, and choose Checkout. You can also use the Command Palette if you remember the extension command better than the panel layout.

Jamie: And when I am done, I should get back to my own branch.

Alex: Yes. Use the branch control in the status bar, the Source Control panel with `Ctrl+Shift+G`, or Git commands to return to your original branch. The web fallback is to stay on GitHub.com and review read-only. The terminal version is `gh pr checkout` for a local checkout, and `gh pr diff` if you only want to inspect changes without switching branches.

Alex: The heart of review is the diff, which is the before-and-after view of the files changed by a PR.

Jamie: Diffs are where I see added lines, removed lines, and whether the change matches what the author claimed.

Alex: Exactly. In VS Code, open the PR, then open the changed files list. A file may open in the Diff Editor, often with old content on the left and new content on the right. You can switch between split view and inline view if one is easier to read.

Jamie: For screen reader users, the visual layout is not always the easiest way to understand the change.

Alex: That is where the Accessible Diff Viewer helps. Press `F7` to move to the next change and `Shift+F7` to move to the previous change. It reads a change as a structured block, such as removed line, added line, and surrounding context, which is usually much clearer than wandering through each visual column.

Jamie: So the review habit is: read the PR description, read the changed files, use `F7` through the diff, and notice one specific thing worth saying.

Alex: Yes. It might be a typo, an unclear instruction, a missing setup step, a heading hierarchy issue, link text that needs improvement, or something the author handled well. Specific comments are useful; vague approval is rarely enough by itself.

Alex: Creating a PR from VS Code is the author side of the same loop.

Jamie: This is where Challenge 11 fits, right? I make changes on a local branch, push that branch, and then open a Day 2 PR.

Alex: Yes. You need a repository connected to GitHub, a branch with commits, and usually that branch pushed to the remote. Then run `GitHub Pull Requests: Create Pull Request` from the Command Palette, or start from Source Control, or use the GitHub panel.

Jamie: The two branch fields always trip people up. Base branch and compare branch sound similar.

Alex: The base branch is the target, often `main`, where you want the change to land. The compare branch is your source branch, the one containing your commits. If those are reversed, the PR will look confusing, so pause and confirm them before creating it.

Jamie: Then I write the title and description in VS Code too?

Alex: Yes. The title is required. The description is optional in the tool, but recommended in real collaboration. If the repo has a PR template, often stored in `.github/pull_request_template.md` or a related template folder, fill it in: description, related issue, type of change, testing, checklist, and screenshots when relevant.

Jamie: And reviewers, labels, milestones, and draft status are optional fields, but they are not random decoration. They tell other people how to treat the PR.

Alex: Right. Draft means not ready for final review. The browser alternative is GitHub.com's New pull request page. The terminal alternative is `gh pr create`, either interactively for prompts or inline with flags for title, body, base, head, and draft.

Jamie: Let's talk about comments, because this is where review can either help someone or make them feel shut down.

Alex: A good inline comment attaches to a specific line and explains what you noticed. In VS Code, put your cursor on the line, run `GitHub Pull Requests: Add Comment`, write the comment, and add it. If that is difficult, open the PR in the browser and comment from the Files changed tab.

Jamie: What if I have several comments and do not want to send them one at a time?

Alex: Use Start Review when it is available. That lets you collect comments, then submit them together with a review verdict. Your verdict can be Approve, Request changes, or Comment. Approve means you believe it is ready, Request changes means something should be fixed before merge, and Comment means you are giving feedback without a blocking decision.

Jamie: I like prefixes for tone too: blocking, suggestion, question, nit. They tell the author whether I am stopping the PR or just offering a small improvement.

Alex: Exactly. The web path is Files changed, add inline comments, then Review changes. The terminal path is `gh pr review --approve`, `gh pr review --request-changes`, or `gh pr review --comment`, and `gh pr diff` helps you inspect before deciding. Challenge 12 is really about this: leave specific feedback and own the tone of your review.

Alex: Merging is the moment when the accepted change becomes part of the target branch.

Jamie: So I should not merge just because the button is there.

Alex: Correct. Check that you have permission, the PR is review-ready, required checks have passed, conflicts are resolved, and the team agrees it should land. In VS Code, the merge action appears in the PR detail view when you have access. You can also run a merge command from the Command Palette.

Jamie: There are different merge types too, right?

Alex: Yes. A regular merge keeps the branch history. Squash and merge combines the PR into one commit, which many documentation projects prefer for a tidy history. Rebase and merge replays commits on top of the base branch. Use the repository's norm, not personal preference in the moment.

Jamie: After merging, I still need to clean up my local view of the world.

Alex: Switch back to `main`, pull the latest changes, and delete the feature branch if the project expects that. On GitHub.com, use the merge button and then delete the branch if offered. With the CLI, use commands such as `gh pr merge`, `gh pr merge --squash --delete-branch`, or auto-merge options when checks must pass first.

Alex: A few problems come up often enough that they are worth recognizing by sound and pattern.

Jamie: First one: the panel says there are no pull requests. That can feel like the extension is broken.

Alex: Usually it is a filter or repository issue. Switch to an All Open view, confirm the right repository is open, and make sure you are signed in with the account that can see the PRs. If the extension seems stuck, reload the window with `Developer: Reload Window` from the Command Palette.

Jamie: What about could not create pull request or authentication failed?

Alex: For PR creation, confirm your branch has commits, the branch is pushed, and the base and compare branches make sense. For authentication, sign in to GitHub in the browser first, close and reopen VS Code, then retry the extension sign-in. If checkout is blocked by permissions, use GitHub.com in read-only mode and still leave your review comment there.

Jamie: And if the diff or comment command is the hard part, use `F7`, search the Command Palette for `GitHub Pull Requests: Add Comment`, or ask a facilitator to model one comment.

Alex: For the chapter evidence, post a completion comment in your assigned setup or review practice issue. Include whether the extension is installed, whether you are signed in, which classmate PR you reviewed, whether the comment was inline or on GitHub.com, and a one-sentence summary of what your comment addressed. There is no automation check here because extension state lives in your account and your local VS Code setup.

Alex: The deeper skill is review judgment, not just button finding.

Jamie: So when I review, I am asking: does the PR do what it says, is the change understandable, does it create an accessibility problem, and can another person maintain it later?

Alex: Yes. Useful review comments include the issue, the reason it matters, and a possible next action. For example, a blocking comment might say that a heading skips from level two to level four and ask the author to preserve the hierarchy. A non-blocking nit might suggest clearer link text without delaying the merge.

Jamie: How many comments is too many?

Alex: If every line gets a comment, the author may not know what matters. Group repeated issues, mark small preferences as nits, and save bigger patterns for the review summary. Review is also a learning tool: explaining what you noticed sharpens your own standards.

Jamie: Where does Copilot fit into this without replacing the reviewer?

Alex: Use it to help understand unfamiliar code or summarize a diff, but do not outsource the decision. It can miss context, invent certainty, or overlook accessibility impact. The Accessibility Agents collection is a living catalog that can support review work over time, but the human reviewer still owns the judgment.

Alex: The same PR workflow now has three doors: VS Code, GitHub.com, and the `gh` CLI.

Jamie: And they line up pretty cleanly. View with the PR panel, the browser tabs, or `gh pr view`. Create with the VS Code command, the web form, or `gh pr create`. Review with inline comments and verdicts in the editor, on GitHub.com, or through `gh pr review`. Merge in the PR detail view, with the web button, or with `gh pr merge`.

Alex: That is why this episode pairs so naturally with Challenge 11, Challenge 12, and bonus-c. Challenge 11 gets your own branch into a PR. Challenge 12 has you review a classmate with clear, constructive feedback. Bonus-c adds the team layer: divide the work, communicate what changed, and make the review conversation easier for everyone.

Jamie: So the takeaway is not that everyone must abandon the browser. It is that you can choose the environment that keeps you oriented, verify the change with accessible tools, and leave feedback that helps the project move forward.

Transcript

Alex: Welcome back. Today we're talking about accessible code review: reading pull requests, understanding diffs, and leaving feedback that actually helps.

Jamie: This is one of those skills that can feel intimidating, because you're not just reading code. You're reacting to someone else's work, in public, with a record attached.

Alex: Exactly. But code review is one of the best places to learn. You see how other people solve problems, you catch mistakes before they merge, and you practice explaining what makes code or documentation clearer.

Jamie: So review is not only a gatekeeping step. It's a learning step, a quality step, and a collaboration step.

Alex: There are two main places you'll review pull requests in this course: GitHub.com in the browser, and VS Code with the GitHub Pull Requests and Issues extension. There's also a third path through the gh command line tool, which is useful when you prefer the terminal.

Jamie: And these connect directly to the Day 2 challenges, right?

Alex: They do. Challenge 11 asks you to open a Day 2 pull request from a locally pushed branch and read it in VS Code. Challenge 12 asks you to review a classmate's PR, leave specific feedback, and take responsibility for your review tone. Bonus Challenge C builds on that with a small-group contribution, where division of work and communication matter just as much as commits.

Jamie: Before doing that, learners should already know the basics of pull requests, have their Learning Room repository available, and have some comfort with Git and source control in VS Code. The written chapter also has short command cards, so you don't have to memorize every menu path.

Alex: Let's start with the VS Code setup. Open the Extensions sidebar with Ctrl+Shift+X, or Cmd+Shift+X on Mac. Search for GitHub Pull Requests, choose the extension published by GitHub, and install it.

Jamie: Then VS Code asks you to sign in to GitHub, usually through a browser authorization screen. After approving it, you return to VS Code.

Alex: To verify it worked, open the Explorer sidebar with Ctrl+Shift+E, or Cmd+Shift+E on Mac. You should see a GitHub section that includes Pull Requests and Issues. The extension also adds PR views, checkout commands, changed-file views, inline comments, review submission, and merge actions.

Jamie: And if a notification disappears before a screen reader catches it, use the Command Palette and run Notifications: Focus Notification Toast. That's a small rescue move that can save a lot of confusion.

Alex: If the extension will not install, reload the VS Code window. If sign-in fails, make sure you're signed in to GitHub in the browser, restart VS Code, and try again. If the PR list is empty, switch the PR panel to an all-open view or check that you're in the right repository.

Alex: Once the extension is installed, you can find pull requests from the GitHub icon in the Activity Bar or from the GitHub section in Explorer. You can list open PRs, filter by status, filter by repository, find items waiting for your review, and open a PR in the browser when that is easier.

Jamie: What does that feel like with a screen reader?

Alex: The PR tree usually announces enough context to orient you, something like pull request number, title, author, status, and repository. When you open a PR detail view, you can move through the description, checks, changed files, comments, and available actions.

Jamie: And checking out a PR means downloading that branch locally, yes?

Alex: Yes. You do that when you want to run the project, inspect files in your editor, or test a change more closely. You can check out from the PR detail view, from the PR tree context menu, or through the Command Palette. When you're done, switch back to your original branch, often main, and pull the latest changes if needed.

Jamie: If checkout is blocked because you don't have permission, that doesn't stop the review. You can stay in read-only mode and review on GitHub.com instead.

Alex: Now let's make diffs less mysterious. A diff is a comparison between two versions of a file. In a unified diff, added lines usually start with a plus sign, deleted lines start with a minus sign, and unchanged context lines appear around them so you know where the change sits.

Jamie: So if I hear plus heading, that line was added. If I hear minus paragraph, that line was removed. And context lines are there to help me understand the neighborhood.

Alex: Right. On GitHub.com, open the pull request, read the description first, then move to the Files changed tab. The modern pull request interface is the default, and the file tree can help you orient by file name, folder, and change count.

Jamie: How do I move around without losing my place?

Alex: Use the file tree, headings, and controls inside the Files changed view. GitHub also has a keyboard shortcuts dialog, opened with the question mark key, where you can confirm the current shortcuts for moving through files and review items. Because shortcuts can change or depend on focus, I like to verify them there before relying on them.

Jamie: And inline comments live on specific lines in the diff.

Alex: Yes. Move to the line you want, open the line comment control, and write the comment there. If you need to comment on several adjacent lines, use the multi-line comment option. When you have more than one comment to leave, choose Start review so you can collect comments before submitting them together.

Jamie: Existing comments matter too. A thread might already explain why something changed, or show that another reviewer asked the same question.

Alex: When you're ready, submit the review with one of three verdicts: approve, request changes, or comment only. Approve means you're comfortable with the PR merging. Request changes means something should be fixed before merge. Comment only means you're leaving feedback without a formal yes or no. If you're the author and you've pushed updates, you can re-request review so reviewers know it's ready for another look.

Alex: VS Code gives you another review path. From the PR view, open the changed files list, then open a file to see the diff. By default, VS Code often uses a split diff, with old content on one side and new content on the other.

Jamie: Split view can be visually helpful, but it can also be noisy with a screen reader.

Alex: That's where the Accessible Diff Viewer matters. Press F7 to move to the next change, and Shift+F7 to move to the previous change. It announces each change as a structured item, including added lines and removed lines, so you don't have to piece together the visual layout manually.

Jamie: So instead of arrowing through a complicated editor and wondering what side I'm on, I get the change read as a meaningful block.

Alex: Exactly. You can also toggle diff views, such as split or inline, if one works better for you. But for screen reader review, F7 is usually the most reliable starting point.

Jamie: And comments from VS Code?

Alex: Place the cursor on the line you want to discuss, open the Command Palette, and run GitHub Pull Requests: Add Comment. Type the comment and add it. If that command is hard to locate or the line placement feels uncertain, open the same PR on GitHub.com and use the Files changed tab there.

Alex: Challenge 11 also asks you to create a pull request from your local branch. In VS Code, the recommended route is the Command Palette command for creating a pull request, though you can also start from Source Control or the GitHub panel.

Jamie: The PR form has a lot of fields. Which ones should people pay attention to first?

Alex: The title is required, and it should describe the change clearly. The description is optional in GitHub, but it's strongly recommended because reviewers need context. You also confirm the base branch, which is the target, and the compare branch, which is your source branch. Reviewers, labels, milestone, and draft status are optional, but they can help a team coordinate.

Jamie: Draft status is useful when the PR is not ready for final review yet.

Alex: Yes. And many repositories use pull request templates. Those are usually stored in the .github folder, either as a single pull_request_template.md file or as files inside a PULL_REQUEST_TEMPLATE folder. A good template may ask for a description, related issue, type of change, testing notes, a checklist, and screenshots when they apply.

Jamie: With a screen reader, I like treating the template as a form inside the description box. Move through each prompt, answer it in place, and don't leave reviewers guessing.

Alex: You can submit through the interactive prompts, provide details inline, create the PR as a draft, or open the form in your browser. The goal is the same: make the change understandable before anyone starts reviewing the diff.

Alex: A helpful review comment is specific, kind, and actionable. It points to the exact problem, explains why it matters, and suggests a possible improvement when you can.

Jamie: So not just, "This is confusing." More like, "This step says press Enter, but the previous sentence says the focus is still in the search box. Could we add a sentence telling the reader to move to the result first?"

Alex: Perfect. Some comments are blocking, meaning the PR should change before merge. Some are non-blocking nits, like a wording polish. Some are questions, and some are praise. Prefixes like blocking, suggestion, nit, question, and praise can help the author understand your intent.

Jamie: How many comments is too many?

Alex: Prioritize. If there are ten tiny style issues and one accessibility barrier, lead with the accessibility barrier. In Challenge 12, the aim is not to prove you found everything. It's to leave feedback a classmate can use, in a tone you'd be comfortable receiving.

Jamie: And after the review is submitted, the author can reply, push commits, and resolve threads.

Alex: Right. Common review tasks include checking whether the PR only changes what it claims, searching for all changes to one section, comparing new commits after the author updates the branch, and asking for clarification when another reviewer's comment is unclear. Good reviewers keep the conversation moving.

Alex: Merging is a separate permission and responsibility. Before merging, make sure the review expectations are met, required checks have passed, conflicts are resolved, and the repository's rules allow you to merge.

Jamie: And there are different merge styles.

Alex: A normal merge keeps the branch commits as they are. Squash and merge combines the PR into one commit, which can keep history tidy. Some repositories enable auto-merge, which merges after required checks pass. After merging, switch back to main, pull the latest changes, and delete the feature branch if the project expects that cleanup.

Jamie: So reviewers may recommend merge readiness, but maintainers often decide the actual merge method.

Alex: The gh CLI is the terminal path. It can be especially nice if terminal output is easier for you to search, copy, or review line by line.

Jamie: What are the core commands?

Alex: Use gh pr view to read the PR description, status, checks, and comments. Use gh pr diff to view the full diff in the terminal. Use gh pr checkout to test the branch locally. And use gh pr review with options like --approve, --request-changes, or --comment, usually with a body message that explains your review.

Jamie: I like that it gives another accessible route. Browser, editor, terminal: same review, different workspace.

Alex: Copilot can help during review, but it should not replace your judgment. In VS Code, with a diff open, you can ask it to summarize what changed, identify possible risks, or suggest test cases.

Jamie: But it can miss context, misunderstand intent, or sound confident about something wrong.

Alex: Exactly. Use it to support your reading, then verify against the actual diff, the PR description, and the project standards. The human reviewer still owns the comment and the verdict.

Alex: The practice work gives you both environments. In the web review exercise, you navigate to a PR, read the description, open Files changed, use focus mode if it helps, find an accessibility issue such as heading hierarchy, find a link text issue, place inline comments, and submit the review.

Jamie: Then the VS Code exercise has you open the PR extension, view file changes, use the Accessible Diff Viewer, listen to the first change, locate the issue, add an inline comment, and reflect on what was easier or harder.

Alex: For evidence, Chapter 15 Part 1 asks for a completion comment confirming the extension installation, GitHub sign-in, the classmate PR number, whether a comment was posted, and what the comment was about. Challenge 12 asks you to show that you reviewed a PR, left inline feedback, and submitted a formal review verdict. Close the assigned Challenge 12 issue when your room instructions say the work is complete.

Jamie: If something breaks, there are practical fallbacks. Reload VS Code, retry GitHub sign-in, switch the PR panel to all open PRs, use GitHub.com if checkout fails, use F7 if the diff editor is hard to navigate, or ask a facilitator to model one review comment.

Alex: The longer-term habit is to review other people's work regularly. Look for correctness, clarity, style, and accessibility. In team work, especially Bonus Challenge C, review becomes part of communication: who changed what, who tested what, and what still needs attention. The Accessibility Agents collection is a living catalog, and some agents can help with review workflows, but the skill comes first: learn to read the change, judge the impact, and respond clearly.

Jamie: That's a strong place to land. A good review does not have to be loud or exhaustive. It has to be specific, respectful, and useful enough that the next commit gets better.

Transcript

Alex: Welcome back. Challenge 11 is called Open a Day 2 PR, and this is the moment your local Git work becomes a GitHub conversation.

Jamie: So we already did the local part in Challenge 10: clone, branch, edit, stage, commit, and push. Now we are proposing that branch for review.

Alex: Exactly. Your commits started on your machine, but a pull request lives on GitHub. A pull request, or PR, is the place where you describe the change, compare it against `main`, let checks run, and invite review.

Jamie: And if someone joined Day 2 without Day 1, this is still doable as long as they have the GitHub basics and have completed the Day 2 Quick Start readiness check.

Alex: The pattern is familiar from Day 1, but the route is different. Day 1 was edit on GitHub.com, commit, open a PR. Day 2 is edit locally, commit locally, push to GitHub, then open a PR.

Jamie: That helps. The PR step did not become a whole new skill. The commits just came from a different place.

Alex: Right. Git is moving your work between locations: your working folder, your local repository history, and GitHub. Once the branch is on GitHub, the PR creation step feels very much like the browser workflow you already practiced.

Jamie: So if I am nervous, I should not treat this as a brand-new mountain. It is the same review doorway, with one extra push step before it.

Alex: Before opening the PR, confirm that your branch really made it to GitHub. In VS Code, the Source Control panel should be clean after your commit and push, meaning no staged or unstaged changes are waiting.

Jamie: And if I like the terminal, I can check the same thing with `git status`, right?

Alex: Yes. `git status` tells you whether your working tree is clean and whether your branch is ahead of or behind GitHub. `git branch --show-current` tells you which branch you are on, and `git fetch` followed by `git status` helps confirm that your local view is up to date before you push or open the PR.

Jamie: What branch name should people expect?

Alex: Use the branch your challenge issue assigned. In some Day 2 materials you will see examples like `fix/YOUR-USERNAME`, `learn/<username>`, or `feature/day2-local-edit`. The important part is not the exact example name. It is that your compare branch is the branch with your Day 2 commit, and your base branch is usually `main`.

Jamie: That also explains the VS Code pieces from the Git practice chapter: branch name in the status bar, changed files in Source Control, staged changes, commit message, and push status.

Alex: Yes, and there are safety tools around that workflow. Timeline helps you inspect file history. Stash can set unfinished work aside without deleting it. Discard is for throwing away changes, so use it carefully. If a merge conflict appears, VS Code can show conflict choices, and if you truly lose track of a local commit, `git reflog` can help you find recent local history.

Jamie: Good to know, but for this challenge we are hoping for the calm version: one branch, at least one commit, pushed to GitHub, ready for a PR.

Alex: The quickest browser path is the notification banner. Go to the assigned repository on GitHub.com, such as the sci-fi themes repository if that is what your challenge uses. If GitHub notices your recent push, it may show a banner with a Compare & pull request button.

Jamie: That banner is a shortcut, not a requirement. If I hear it or see it, I can use it and skip the manual compare setup.

Alex: Exactly. If there is no banner, open the Pull requests tab, choose New pull request, set base to `main`, and set compare to your Day 2 branch. Then choose Create pull request to reach the form.

Jamie: The base is where I want the change to land. The compare branch is where my change currently lives.

Alex: You can also create the PR inside VS Code if the GitHub Pull Requests and Issues extension is installed and you are signed in. Open the GitHub Pull Requests view from the Activity Bar, or use the Command Palette with `Ctrl+Shift+P`, or `Cmd+Shift+P` on Mac.

Jamie: Then I run GitHub Pull Requests: Create Pull Request?

Alex: Yes. You can run that command, or select the Create Pull Request button in the Pull Requests view. Choose your compare branch, choose `main` as the base branch, enter a clear title, add a short description, and activate Create.

Jamie: And the extension is useful beyond creating PRs. It can list PRs, show details, open changed files, and let me work with reviews without constantly switching back to the browser.

Alex: If you use GitHub CLI, the command is `gh pr create`. It opens an interactive PR creator in the terminal.

Jamie: Interactive means it asks me questions instead of making me remember every option.

Alex: Right. Give the PR a clear title, choose to write the body in your editor if that is comfortable, summarize what changed, and when it asks what is next, choose Submit. You can also use inline options later, but the guided prompts are a solid starting point.

Jamie: So the three doors are browser, VS Code, and `gh pr create`. They all lead to the same PR on GitHub.

Alex: Now slow down for the title and description. A title like `docs: improve README wording` tells reviewers the type of change and the area touched.

Jamie: That is much better than `updates` or `stuff fixed`, which makes everyone open the diff just to learn the basics.

Alex: For the description, write a few plain sentences. You might include a short Changes area, a How I made these changes area, and a Pattern recognition note. For example: I cloned the repo locally, created a branch, edited in VS Code, committed, pushed, and opened this PR. Compared with Day 1, this started from a local clone, may have more than one commit, and required `git push` before the PR.

Jamie: And if the PR should close an issue, include plain text like `Closes #8`, using the real issue number.

Alex: Yes. The reference solution shows that kind of professional PR: a specific title, a list of changes, a short explanation of how the work was made, and a note about what changed from Day 1. That is the evidence reviewers need to understand your path.

Jamie: It also makes the pattern visible to future you. You are not just submitting a link. You are explaining the workflow you used.

Alex: After the PR exists, read it. In the browser, check the Conversation and Files changed tabs. In VS Code, the GitHub Pull Requests extension can open the PR details and changed files.

Jamie: This is where the code review chapter starts to matter. I am not reviewing someone else yet, but I can still inspect my own PR like a reviewer would.

Alex: Exactly. Read the title and description first, then open the changed files. If the diff editor is hard to follow, use the Accessible Diff Viewer with `F7` for the next change and `Shift+F7` for the previous change. It reads changes in chunks, which is usually easier than moving line by line through a visual diff.

Jamie: The challenge also mentions a peer-simulation check. That means I should look at the sample PR title and description and ask whether they clearly explain what changed. If I have real buddy access, I can review my buddy's PR too.

Alex: Yes. And when you leave review comments later, be specific and constructive. A useful comment points to the issue, explains why it matters, and suggests a next step when possible.

Jamie: That is a good habit even when the change is tiny. The PR is both a code artifact and a communication artifact.

Alex: Once the PR is open, Gandalf should run automated checks and post a validation report in the PR conversation. If Gandalf is quiet, open the Checks tab and see whether the workflow is running, waiting, or failed.

Jamie: What if my branch does not appear in the compare dropdown?

Alex: First, make sure the push completed. From your local tool, you can run `git push -u origin fix/YOUR-USERNAME`, replacing the branch name with yours. If GitHub says there is nothing to compare, your branch may not contain any new commits compared with `main`, so confirm you committed and pushed at least one change.

Jamie: And if I do not know what to write in the description, I can reuse the same shape from the earlier PR challenge: what changed and why.

Alex: To finish Challenge 11, paste the URL of your Day 2 PR into the evidence field. Then describe the pattern you noticed between the Day 1 PR and the Day 2 PR.

Jamie: Something like: Day 1 used the web editor, Day 2 used a local clone and required a push, but both ended with a PR against `main`.

Alex: Perfect. Then activate Close issue when the challenge asks you to. If you created a PR from your locally pushed branch, waited for validation, and explained the workflow pattern, you completed the challenge.

Jamie: That is the real win here: local work did not stay trapped on your machine. You moved it into a reviewable GitHub workflow.

Transcript

Alex: Welcome back. Challenge 12 is Review Like a Pro, and this is where the workshop starts to feel like real collaboration. You are going to review a pull request from a classmate, a peer-simulation PR, or a sample file, and leave feedback that another person could actually use.

Jamie: I like the goal, but review can feel weirdly personal. It is someone else's work, and you are putting your opinion on it in public.

Alex: Exactly, and that is why this challenge is about both code review and open source culture. A good review is not a performance of expertise. It is asking useful questions, noticing what works, suggesting improvements, and assuming the author was trying to do a good job.

Jamie: So the target is not to sound impressive. It is to help the change get better without making the author feel attacked.

Alex: Before you start, make sure you are in the right place. Day 2 work happens in your Learning Room repository, which is provisioned for you, and VS Code is the required editor for the Day 2 local workflow. If you joined Day 2 without Day 1, the quick start guide is there to confirm your account, tools, and GitHub basics before you jump in.

Jamie: And if I do not have a classmate PR ready, I am not stuck, right?

Alex: Right. The challenge gives you options. You can review the peer-simulation PR named Peer Simulation: Improve contribution guidance, you can review a buddy's Day 2 PR if your facilitator gave you access, or you can use docs/code-review-sample.md as the practice material.

Jamie: And the evidence is not mysterious. I need the review URL, a short description of the feedback I gave, and the verdict I chose.

Alex: On GitHub.com, start from the Pull requests tab in the repository. Open the PR you are reviewing, then move to the Files changed tab. Along the top of a pull request you will usually hear or see Conversation, Commits, Files changed, and Checks.

Jamie: Files changed is where the actual review happens, because that is where the diff lives.

Alex: Yes. A diff is the comparison between the old version and the proposed new version. GitHub marks removed lines and added lines, and it also uses red and green visually, but the important thing is the line-level change: what was removed, what was added, and where it happened.

Jamie: What do I do first when I land in that file list?

Alex: Orient yourself before commenting. Read the PR description, use the file tree to hear which files changed, then move through the changed files one at a time. Some learners like Focus Mode in the browser because it reduces noise while reading diffs.

Jamie: Then I place the first inline comment on a specific line, not just at the bottom of the PR.

Alex: Exactly. Focus on a changed line, or hover over it if you use a mouse, and activate the blue plus comment button. For the first comment, make it specific and positive, like: Great, this heading structure makes the section easy to scan.

Jamie: That is much more useful than just saying looks good.

Alex: For the second comment, make a constructive suggestion. You might say that a sentence would be clearer if it used the word beginners instead of new people. If the suggestion button is available, the one with the plus and minus style icon, use it to create a suggestion block so the author can accept the exact text change.

Jamie: That one-click acceptance is a nice accessibility win too. It reduces the amount of retyping and interpretation the author has to do.

Alex: At the end, submit a review verdict. Approve means the changes are ready to merge. Request changes means something must be fixed first. Comment means you have feedback, but you are not blocking the merge.

Jamie: When I am unsure, Comment is the safer choice. It lets me participate without pretending something is blocking.

Alex: That is a strong default for practice reviews. A complete review might say: Nice work. The structure is clear and the content is welcoming. I left one suggestion to improve clarity. If there is a real blocker, name it clearly, such as a missing required field, an insecure http link that should be https, or a heading level that breaks the document structure.

Jamie: So review comments can be praise, questions, suggestions, or required changes. The key is that each one points to something specific.

Alex: You can also do this from VS Code with the GitHub Pull Requests and Issues extension. Install it from the Extensions sidebar with Ctrl+Shift+X, or use the Command Palette with Ctrl+Shift+P and search for the extension. On Mac, use Cmd instead of Ctrl for those shortcuts.

Jamie: After installing, I sign in to GitHub, and then I should see a GitHub section in the Explorer or a Pull Requests view in the Activity Bar.

Alex: Right. From there, find an open PR, preferably one that is not yours, and open it. You can check out the PR branch locally for testing, open the changed files, and read the diff inside VS Code.

Jamie: The diff editor can be a lot through speech, though.

Alex: Use the Accessible Diff Viewer. Press F7 to move to the next change and Shift+F7 to move to the previous change. It reads each change as a structured block, which is usually much easier than arrowing through a visual side-by-side diff.

Jamie: And to comment, I put the cursor on the line, run GitHub Pull Requests: Add Comment from the Command Palette, write the comment, then add it. Ctrl+Enter can submit in some comment boxes.

Alex: When you are done, use Finish Review, the check icon at the top of the PR view. If checkout fails because you do not have permission, stay in read-only mode and open the PR on GitHub.com. The browser path still completes the challenge.

Jamie: What am I actually looking for when I review? I know I should be helpful, but helpful about what?

Alex: Start with whether the change does what the PR description says. Then check whether the commit message is meaningful, whether there are typos or formatting issues, whether a beginner would understand the content, and whether the language and Markdown are accessible. If the PR includes a template, notice whether the title, description, related issue, testing notes, and checklist are filled in well enough to guide the reviewer.

Jamie: How many comments is too many?

Alex: Enough to help, not enough to bury the author. If five comments all point to the same pattern, leave one example and say it happens in a few places. Also set expectations with words like nit, question, suggestion, or blocking, so the author knows how seriously to treat the comment.

Jamie: That also helps with tone. A nit about capitalization should not sound like a security emergency.

Alex: Exactly. Helpful feedback usually starts by acknowledging what is working, identifies the specific concern, explains why it matters, suggests a path forward when you can, and signals the weight of the concern. Talk about the code or the document, not the person. If you are uncertain, use tentative language like: I might be missing something, but...

Jamie: There is also a command line path here, right? Some people like staying in the terminal.

Alex: Yes. With GitHub CLI, gh pr list shows open pull requests, and gh pr diff followed by the PR number shows the changes. For a summary review, you can run gh pr review with the PR number, --comment, and a body message. GitHub CLI can also approve or request changes, and advanced reviewers can add more specific comments, but for this challenge the browser or VS Code path is usually clearer.

Jamie: What about Copilot during review? Is it fair to ask it what changed?

Alex: It can be useful as a reading aid. In VS Code, with a diff open, you can ask Copilot to summarize the change or explain a piece of code you do not understand. But do not outsource judgment. You still verify the diff, check the project norms, and decide what feedback is appropriate.

Alex: After you submit the review, the author sees your comments on the PR. They may reply, make commits, resolve threads, or re-request review after changes. A maintainer handles merging when the project is ready, usually after review and status checks pass.

Jamie: And if I am the author receiving feedback, I should say thanks, ask clarifying questions, explain my choices when needed, and surface blockers early.

Alex: That fits the bigger GitHub Flow pattern: create a branch, make a small focused change, open a pull request, discuss and review, pass checks, then merge. GitHub Flow keeps main deployable and makes the PR the place where the conversation lives. One branch should represent one task, and small PRs get reviewed faster.

Jamie: There are project norms around that conversation too.

Alex: Yes. Read the README, CONTRIBUTING file, Code of Conduct, security policy, and license when they exist. Good first issue labels are an invitation to start small, not a promise that maintainers have unlimited time. Clear commit messages, focused changes, and a PR description that says what changed, why, and how to test it make the review kinder for everyone.

Jamie: And if things get tense?

Alex: Slow down. Public, written, asynchronous communication can make tone hard to read. If you receive harsh feedback, look for the actionable part and ask for clarification. If you disagree, explain the tradeoff respectfully. If someone is rude, follow the project's Code of Conduct. If you caused offense, acknowledge it, apologize briefly, and repair the conversation.

Jamie: Let us talk about the stuck moments, because review interfaces have a lot of little controls.

Alex: If you cannot find the Files changed tab, open the PR first and then look for the tab links near Conversation and Commits. If you cannot leave an inline comment, focus on the line number in the diff and look for the blue plus button. If the suggestion icon is not available, leave the exact replacement text in your comment instead.

Jamie: And if there are no classmate PRs?

Alex: Ask a facilitator for a sample PR or use the peer-simulation PR and docs/code-review-sample.md. If the VS Code extension does not install cleanly, reload the window from the Command Palette. If sign-in fails, confirm you are signed in to GitHub in the browser, restart VS Code, and try again. If the PR list looks empty, switch the Pull Requests view to show all open PRs.

Jamie: Then I paste the review URL into the challenge issue, describe my inline comments, name my verdict, and close the issue when instructed.

Alex: Yes. If you are using the peer simulation, also read any review comments on your own PR, or reply with one thing you learned if you do not have real buddy access. Gandalf celebrates once your review is approved, and Challenge 13 unlocks after you confirm the review and close the issue. The win is not the number of comments. It is one specific, constructive review that helps another contributor move forward.

Transcript

Alex: Welcome back. GitHub Copilot is an AI coding assistant built into the places many of us already work, especially VS Code and GitHub.com.

Jamie: So it is not just autocomplete with a fancy name?

Alex: Right. Autocomplete is one part of it, but Copilot also answers questions, explains code, drafts documentation, suggests tests, helps with commit messages, and can make edits across files when you ask it to. It generates those suggestions from context: the file you are editing, nearby code, the repository workspace, your prompt, and sometimes instructions your project has provided.

Jamie: That context piece feels important. It means Copilot is not reading your mind. It is responding to what it can see and what you tell it.

Alex: Exactly. And in this course, we use it as a reviewed writing partner, not as an authority. Challenge 13, AI as Your Copilot, is where learners practice signing in, asking targeted questions, applying a small change, and reflecting on what Copilot helped with.

Jamie: Before anyone gets excited and opens every AI feature at once, what should be in place?

Alex: You should already be comfortable opening a repository in VS Code and using basic Git workflows from earlier lessons. Copilot access depends on your account, plan, student status, or organization policy. GitHub Copilot Free is available to individual developers with monthly limits, verified students may have student access, and organization or enterprise access can be managed by an administrator. Plans and billing can change, so if you are unsure, check your Copilot settings on GitHub or ask a facilitator before using workshop time.

Jamie: Let's say I have VS Code open with my Learning Room repository. How do I actually turn Copilot on?

Alex: Start with a current stable version of VS Code if you can. Recent VS Code builds include built-in AI features and surface Copilot and Chat directly, so you normally do not need to install a separate Copilot Chat extension. Open the Copilot item in the Status Bar if it appears, choose Use AI Features or Set up Copilot when prompted, and sign in with GitHub through the browser. If your access is tied to GitHub Enterprise, use the enterprise sign-in path and provide the enterprise URL.

Jamie: And how do I know it worked instead of just assuming the sign-in completed?

Alex: Open Copilot Chat with Ctrl+Alt+I, or use the Command Palette and run Chat: Open Chat if the shortcut does not work in your setup. Type something simple like 'Hello, are you working?' and press Enter. If Copilot responds, you have a basic activation check. You can also use the Copilot status item, Copilot settings, or Command Palette commands related to sign-in and status if you need to confirm your account state.

Jamie: What if the controls are missing, or the chat panel refuses to open?

Alex: Update VS Code, reload the window with Developer: Reload Window, and make sure you are signed into GitHub in both the browser and VS Code. If OAuth fails, close VS Code, confirm your GitHub account works in the browser, and try again. If the panel still does not open, use the Command Palette instead of the shortcut, and confirm AI features are enabled. If you see a subscription required message, that is an account access issue, not a Git mistake.

Jamie: The feature people notice first is the faint suggested text that appears while typing. What is happening there?

Alex: Those are inline suggestions, often called ghost text because they appear in the editor before they become real text. Copilot looks at what you are typing, the surrounding file, and nearby project context, then predicts a possible completion. It might offer a few words, one line, or several lines.

Jamie: How do you control it from the keyboard?

Alex: Press Tab to accept the visible suggestion. Press Escape to dismiss it. Press Alt+] to move to the next suggestion when more than one is available. You can also open the full suggestions panel with Ctrl+Enter, and in some setups accept a suggestion word by word with Ctrl+Right Arrow, or Cmd+Right Arrow on Mac, which is useful when you only trust the first part.

Jamie: Ghost text can be tricky with a screen reader. Sometimes I want help, and sometimes I just want the editor to stop talking.

Alex: That is real. NVDA, JAWS, and VoiceOver can interact with Copilot suggestions, but the experience varies by version, settings, and how much Copilot is offering. If a suggestion is long or hard to review, open Accessible View with Alt+F2, or Option+F2 on Mac, so you can read the content in a plain text buffer. If suggestions are too frequent, you can temporarily disable them for the current language, toggle Copilot completions from the Command Palette, or change the Copilot completion setting more permanently in VS Code settings.

Jamie: Can I steer inline suggestions without opening chat?

Alex: Yes. A common move is prompting through comments. You might write a comment such as 'Create a function that validates an email address and returns true or false,' then start the next line and let Copilot suggest code. For this workshop, the same idea works for documentation: write a short comment describing the paragraph, checklist, or settings example you want, then review the suggestion before keeping it.

Jamie: Chat feels less mysterious to me because I can ask a normal question. Is that the main difference?

Alex: Pretty much. Copilot Chat is conversational assistance inside VS Code. Open it with Ctrl+Alt+I or Chat: Open Chat, type in natural language, and ask about code, settings, errors, docs, or a change you are planning. If a shortcut conflicts with your operating system or assistive technology, the Command Palette fallback is the reliable path.

Jamie: I have seen people type things like @workspace and slash commands. Are those magic words?

Alex: They are ways to give Copilot more precise context. @workspace asks Copilot to use the files in your open workspace. @terminal focuses on terminal output, which helps when an error just appeared. @vscode is useful for questions about VS Code features and settings. Slash commands are shortcuts for common tasks: /explain, /fix, /tests, and /doc can ask Copilot to explain code, suggest a fix, generate tests, or draft documentation.

Jamie: And then there are modes and models, which can sound like a lot.

Alex: Keep the choice practical. Ask mode is best when you want an explanation or plan. Edit mode is for applying changes to selected files. Agent mode can take more initiative, including proposing commands, so it needs closer review. The model picker in Chat lets you switch among the models available to your account; names and availability can change, but a quick model is fine for small questions, while a stronger reasoning model may help with complex refactors or careful explanations.

Jamie: What should screen reader users expect in the chat panel itself?

Alex: The panel is a sidebar with conversation history, the response area, model and mode controls, and an input box near the bottom. Responses may stream in, which can be noisy or hard to follow. Use Accessible View with Alt+F2, or Option+F2 on Mac, to read the full answer after it arrives, especially if there is a code block. Built-in actions are also available through the Command Palette, which can be easier than hunting through visual controls.

Jamie: Challenge 13 uses Copilot in a pretty specific way, right? It is not asking learners to build a big app.

Alex: Correct. The pattern is sign in, prompt, apply, reflect. First, you sign in and confirm Copilot Chat responds. Then you clone the sci-fi themes repository, open it in VS Code, and ask Copilot to explain a setting named chat.agent.thinking.phrases.

Jamie: That is a very workshop-flavored setting.

Alex: It is. After Copilot explains it, you ask a follow-up: how to apply one of those themes to settings.json. Then you make the setting change yourself. The goal is not to let AI do hidden work; it is to ask a focused question, read the answer, and apply a small change you understand.

Jamie: And then learners create something new?

Alex: Yes. You ask Copilot to create a custom GitHub Copilot thinking phrases theme for a favorite universe, maybe Star Trek, Dune, Marvel, Studio Ghibli, or something else. Copilot should generate an array of themed phrases. You copy the generated content, open Preferences: Open User Settings (JSON), paste the configuration, save, reload the window, and test it by asking Copilot another question.

Jamie: What counts as completion?

Alex: You post a comment in your assigned Challenge 13 issue with a short checklist: whether Copilot is enabled and signed in, whether you asked it to explain a setting, whether you applied a setting, whether you created a custom theme, and what theme universe you chose. Then close the issue when you are done. There is no automation check here because Copilot setup is local to your account and machine.

Jamie: Chat answers are one thing. What about Copilot Edits, where it actually changes files?

Alex: Copilot Edits is for multi-file changes that you still review. You describe the change, choose or confirm the working set of files, and Copilot proposes edits. Then you inspect the diff before accepting anything. With a screen reader, move through the diff carefully, use VS Code's accessible diff support where it helps, and keep the working set small so the review stays manageable.

Jamie: Agent mode sounds more powerful, and honestly a little easier to misuse.

Alex: That is a fair read. Agent mode can plan work, edit files, and ask to run terminal commands. You approve terminal commands before they run, and you should read them like you would read any command someone handed you in a chat message. Ask mode is for advice, Edit mode is for controlled file changes, and Agent mode is for tasks where you are willing to supervise a more active assistant.

Jamie: Where does the VS Code Agents window fit in?

Alex: In VS Code 1.120 and newer, there is an Agents window you can open from the Command Palette with Chat: Open Agents Window. It can show available agents and related controls. For workshop learners, the safety advice is simple: do not approve commands you do not understand, do not hand an agent broad access just because it asks, and keep your changes reviewable. Accessibility is still improving there, so use keyboard navigation, Accessible View when available, and ask for help if focus gets confusing.

Jamie: And Next Edit Suggestions?

Alex: Next Edit Suggestions try to predict the next place you may want to edit after you make a change. You can turn them on in settings if they are available for your account and VS Code build. They can be helpful during repetitive edits, but they are still suggestions. Accept only what matches your intent.

Jamie: Copilot is also on GitHub.com. Is that the same experience as VS Code?

Alex: It overlaps, but the context is different. On GitHub.com, you can open Copilot Chat from the GitHub interface when it is available to your account. There, it is useful for asking about a specific repository, an issue, a file, a piece of code, or a general coding question while you are already browsing the site.

Jamie: That seems especially useful during pull requests.

Alex: Yes. Copilot can help draft pull request summaries, explain changed code, and assist with code review comments on GitHub.com. In VS Code, it is closer to your editor, terminal, and local files. On GitHub.com, it is closer to issues, pull requests, repository pages, and review workflows.

Jamie: And it is not only for code.

Alex: Not at all. In this course, Copilot is often most useful for non-code contribution work: drafting docs, tightening a commit message, summarizing a change for a pull request, turning notes into a checklist, or making an accessibility report clearer. The human still decides whether the result is accurate, kind, and useful.

Jamie: Prompting is where people can get vague fast. What makes a prompt better?

Alex: A weak prompt is something like 'fix this' with no context. A stronger prompt says what you are working on, what file or audience matters, what format you want, and what constraints to follow. For example: 'Rewrite this README section for first-time contributors. Keep it under 150 words, use plain language, and preserve the commands exactly.' That gives Copilot a job, boundaries, and a way to judge the answer.

Jamie: So the pattern is not one perfect prompt. It is a conversation.

Alex: Yes. Start specific, read the response, then iterate. You can ask for a contextual rewrite, generate text with constraints, review and improve a draft, run an accessibility-focused audit, or draft from an outline. Follow-up prompts are normal: 'make it shorter,' 'keep the tone warmer,' 'add a keyboard-only note,' or 'show me what changed.' VS Code's Timeline view can also help you inspect file history as you experiment.

Jamie: Where do prompt files come in?

Alex: Prompt files are reusable prompts stored in .github/prompts/*.prompt.md. They are useful when a team repeats the same kind of request, such as reviewing docs for accessibility language or drafting release notes. Instead of retyping a long prompt, you keep the prompt in the repo and reuse it.

Jamie: Custom instructions sound similar to prompt files. Are they the same thing?

Alex: They are related, but they work differently. A repo can include .github/copilot-instructions.md to tell Copilot how to behave for that project. Those instructions can cover accessibility standards, documentation style, commit message format, preferred tone, keyboard navigation expectations, and design system rules. You do not have to paste them into every chat; Copilot can apply them as background guidance where the feature supports them.

Jamie: What makes accessibility-focused instructions useful instead of just decorative?

Alex: Make them specific to the team and project. Say which standards matter, which components or design system rules to enforce, and what a good review should check. Lists and checklists help, especially for things like keyboard navigation or WCAG 1.3.1, Info and Relationships. Avoid vague instructions like 'make everything accessible' because Copilot cannot reliably turn that into a precise review.

Jamie: And custom agents?

Alex: Custom agents are more task-oriented. You might have an accessibility reviewer agent, a documentation editor agent, or a release-note helper agent. Instructions guide Copilot's general behavior, while agents automate specific workflows. You can use both together: the repo instructions set the standards, and the agent carries out a focused task under those standards.

Jamie: Here is the uncomfortable question. When should I trust Copilot, and when should I not?

Alex: Trust it most for low-risk drafts, explanations you can verify, and suggestions that match patterns already visible in the repository. Verify anything that changes behavior, affects accessibility, touches security, modifies commands, or claims to summarize policy. Reject output that you do not understand, that invents files or APIs, that removes important context, or that makes the experience worse for users.

Jamie: What are common failure modes?

Alex: Copilot can hallucinate, which means it can confidently state something false. It can produce outdated syntax, overlook project conventions, miss accessibility requirements, or generate text that sounds polished but says very little. It can also overfit to nearby code, repeating a bad pattern because that is what it sees.

Jamie: What does a good verification pass include?

Alex: Read the diff, run the relevant test or preview, confirm links and commands, check that the change matches the issue or goal, and make sure the language is accurate. For accessibility work, do not accept claims like 'this is accessible' without checking keyboard behavior, labels, headings, names, roles, states, focus order, and screen reader output when those things apply.

Jamie: And the accessibility limitations are not only about the code it writes. They are also about using the tool itself.

Alex: Yes. Streaming chat can be hard to follow, ghost text can be noisy, focus can move in surprising ways, and some newer surfaces, like advanced agent controls, may not feel as polished with every screen reader. Accessible View helps a lot for reading long responses and code blocks, but it does not remove the need to review carefully. Official accessibility guides and screen reader demonstrations are good companion references when your setup behaves differently from someone else's.

Jamie: If a learner only remembers one practical workflow from this episode, what should it be?

Alex: Use Copilot in small, reviewable loops. Ask a clear question, provide enough context, read the response in a way that works for you, apply only the part you understand, and verify the result. That is how Challenge 13 is designed: sign in, prompt, apply, reflect.

Jamie: And the learning cards in the chapter are there for quick review, not as a separate project.

Alex: Exactly. They reinforce inline suggestions, chat, edits, agent mode, Copilot on GitHub.com, prompting, Accessible View, and critical evaluation. By the end, you should be able to use Copilot to explain unfamiliar code, create a small configuration change, draft contribution text, and keep human judgment in charge.

Jamie: That last part is the anchor for me. AI can speed up a draft, but it cannot take responsibility for the contribution.

Alex: Well said. Copilot can be a useful partner, especially for documentation and exploration, but your review is what makes the work trustworthy.

Transcript

Alex: Welcome back. Episode 40 is our Copilot reference companion. It is not trying to teach one tiny workflow; it is the place you come back to when you need the shortcut, the command, the mode, the setting, or the safety check.

Jamie: So this is the desk reference version of Copilot. Less mystery, more, where is that control and what does it do?

Alex: Exactly. We are covering Copilot in VS Code, Copilot Chat, participants like @terminal and @github, variables like #file and #codebase, slash commands, agents, MCP servers, custom instructions, models, pricing, plugins, the CLI, and pull request help. The big theme is control: give Copilot the right context, choose the right mode, and review what it gives you before it lands in your work.

Jamie: Let's start with the thing people usually need first: keys. What are the Copilot shortcuts worth memorizing?

Alex: For inline suggestions, also called ghost text, Tab accepts the whole suggestion and Escape rejects it. Ctrl+Right Arrow on Windows or Linux, and Cmd+Right Arrow on macOS, accepts one word at a time. Alt+] and Alt+[ move through alternative suggestions on Windows or Linux, with Option+] and Option+[ on macOS.

Jamie: The word-by-word option feels important. If Copilot suggests a long line, I do not want to accept a whole sentence or function before I know what is in it.

Alex: Right. The full suggestion list opens with Ctrl+Enter on Windows or Linux, and Cmd+Enter on macOS. For accessibility, Alt+F2 opens Accessible View, Option+F2 on macOS, and Ctrl+/ or Cmd+/ inserts the suggestion from Accessible View at the cursor.

Jamie: And for Chat, the common pattern is open the Chat panel, send with Ctrl+Enter or Cmd+Enter, and clear the conversation with Ctrl+L or Cmd+L. Inline chat is Ctrl+I on Windows or Linux, Cmd+I on macOS.

Alex: Yes. The appendix also separates the official screen reader workflow: enable VS Code screen reader mode, consider accessibility signals, use Accessible Help when needed, and read Copilot responses in Accessible View instead of trying to follow live streaming text. For inline suggestions, open Accessible View, review the suggestion, then insert only when it is safe.

Alex: Copilot Chat gets much better when you tell it where to look. The @ participants scope the conversation to a source, while # variables attach specific context.

Jamie: Give me the plain version. If I type @terminal, what am I asking for?

Alex: You are asking Copilot to use the integrated terminal as context. @github can search GitHub data such as issues, pull requests, and code you can access. @vscode can help with VS Code features and settings in environments where that participant is available. @workspace searches the current workspace, but newer prompts should usually prefer #codebase because it works more broadly across modes.

Jamie: So @ is about the source, and # is about attaching something specific.

Alex: Exactly. #file lets you pick a file. #selection sends the text you selected. #terminalLastCommand attaches the last command and output. #githubRepo can point Copilot at a repository you can access, and #codebase searches the project for relevant snippets.

Jamie: Then slash commands are the quick actions. /explain for plain-language explanation, /fix for repair suggestions, /tests for tests, /doc for documentation, /new or /generate when your environment offers generation commands, /help to see what exists, and /clear when the thread has gotten noisy.

Alex: And two commands are especially useful for project setup. /init can analyze a workspace and create .github/copilot-instructions.md. /savePrompt can turn a useful chat exchange into a reusable .prompt.md file. The exact list can change by VS Code version, Copilot plan, extension, and workspace, so /help is always worth checking.

Jamie: Chat modes are where I see people get nervous. Ask, Edit, Agent, Plan... those names sound close until you know what can actually change files.

Alex: Ask is conversation only. It explains and suggests, but it does not directly edit files. Edit works on a chosen set of files and proposes diffs you approve or reject. Agent can inspect files, make changes, and run commands, so it needs more review. Plan writes a plan first, and no code should be written until you approve that plan.

Jamie: And since VS Code unified the Chat view, the mode selector lives down by the Chat input, right?

Alex: Yes. Tab through the bottom of the Chat view until you reach the mode selector, then press Space or Enter to open it. The model selector is a separate control near the same area, so do not confuse mode with model. Mode changes the kind of work Copilot is allowed to do; model changes the engine answering you.

Jamie: Where does the newer Agents window fit in?

Alex: In VS Code 1.120 and later, the Agents window gives a more agent-first workflow. You can open it from the Activity Bar or Command Palette by searching for Agents, then review available agents, their capabilities, and their task state. The safe pattern is to ask for a plan, review proposed changes, inspect diffs, and only then accept or run anything that affects your repository.

Jamie: That helps with accessibility too, because the task state and review points are easier to revisit than a fast-moving stream of text.

Alex: Exactly. Smart Actions are another entry point: they appear from editor context, quick fixes, menus, or the Command Palette, depending on the file and selection. They can explain, fix, generate, or document based on what you are focused on. The Browser Agent is different: it can interact with web pages for browsing and testing tasks, but it is experimental, so treat its results as something to verify, not as a final accessibility audit.

Jamie: And Plan Agent is the calmer option for complex work. It gives you a proposal before implementation. Copilot Spaces adds the team knowledge base angle, where shared context such as docs, decisions, and repository guidance can travel with the team instead of living in one person's memory.

Alex: MCP stands for Model Context Protocol. An MCP server is a tool provider Copilot can call when a task needs something outside ordinary chat, such as scanning a page, querying a service, or reading structured project information.

Jamie: So MCP is not another chatbot. It is more like a bridge from Copilot to tools.

Alex: Yes. The appendix catalogs many MCP tools, including accessibility scanning tools, browser-related tools, documentation helpers, and repository helpers. In VS Code, you configure the server, allow Copilot to use it in the right mode, and review tool calls before you trust the result.

Jamie: I like the review part there. An accessibility scanner can find real issues, but it can also miss things a human user would notice immediately.

Alex: Exactly. MCP tools can also run in CI/CD, which means continuous integration and deployment workflows. That is useful when you want scans or checks to run whenever code changes. Some MCP integrations require local dependencies such as Docker, and some require tokens or permissions, so the setup belongs in documentation, not in someone's private notes.

Jamie: And for workshop use, that means MCP can support accessibility testing, but it does not replace keyboard testing, screen reader testing, or a careful review of the user experience.

Alex: Custom instructions are how you teach Copilot the house rules of a project. The most common repository-level file is .github/copilot-instructions.md, and it is always-on for that workspace when supported.

Jamie: What goes in that file without turning it into a novel?

Alex: Short, concrete guidance. For an accessibility project, that might include WCAG expectations, semantic HTML preferences, documentation tone, commit message style, test requirements, and code quality rules. /init can generate a first draft, but you still need to edit it so it reflects the actual project.

Jamie: The appendix also mentions AGENTS.md and CLAUDE.md. Those are for broader tool compatibility, right?

Alex: Right. AGENTS.md is useful in multi-tool or monorepo settings where several coding agents need shared instructions. CLAUDE.md can support cross-tool compatibility where that ecosystem is used. For more targeted rules, .instructions.md files can include frontmatter and applyTo glob patterns, such as applying test conventions only to files matching a test path.

Jamie: So if a test file convention only matters under tests, you do not need to burden every prompt with it.

Alex: Yes. Instructions can exist at repository, user, and organization levels, and conflicts can happen. When Copilot seems to ignore an instruction, check whether the file is in a supported location, whether the setting that loads instruction files is enabled, whether the glob pattern matches, and whether a higher-level or later instruction is contradicting it.

Jamie: Troubleshooting sounds unglamorous, but it is probably where people save the most time.

Alex: Absolutely. The appendix calls out common issues: copilot-instructions.md not being followed, .instructions.md not loading automatically, a custom agent not appearing, a slash command not showing up, conflicting instruction files, and instruction file locations not working as expected. A practical check is to view loaded customizations in VS Code, confirm your Copilot and VS Code versions, and reopen the workspace after configuration changes.

Jamie: There is also a configuration scope reference, which I read as: know whether the setting belongs to this repository, to my personal VS Code setup, or to the organization.

Alex: Yes. Repository settings travel with the project and help the team. User settings follow you across workspaces through Settings Sync if you use it. Organization instructions are configured through GitHub plans that support them, and they can set expectations across many repositories.

Jamie: And the quick reference card is the fast path: open Copilot, read responses, accept or reject suggestions, and manage instruction files.

Alex: For screen reader workflows, the appendix repeats the reliable habits: enable screen reader mode, consider accessibility signals, learn the official shortcut table, use the suggestions panel when needed with Ctrl+Enter or Cmd+Enter, and read Chat responses in Accessible View. NVDA, JAWS, and VoiceOver users may use different navigation keys inside the readable pane, but the goal is the same: review the complete answer before acting on it.

Alex: The plugin ecosystem expands what Copilot can do. The awesome-copilot collection is a catalog of prompts, instructions, agents, and related integrations that can be browsed and installed.

Jamie: And that is different from Accessibility Agents, right?

Alex: Yes. Accessibility Agents is a living catalog focused on accessibility contribution workflows. awesome-copilot is a broader plugin ecosystem. In Chat, the /plugin command can help browse and install supported plugins, and the CLI flow can browse a marketplace, add the collection, install a specific plugin, and list what is installed.

Jamie: Some MCP server integrations need Docker, so a learner should not assume every plugin is one-click.

Alex: Correct. The appendix also moves into GitHub agentic workflows and third-party agents. These can take a task from GitHub, work on it in the cloud, and open a pull request or produce a result for review. The accessibility skill is not just assigning the task; it is reviewing the agent's pull request with the same care you would use for any contributor.

Jamie: The workflow files are Markdown with frontmatter, which means they have human-readable instructions plus structured properties at the top.

Alex: Yes. The security model emphasizes safe outputs, so workflows should produce reviewable artifacts instead of silently changing protected systems. The gh aw CLI extension can create a workflow, compile the Markdown workflow into a locked GitHub Actions file, and then you commit both the source .md and the .lock.yml that Actions actually runs. After that, you monitor the runs like any other automation.

Jamie: Models are the part where people ask, which one should I pick, and also, will this cost me credits?

Alex: A practical way to choose is by task. Use everyday models for normal coding and writing, faster models for simple repetitive work, deeper reasoning models for hard debugging or architecture, agent-oriented models for multi-step implementation, and visual models when images or screenshots are part of the work.

Jamie: And Auto model selection can choose for you, but it is not magic.

Alex: Right. Auto is convenient when you do not have a strong preference. Override it when you need speed, when you need deeper reasoning, when a model is not available on your plan, or when usage limits matter. Model availability, billing, and retirement notices change, so the appendix points learners to current Copilot plan and billing information rather than treating one snapshot as permanent.

Jamie: Switching models in VS Code happens from the model control near the Chat input, and in inline chat there may be a model picker in that inline session. Keyboard users can Tab to it and listen for the current model name.

Alex: The pricing reference separates plan features from usage. The free plan is useful for workshops, but it has limits and restrictions. Pro and higher plans raise or change access, and GitHub AI credits affect some premium or usage-based features, especially as billing rules evolve after June 1, 2026. If you are teaching or learning in a group, check your plan before relying on a high-usage agent workflow.

Alex: Copilot also exists in the GitHub CLI. With the GitHub CLI extension installed, gh copilot suggest can propose a command, and gh copilot explain can explain a command you already have.

Jamie: That is useful when the scary part is the terminal. You can ask for a command, but still read it before running it.

Alex: Exactly. For example, you might ask gh copilot suggest how to list recent branches, or use gh copilot explain on a command before you paste it into a workflow. Treat suggestions as drafts, especially when a command can delete files, rewrite history, change permissions, or publish something.

Jamie: And on GitHub pull requests, Copilot can help summarize changes and review code, but it is not a maintainer.

Alex: Right. PR summaries can help a reviewer understand what changed, and Copilot review comments can catch possible issues. Still, you check the diff, run tests, confirm accessibility behavior, and make sure the final contribution matches the repository's standards. In Challenge 16, a review-ready draft or a clear contribution plan can be valid evidence when the work is meaningful, whether the repository is Accessibility Agents, GLOW, or another appropriate project.

Jamie: So the reference is not asking us to memorize every command. It is giving us a way to choose the right Copilot surface, add the right context, slow down for review, and leave work that another person can understand.

Transcript

Alex: Welcome back. Today we're taking the Copilot reference material and focusing on the part that can feel slippery: billing, GitHub AI Credits, and model choice.

Jamie: Slippery is the word. A learner opens Copilot, sees a model name, sees a plan limit somewhere else, and wonders, am I about to spend something?

Alex: Exactly. Appendix K is a broad reference for Copilot in VS Code and GitHub: shortcuts, chat, agents, plugins, instructions, accessibility workflows, and pricing. But model names, limits, and availability change often, so the safer skill is learning where to check and how to choose.

Jamie: So we are not trying to memorize a frozen chart. We are trying to make good decisions when the chart changes.

Alex: Let's ground this in the everyday Copilot surfaces first. Inline suggestions are the ghost text that appears in your editor, and the core keys are Tab to accept, Escape to reject, Ctrl+Right Arrow or Cmd+Right Arrow to accept one word, Alt+] or Option+] for the next suggestion, and Ctrl+Enter or Cmd+Enter for the full suggestion list.

Jamie: And for screen reader users, the big one is Accessible View, right?

Alex: Yes. When a suggestion or response appears, Alt+F2 on Windows or Linux, and Option+F2 on macOS, opens Accessible View. It gives you the content in a readable pane instead of making you chase streaming text, and Ctrl+/ or Cmd+/ can insert a suggestion from that view.

Jamie: What about chat itself?

Alex: In VS Code, Ctrl+Alt+I often opens the Chat panel, Ctrl+I or Cmd+I opens inline chat at the cursor, and Ctrl+Enter or Cmd+Enter sends a message. If a keymap differs, the Command Palette is your fallback; search for the Chat command by name.

Jamie: And context is where people get tripped up too. They ask a good question, but Copilot does not know what they meant.

Alex: Right. You can type @ participants to scope context, such as @github for GitHub data or @terminal for terminal output. You can also attach specific context with # variables: #selection for selected text, #file for a file picker, #codebase for a workspace search, #githubRepo for a repository you can access, and #terminalLastCommand for the last command and output. For new prompts, #codebase is usually the better choice than the older @workspace habit.

Jamie: Then slash commands and modes sit on top of that.

Alex: Yes. Slash commands like /explain, /fix, /tests, /doc, /new, /help, /clear, /init, and /savePrompt give Copilot a specific action. Modes change how much Copilot can do: Ask answers, Edit proposes diffs, Agent can work across files and tools, and Plan writes an implementation plan before code is changed. The model selector is separate from the mode selector, usually near the bottom of the Chat input area.

Jamie: So where does the model actually touch the workflow?

Alex: In Ask mode, the model affects the quality, speed, and style of the explanation. In Edit mode, it affects the proposed diff. In Agent mode, it affects planning, tool use, file edits, and terminal choices. In review workflows, it can affect how Copilot summarizes or critiques a pull request.

Jamie: That makes model choice feel bigger than just picking a smarter chatbot.

Alex: It is bigger. Appendix K also covers the wider ecosystem: the VS Code Agents window, Smart Actions, the experimental Browser Agent, Plan Agent, Copilot Spaces for team knowledge, MCP servers for tools such as accessibility scanning, and the awesome-copilot plugin ecosystem. There are also GitHub cloud agents and third-party agents that can be assigned work and produce pull requests.

Jamie: Which sounds powerful, but also like something you should review carefully.

Alex: Absolutely. Agent output should be reviewed through diffs, tests, accessible reading workflows, and small commits. Agentic workflows can be defined in Markdown with frontmatter, compiled into locked GitHub Actions workflow files, and monitored like other automation. The safe habit is to review the output, not just the promise.

Jamie: And organization policy can change what someone sees.

Alex: Yes. An organization or enterprise can allow or block models, agents, MCP tools, custom instructions, and related features. Two learners can open the same version of VS Code and still have different options because their account, plan, region, or organization policy is different.

Jamie: Now the money question. What are GitHub AI Credits?

Alex: Copilot has plan entitlements, and GitHub also uses usage-based billing through GitHub AI Credits for some AI activity. The May 2026 reference material points learners to current plan details, free plan limits, Pro comparisons, and usage-based billing information after June 1, 2026. Prices and allowances are not workshop facts to memorize forever.

Jamie: What kinds of Copilot activity might consume credits?

Alex: Check the current Copilot billing and usage pages for the exact answer on your account. In general, higher-cost experiences can include premium model requests and agentic or review workflows, depending on the plan and product surface. Chat, edits, agent mode, cloud coding agents, code review, Spaces, extensions, and premium models may be counted differently, while basic inline completions and plan-included usage may be covered until a plan limit is reached.

Jamie: So the honest answer is, do not assume every Copilot feature is billed the same way.

Alex: Exactly. Free plan users may have monthly caps and feature restrictions. In a workshop, use core prompts, smaller requests, and lighter models when possible; avoid long agent loops unless they are necessary; and keep evidence of what you did. Recommend an upgrade only when the work actually needs more capacity or a feature that the learner does not have.

Jamie: If I want to check my current access, where do I go?

Alex: On GitHub.com, open your account settings, find Copilot, and review your plan, usage, enabled features, and available models. If your Copilot access comes through a workplace or school, also check organization or enterprise settings if you have permission, or ask an admin what policies are applied. Your personal settings might not tell the whole story.

Jamie: And in VS Code?

Alex: Open Copilot Chat, then move through the controls near the bottom of the Chat view. The mode selector and model selector are separate controls; press Space or Enter to open a dropdown. In inline chat, some versions also expose a model control for that session, and if the interface changes, the Command Palette is still a good way to search for Copilot and Chat commands.

Jamie: Any accessibility checks while doing that?

Alex: Enable VS Code screen reader mode if it is not already enabled, and consider accessibility signals if they help you track events. Use Accessible View for chat responses, inline suggestions, and code blocks. When comparing inline suggestions, the suggestions panel with Ctrl+Enter or Cmd+Enter and word-by-word acceptance can make review less rushed.

Jamie: How should someone choose a model without memorizing model names?

Alex: Choose by task. For everyday coding and writing, a balanced default or Auto selection is usually fine. For simple repetitive tasks, a faster model can be enough. For deep reasoning, debugging, or tricky architecture, choose a reasoning-oriented model if you have access.

Jamie: And agentic work?

Alex: For agentic software development, use a model that is good with tools, planning, and multi-step changes. For visuals, choose a model that supports image input or visual understanding. The labels may change, but the question stays the same: what does this task require?

Jamie: Where does Auto model selection fit?

Alex: Auto lets Copilot choose a model for the request. It is helpful when you are not sure what fits, but you may want to override it when cost, latency, organization policy, reproducibility, or a specific capability matters. If you are documenting a result, say whether you used Auto or a named model.

Jamie: And models retire too.

Alex: They do. New models appear, old models retire, limits change, and availability can differ by plan, region, organization policy, and product surface. That is why a model list from a lesson is a snapshot, not a guarantee.

Jamie: If I write documentation about Copilot models or billing, how do I keep it from going stale immediately?

Alex: Include the date you checked, link to official Copilot documentation, billing pages, changelog posts, or VS Code release notes, and say where you observed the behavior. For example, mention whether you checked GitHub settings, the VS Code model picker, an organization policy page, or a billing dashboard. That gives the next reader a trail to verify.

Jamie: The source material uses dated language like facts verified in May 2026.

Alex: That is a useful pattern. Write something like, "Verified May 2026," then quote only what the source actually says. If a learner or maintainer reads it later, they know whether to refresh the claim before relying on it.

Jamie: Models are one part of Copilot behavior, but instructions are another. How do those fit in?

Alex: Custom instructions tell Copilot how to behave in a repository or workspace. A .github/copilot-instructions.md file can set repo-level guidance, AGENTS.md can help in multi-tool or monorepo contexts, CLAUDE.md may support cross-tool compatibility where available, and .instructions.md files can use frontmatter and applyTo patterns for scoped rules. Organization-level instructions can also apply for GitHub Teams or Enterprise setups.

Jamie: What about old settings-based instructions?

Alex: The reference steers learners toward files instead of older settings-based task instructions. If Copilot ignores guidance, check whether the file is in a supported location, whether the glob pattern matches, whether another instruction conflicts with it, and whether organization instructions are overriding something. Diagnostics can also help you view loaded customizations and troubleshoot missing agents or slash commands.

Jamie: So model choice is not the only lever.

Alex: Right. Context variables, custom instructions, chat mode, plugins, MCP tools, Smart Actions, Spaces, organization policy, and account plan can all change the result. When Copilot surprises you, do not blame the model first; check the whole setup.

Jamie: How does this connect back to the course challenges?

Alex: Challenge 15 is browse-first in the Accessibility Agents living catalog. Learners are not required to fork that repository to complete the challenge. Completing Challenge 15 unlocks Challenge 16, titled Capstone Project, plus Bonus Challenges A through E as a structured path.

Jamie: And the capstone is not limited to one repository.

Alex: Correct. Challenge 16 can accept contributions to Accessibility Agents, GLOW, or another meaningful repository. A review-ready draft or a clear contribution plan can be valid evidence, especially when billing limits, organization policy, or model access affects what a learner can complete.

Jamie: Where do the Day 1 contributions happen?

Alex: In each learner's Learning Room repository. That is where the issue, branch, commit, pull request, and merge workflow happens. For Copilot-related evidence, name the workflow you used, the model or Auto setting if relevant, the date, and any limits or policy restrictions you encountered.

Jamie: So the takeaway is not, memorize which model is best this month.

Alex: Right. Check your access, choose a model by task, watch usage, review agent output carefully, and document any model or billing claim with a date and an official source. And when you are listening with a screen reader, keep Accessible View close; it turns Copilot from a stream of motion into text you can actually inspect.

Transcript

Alex: Welcome back. Challenge 13 is called AI as Your Copilot, and the main idea is simple: use GitHub Copilot to improve documentation, then decide whether the suggestion deserves to stay.

Jamie: I like that wording, because it does not say, let the AI take over. It says, use it, inspect it, and keep your own judgment in charge.

Alex: Exactly. Copilot can be a writing partner, a code explainer, a command helper, and sometimes a creative spark. But it can also be confidently wrong, too wordy, or unaware of the workshop context.

Jamie: So the win is not just getting a nicer paragraph. The win is being able to say what you asked, what Copilot offered, and why you accepted, changed, or rejected it.

Alex: Yes. In this challenge, that evaluation is part of the work. You are practicing AI-assisted contribution without handing away responsibility for the final change.

Jamie: Before someone starts, what needs to be working in VS Code?

Alex: You need VS Code open with your Learning Room repository available locally. Current VS Code builds include built-in AI features, so you usually do not need a separate Copilot Chat extension, but your GitHub account still needs Copilot access.

Jamie: And access can vary, right? Some people have Copilot Free, some have student access, and some are in an organization where an admin controls it.

Alex: Right. Copilot Free is available to individual developers with monthly limits, verified students may have the GitHub Copilot Student plan, and enterprise or organization access depends on policy. If you are unsure, check your Copilot settings on GitHub, review the Copilot plans page, or ask a facilitator before burning time troubleshooting.

Jamie: There is also billing language in the chapter. Do learners need to panic about that?

Alex: No panic. The workshop keeps prompts short and focused on documentation tasks. The important practical note is that GitHub Copilot is moving to usage-based billing on June 1, 2026, and features like chat, CLI, cloud agent, Spaces, Spark, and third-party coding agents use GitHub AI Credits, while code completions and next edit suggestions are not billed in AI Credits for paid plans.

Jamie: So if Copilot is missing, first update VS Code, then look for the Copilot status item, or use the Command Palette.

Alex: Yes. Open the Command Palette with Ctrl+Shift+P, or Cmd+Shift+P on Mac. You can run commands like Chat: Open Chat, Inline Chat: Start in Editor, or Chat: Open Agents Window if a shortcut does not work with your keyboard layout or assistive technology setup.

Alex: The assigned Challenge 13 issue starts in the same file from the code review challenge: docs/code-review-sample.md. Open it from the Code tab if you need to orient yourself, then open that same file locally in VS Code.

Jamie: So we are not asking Copilot to invent a whole new project. We are asking it to improve a real workshop document that already exists.

Alex: Exactly. Select a paragraph or section that could be clearer, or choose an issue you noticed during Challenge 12. Then start Copilot from the Copilot icon, the shortcut your setup supports, or the Command Palette.

Jamie: The prompt can be plain, right? Something like, improve the clarity of this paragraph for beginners.

Alex: That is a good starting point. You might also ask, suggest a better heading for this section, or rewrite this paragraph for someone new to pull requests. The key is to keep the request focused enough that you can evaluate the result.

Jamie: And once it suggests something, the options are accept, modify, or reject.

Alex: Yes. Accept means the suggestion is accurate, clearer, in the right tone, and accessible. Modify means Copilot helped, but you need to tighten it, remove extra claims, or make it fit the document. Reject means the original is better, or the AI introduced a problem.

Jamie: What makes a prompt good for documentation work?

Alex: A good prompt gives context, states the audience, names the task, and adds constraints. For example, instead of saying, make this better, say, rewrite this README paragraph for beginning GitHub contributors, keep the tone welcoming, avoid jargon, and do not add new facts.

Jamie: That last part matters. If Copilot adds new facts, now you have to verify them.

Alex: Exactly. Chapter 16 gives several useful patterns: contextual rewrite, generate with constraints, review and improve, accessibility audit, and draft from an outline. All of them work best when you tell Copilot what material to use and what not to invent.

Jamie: Can learners use inline suggestions too, or should they only use chat?

Alex: They can use both. Inline suggestions are the ghost text that appears while you type in the editor. You can accept a suggestion, open the full suggestions panel with Ctrl+Enter, or accept part of it word by word with Ctrl+Right Arrow, and on Mac that is usually Cmd+Right Arrow.

Jamie: Ghost text can be noisy with a screen reader, though.

Alex: It can. NVDA, JAWS, and VoiceOver users may want to adjust announcement settings, use Accessible View, or temporarily disable inline suggestions if they are interrupting concentration. You can disable them for the current language, turn them off through the Copilot status item or Command Palette, or change the setting more permanently in VS Code settings.

Jamie: Chat feels easier to review because the answer is in one place. How do you recommend opening it?

Alex: The current default shortcut in VS Code is Ctrl+Alt+I for the Chat view, but shortcuts can vary. The reliable fallback is the Command Palette command Chat: Open Chat. Once it opens, the panel is usually a sidebar with controls near the top, the conversation history, the response area, and the input box.

Jamie: And chat has modes now, not just one text box.

Alex: Right. Ask mode is best when you want an explanation or advice. Edit mode is better when you want Copilot to propose changes. Agent mode lets Copilot take more initiative, including planning work and requesting terminal commands, so it needs closer supervision.

Jamie: What about models? The chapter mentions choosing a model and auto selection.

Alex: For this workshop, do not get stuck comparing models. Use the default or auto selection unless a facilitator tells you otherwise. The bigger skill is asking a focused question and reading the result carefully.

Jamie: And if the response streams by too fast?

Alex: Use Accessible View. In VS Code, Alt+F2, or Option+F2 on Mac, opens the response in a plain text buffer that is easier to read, search, and copy from. That is useful for chat answers, inline suggestions, and code blocks, especially when the response is long.

Jamie: Chapter 16 also talks about Copilot Edits, Agent mode, the Agents window, and Next Edit Suggestions. How much of that is required for this challenge?

Alex: The assigned challenge can be completed with a focused documentation edit, so you do not need the advanced features. But it helps to know what they are, because they may appear in your VS Code interface.

Jamie: So Copilot Edits is for bigger changes?

Alex: Yes. Copilot Edits can propose changes across one or more files. If you use it, pay attention to the working set, then review the diff file by file so you know exactly what changed before you accept anything.

Jamie: And Agent mode is the one where Copilot may try to drive the work.

Alex: Correct. Agent mode can plan steps and ask permission to run terminal commands. Never approve a command just because it sounds official. Read it, ask what it does if needed, and reject anything that modifies files, installs packages, or contacts services in a way you do not understand.

Jamie: What is the VS Code Agents window for?

Alex: In newer VS Code builds, the Agents window can show available agents and related chat experiences. The safety advice is the same: keep the task small, inspect proposed changes, and do not share secrets, tokens, private keys, or personal data in prompts.

Jamie: And Next Edit Suggestions?

Alex: Those suggest likely follow-up edits after you make a change. They can be convenient for repeated documentation cleanup, but still treat each suggestion as a draft, not a decision.

Jamie: What if someone wants to use Copilot outside VS Code?

Alex: On GitHub.com, Copilot Chat can answer questions about a repository, an issue, code, or general programming topics, depending on your access. In the browser editor, you may also see a Copilot or Copilot actions button when editing a file. If you do not see it, use the VS Code method instead.

Jamie: There are also pull request features, right?

Alex: Yes. Copilot can help draft pull request summaries and may offer code review assistance on GitHub.com. Those are helpful starting points, but you still need to read the PR, confirm the summary is true, and make sure comments are fair and specific.

Jamie: And the command line option is GitHub CLI with Copilot?

Alex: Right. If the gh-copilot extension is installed, you can ask for command suggestions, like how to create an issue with multiple labels, or ask it to explain a command such as git merge --squash. Treat suggested commands with extra care, because command-line mistakes can change files or repository history.

Jamie: The chapter also compares custom instructions and custom agents. Those sound similar, but they are not the same thing.

Alex: Custom instructions are standing guidance that Copilot should follow, such as documentation style, accessibility standards, commit message format, tone, keyboard navigation expectations, WCAG 1.3.1 checks for info and relationships, and design system rules. They can live in places like .github/copilot-instructions.md, depending on the feature and support level.

Jamie: So instructions guide every response, while agents handle a more specific workflow.

Alex: Exactly. A custom agent can be built for a particular kind of task, while instructions provide the baseline behavior. Good instructions are concrete and team-specific; weak instructions are vague, generic, or so broad that Copilot cannot tell what to do.

Alex: Now comes the most important habit: evaluate every suggestion before it enters your repository.

Jamie: The challenge gives five questions. Is it factually correct? Is it clearer? Does it keep the tone? Is it accessible? Did the AI add content I did not ask for?

Alex: Yes. If a suggestion is factually wrong, reject it. If it is not clearer, keep the original. If the tone is off, modify or reject. If it introduces an accessibility issue, fix it or reject it.

Jamie: The common mistakes are very real: fake links, fancy language, lost context, and accessibility regressions.

Alex: Exactly. A fake link can look convincing but lead nowhere. Over-complicated language can turn a beginner-friendly paragraph into a wall of buzzwords. Lost context might make the answer drift into unrelated Python or machine learning content. Accessibility regressions include images without alt text, complex tables where a list would be clearer, or color used as the only way to communicate meaning.

Jamie: Can you give an example of a good Copilot interaction?

Alex: Sure. Suppose you ask Copilot to review alt text in docs/welcome.md for screen reader users. It notices an image with alt text that only says screenshot and suggests something more descriptive, like Learning Room repository Code tab showing the file list with README.md, docs folder, and .github folder.

Jamie: That is better because it says what the image communicates, not just that an image exists.

Alex: Right, but you still evaluate it. Maybe Copilot's version is too long, so you shorten it. Maybe the image is decorative, in which case empty alt text could be more appropriate. You check the purpose of the image, then decide.

Jamie: And when facts are involved, use current references, not Copilot's confidence.

Alex: Yes. Use official Copilot documentation, VS Code Copilot documentation, GitHub Accessibility guides, Copilot plan and billing pages, the custom instructions support reference, custom agent documentation, model selection documentation, and the Copilot changelog when you need current details.

Jamie: Once the documentation edit is ready, what does the repository need to show?

Alex: Save the final version of docs/code-review-sample.md, then stage, commit, and push it on a non-default branch. A typical commit message is docs: improve code-review-sample clarity with Copilot assistance.

Jamie: And the autograder is not judging whether the AI wrote the perfect paragraph.

Alex: Correct. The automated check verifies that a commit exists on a non-default branch. The human learning evidence is in your Challenge 13 issue, where you describe what you asked Copilot, what it suggested, how you evaluated it, one thing it got right, and one thing it got wrong or needed help with.

Jamie: There is also a peer simulation check. Compare the Copilot result with the peer-simulation PR, or with a real buddy if one is available, and ask whether the document actually improved.

Alex: Yes. And if your cohort asks you to bring in the workshop review bot, mention @gandalf-bot in a commit message or PR comment so the change can be audited. Follow your assigned issue first, then any facilitator-specific directions.

Jamie: What are the common stuck points?

Alex: If Copilot is not available, confirm access and sign-in, and ask a facilitator about alternatives. If controls are missing, update VS Code, reload the window, and use the Command Palette. If chat responses are hard to hear, use Accessible View. If every suggestion seems good, make the task harder, such as asking for a rewrite for a screen reader user, then inspect whether the answer really helps.

Jamie: So Challenge 13 is a documentation contribution, a Copilot practice round, and a judgment exercise all at once.

Alex: Exactly. Use Copilot to help you write or review. Keep the parts that are accurate, clear, accessible, and useful. Change or reject the rest, and leave a clear record of how you decided.

Transcript

Alex: Welcome back. Today we're working with issue templates, one of GitHub's best tools for turning a messy intake process into something calm and useful.

Jamie: I love that framing, because a blank issue box can feel like being asked, please describe everything important, with no clue what important means.

Alex: Exactly. An issue template gives contributors prompts before they submit. It can ask for steps to reproduce, expected behavior, actual behavior, environment details, assistive technology setup, or anything else maintainers need.

Jamie: So the template is not just making the issue look tidy. It's helping the contributor include the information that lets someone act on it.

Alex: Yes. And for accessibility projects, that matters a lot. If a report says, button broken, the maintainer has to ask follow-up questions. If the report says which page, which screen reader, what happened, what should have happened, and how to reproduce it, the conversation starts much farther along.

Jamie: Before somebody builds one of these, what should they already have in place?

Alex: You should already know the basics of GitHub issues: opening them, reading them, and moving through the page. You also need a repository where you have write access, such as a personal practice repo or another repo you control. And you want an editor that understands YAML files, because color highlighting helps you catch mistakes.

Jamie: YAML is the format with indentation rules, right? Friendly when it's right, fussy when it's not.

Alex: That is a fair summary. VS Code is a good choice, but github.dev or the GitHub web editor can work too. Copilot can help generate variations, and notification knowledge is useful, but neither one blocks you from doing this chapter.

Jamie: There's also a nice built-in example here. Learners already filled out the workshop registration form earlier.

Alex: Right, and Challenge 14, Template Remix, uses that real registration template as the model. The work pattern is to analyze it, remix it for a new purpose, optionally create a Markdown version, and optionally test it in the template chooser. Plan for about two to two and a half hours if you're doing the exercises and dealing with YAML troubleshooting.

Jamie: And Challenge 14 is design-focused, not an autograded code puzzle.

Alex: Yes. Your evidence is usually a comment on your assigned Challenge 14 issue or a pull request that shows the template you analyzed, remixed, or created. A good completion comment can say whether you analyzed the registration template, what context you remixed it for, whether the YAML validates, where you committed it, and whether you tested the chooser.

Alex: On GitHub, issue templates live in a specific place: the .github/ISSUE_TEMPLATE/ directory inside the repository.

Jamie: So if GitHub doesn't find the file there, the template won't show up where users expect it.

Alex: Correct. A Markdown issue template usually ends in .md. A YAML issue form usually ends in .yml. GitHub reads the files in that folder and uses them to build the template chooser page when someone activates New issue.

Jamie: That's the page where you see choices like bug report, feature request, documentation issue, or whatever the project has configured.

Alex: Yes. The chooser can also be shaped by a config.yml file in that same ISSUE_TEMPLATE folder. That file can add helpful external links, such as a support forum or security reporting page, and it can control whether people can open a blank issue without choosing a template.

Jamie: So the project can guide people toward the right path without blocking every unusual case.

Alex: Exactly. A mature project often offers a few well-named templates, useful descriptions, and maybe a blank issue option if maintainers still want open-ended reports.

Alex: Let's read one like a maintainer. At the top of a YAML form template, you'll usually see keys such as name, description, title, labels, and sometimes assignees.

Jamie: What does each one do in practice?

Alex: The name is what appears as the template choice. The description is the helper text in the chooser. The title can pre-fill the issue title with a prefix like bug report or event request. Labels are added automatically, and assignees can route the issue to a person or team if the project uses that workflow.

Jamie: Then the body is where the actual form fields live.

Alex: Right. In the workshop registration template, you can see several field types. A markdown field displays instructions only. An input field collects one line of text, a dropdown offers a list of choices, and a textarea gives someone room for a longer answer.

Jamie: And each field has its own little set of details.

Alex: Yes. The id is the internal name for the field. The label is what the user hears or sees as the field name. The description explains what to enter, the placeholder gives an example, and validations can mark a field as required.

Jamie: The chapter asks learners to search the file for accessible, too. Not as a word game, but to notice that the form description promises the fields work with screen readers.

Alex: That's professional template design. The template doesn't just collect data. It sets expectations, reduces confusion, and makes the contribution process more predictable than a single empty text area.

Jamie: Once you've read the registration template, the remix challenge feels less intimidating. You're not inventing the whole structure from nothing.

Alex: Exactly. For Challenge 14.2, you copy the registration template into a new file, often something like .github/ISSUE_TEMPLATE/my-template.yml, in a repository where you can commit changes. You keep the basic skeleton: name, description, title, labels, and body. You also keep the field pattern: type, id, attributes, and validations.

Jamie: But you change the meaning of the form.

Alex: Yes. You might turn it into a bug report, event attendance form, product research intake, or accessibility audit request. Change the labels, descriptions, placeholder text, dropdown options, and title prefix so they fit that new purpose.

Jamie: And then decide what truly needs to be required. It is tempting to require everything, but that can make forms exhausting.

Alex: Exactly. Required fields should be the information maintainers need before they can take action. After that, validate the YAML, fix indentation or syntax problems, commit the file, and push it to your repository.

Jamie: The optional Markdown template is different enough that it's worth trying once.

Alex: It is. A Markdown issue template starts with front matter between three hyphens. It uses name, about, title, and labels, and that about key is different from YAML forms, which use description. Below that, you write headings like Problem, Context, and Solution Ideas, often with HTML comments that guide the user without appearing in the final issue after they replace them.

Alex: Testing is where the template becomes real. Open your test repository on GitHub.com, go to Issues, activate New issue, and check whether your template appears in the chooser.

Jamie: If it doesn't appear, the first suspects are location, filename, and YAML syntax.

Alex: Exactly. The file needs to be under .github/ISSUE_TEMPLATE/, it needs the right extension, and the YAML needs to parse. When it does appear, activate Get started on your template and move through the fields.

Jamie: This is a good time to test with a screen reader, not just visually glance at the page.

Alex: Yes. Listen for field labels, descriptions, required indicators, dropdown choices, and checkbox text. Then preview the issue before submitting, because preview shows what maintainers will receive.

Jamie: And the reflection matters. Ask whether the form helped you know what to write, whether anything was confusing, and whether the required fields were reasonable.

Alex: That's the kind of evidence maintainers can use. The best template is not the longest one. It's the one that asks clear questions in the right order.

Jamie: Let's compare the two formats more directly. When would you use a Markdown template instead of a YAML form?

Alex: Use Markdown when the issue can be guided by a few headings and comments, and when you want the contributor to write in a flexible document. It's simple, portable, and easy to edit. It works well for lightweight reports or projects that do not need strict field validation.

Jamie: And YAML forms are better when you need structure.

Alex: Right. YAML forms let you define specific field types. A markdown field gives instructions. An input field is a single line, like a version number or URL. A textarea is for longer answers. A dropdown gives a controlled set of options. Checkboxes are useful for confirmations, checklists, or multiple selections.

Jamie: That's also where required fields come in.

Alex: Yes. In YAML forms, validations can make a field required. That helps prevent incomplete reports, but it should be used carefully. A form with clear labels, short descriptions, useful placeholders, and sensible required fields is much easier to complete.

Jamie: Especially when labels are specific. A field called details is vague. A field called steps to reproduce tells me exactly what belongs there.

Alex: Exactly. The field type should match the answer you want. Don't use a dropdown for something with hundreds of possible answers, and don't use a giant textarea when a short version number would do.

Alex: An accessibility bug report template usually asks for a few core pieces of information: the affected component, the assistive technology setup, expected behavior, actual behavior, steps to reproduce, and any known WCAG success criterion.

Jamie: WCAG is the Web Content Accessibility Guidelines, right? The standards people often use to describe accessibility requirements.

Alex: Right. The template can make that field optional, because not every contributor will know the criterion. It can also include Additional context and a Before submitting checkbox group, where someone confirms they searched existing issues or included reproduction details.

Jamie: I like the assistive technology setup field. Without it, two people can experience the same page very differently and not know why.

Alex: Exactly. A screen reader name, browser, operating system, zoom level, voice control tool, or keyboard-only setup can change the investigation. The goal is not to make contributors prove their report. It's to help maintainers reproduce the barrier respectfully and efficiently.

Jamie: The chapter also includes a second kind of template, a feature request form.

Alex: Yes. A feature request can ask what problem the feature solves, what solution is proposed, who benefits, what alternatives were considered, and whether there are accessibility considerations. That keeps feature discussions from becoming only, please add this, with no context.

Jamie: And custom templates can cover almost anything: audits, research interviews, event support, documentation updates, design reviews.

Alex: Exactly. Start by looking at the issue patterns your project already receives. Then decide the required fields, optional fields, placeholder examples, and help text. Test it yourself, and if you can, ask someone else to try it without coaching.

Jamie: Let's talk about the actual file workflow. Some people will do this in the browser, and some will do it in VS Code.

Alex: In the browser, you can create or edit a file directly in .github/ISSUE_TEMPLATE/, paste in the template, preview where possible, and commit the change. In VS Code, you usually clone or open the repository, create a branch, add the template file, validate it, commit, and push.

Jamie: File naming is one of those small details that saves headaches.

Alex: Yes. Use clear lowercase names with hyphens, like accessibility-bug-report.yml or feature-request.yml. Avoid spaces. And if you're using YAML, watch indentation, colons, quotation marks, and unique ids for fields.

Jamie: What are the common mistakes?

Alex: Tabs instead of spaces, a dropdown with options indented wrong, a colon in text that should have been quoted, or a required validation attached to the wrong level. If something fails, compare it with a working template, run it through a YAML validator, and check the chooser again.

Alex: Issue templates are not the only templates a project can use. Pull request templates guide contributors after they have made a change and are asking maintainers to review it.

Jamie: So an issue template helps describe the need, and a pull request template helps describe the proposed change.

Alex: Exactly. A strong PR template often asks for a description, the type of change, how to test it, accessibility considerations, and related issues. Those prompts help reviewers understand both the code change and the reasoning behind it.

Jamie: And they pair nicely. The issue says what problem exists. The PR says what was changed, how it was tested, and what accessibility impact was considered.

Alex: Yes. In the Accessibility Agents living catalog, and in other meaningful repositories, templates help maintainers keep contribution conversations clear as the project grows.

Jamie: The hands-on work gives learners several ways to practice without treating one path as the only correct one.

Alex: Exercise A is to use an existing template. Navigate to the Issues area of a project such as Accessibility Agents, open the template chooser, select a template, move through the fields, fill it in if appropriate, preview it, and reflect on how the template guided you.

Jamie: And if you're only exploring, be respectful. Don't create noise in a public project unless the workshop instructions ask you to submit something real.

Alex: Exactly. Exercise B is to add an accessibility bug report template to a repository you control. Open the repo in VS Code or the web editor, create the template file, copy or adapt the YAML, validate it, create a branch and commit, test it on GitHub, test with your screen reader, and merge your branch if that fits your workflow.

Jamie: Exercise C is about submitting upstream when the project is ready for that kind of contribution.

Alex: Right. Before opening a pull request, verify the template is useful, valid, and tested. In the PR, answer what the change does, why it is useful, how it was tested, and what issue it relates to if there is one. Then review your own PR, submit it, and respond to feedback.

Jamie: And Exercise D brings it home to your own project.

Alex: Choose a project, identify the issue patterns it gets or might get, design required and optional fields, write placeholders and help text, test locally, optionally deploy to GitHub and test with a friend, then reflect on what you would improve.

Jamie: If someone gets stuck, where should they look first?

Alex: Start with a known working template, like the workshop registration form, and compare structure. Check the folder path, file extension, indentation, and front matter. Then validate the YAML and try the chooser again.

Jamie: And if the form technically works but feels bad to fill out, that's a design problem, not a GitHub problem.

Alex: Exactly. Rewrite labels so they are specific, shorten descriptions, remove unnecessary required fields, and make placeholders realistic. Templates are about asking better questions before frustration builds.

Jamie: There's also the Day 2 amplifier with the Template Builder Agent later in the curriculum.

Alex: Yes. After you understand templates manually, Chapter 19 introduces @template-builder in VS Code to help automate template creation. The important part is that you still review the output: labels, required fields, help text, accessibility language, and whether the template actually helps maintainers.

Jamie: So Challenge 14 is not just, make a file exist. It's learning how to structure a contribution so another human can respond well.

Alex: Exactly. By the end, you should be able to read a professional template, remix it, create Markdown and YAML versions, test the chooser, and explain why the template improves issue quality and reduces back-and-forth.

Transcript

Alex: Welcome back. Today we're working on Challenge 14: Template Remix, and the skill is designing an issue template that helps people give useful information from the start.

Jamie: So instead of opening a blank issue and hoping people know what to write, we give them a guided form.

Alex: Exactly. An issue template can ask for the location of a problem, the expected behavior, the actual behavior, the assistive technology involved, and anything else maintainers need to act.

Jamie: That sounds like accessibility work and project management meeting in the middle.

Alex: It is. Good templates reduce back-and-forth, make issues easier to triage, and help contributors feel less like they're guessing what the project wants.

Jamie: What should learners have ready before they start this one?

Alex: You should already know the basics of GitHub issues: opening them, reading them, and moving around the conversation. You also need a repository where you can write files, usually your class repository or another repo you control. VS Code is the supported Day 2 editor, and YAML highlighting will help a lot because `.yml` files care about spacing. If you joined Day 2 without Day 1, use the Day 2 Quick Start first to confirm your account, tools, and basic workflow are ready.

Jamie: And the familiar workshop registration form comes back here, right?

Alex: Yes. You already filled out that registration template, so now you inspect it as a working example. Copilot can help generate variations, but it's optional. Terminal comfort helps, but you can still use the browser editor or github.dev if that is the right path for you. Plan around two to two and a half hours if you're doing the exercises and fixing YAML mistakes along the way.

Alex: The challenge uses a practical pattern: analyze a real template, remix it for a new purpose, create your own file, and test that it behaves correctly.

Jamie: When you say analyze, where do I actually look?

Alex: Start with `.github/ISSUE_TEMPLATE/workshop-registration.yml`. Then compare it with the worked remix sample in `docs/samples/challenge-14-registration-remix-example.yml`. You're looking for what stayed the same and what changed when the template was adapted for a different purpose.

Jamie: The top of the YAML file is doing a lot of work, isn't it?

Alex: It is. `name` is what people hear or see in the template chooser. `description` is the short helper text below it. `title` pre-fills the issue title with a useful pattern, `labels` adds labels automatically, and `body` defines the actual form fields.

Jamie: And inside the body, each field has its own little set of details.

Alex: Right. The `id` is an internal identifier, the `label` is the field name shown to the person filling it out, the `description` explains what belongs there, and the `placeholder` gives an example. If you see `validations` with `required: true`, GitHub treats that field as required before the issue can be submitted.

Jamie: Okay, once I've studied the existing form, how do I create mine?

Alex: In the current Challenge 14 issue, the file name may be assigned for you. The seeded version asks you to work on your `fix/YOUR-USERNAME` branch and create `.github/ISSUE_TEMPLATE/YOUR-USERNAME-template.yml`. If your instructor or issue text gives a different exact file name, follow that instruction, but keep the file inside `.github/ISSUE_TEMPLATE/` and make sure it ends in `.yml`.

Jamie: That folder path matters because GitHub only looks in certain places for issue templates.

Alex: Yes. In the browser, you can use Add file, then Create new file, and type the full path, including `.github/ISSUE_TEMPLATE/`. Commit the file to a new branch, then open a pull request so the change can be reviewed.

Jamie: What about VS Code, since that's the main Day 2 tool?

Alex: Use the Explorer with Ctrl+Shift+E, or Cmd+Shift+E on Mac. Create `.github` at the root if it is not there, then create `ISSUE_TEMPLATE` inside it, then create your `.yml` file inside that folder. Use the Source Control view with Ctrl+Shift+G, or Cmd+Shift+G on Mac, to stage, commit, and push. Then use the GitHub Pull Requests extension to create the PR.

Jamie: And if someone is working from the command line?

Alex: They can run `mkdir -p .github/ISSUE_TEMPLATE`, then create the file with `touch .github/ISSUE_TEMPLATE/YOUR-USERNAME-template.yml`. Open the repo with `code .`, add the YAML content, then run `git add .`, `git commit -m Add custom issue template`, `git push`, and `gh pr create` if GitHub CLI is set up.

Alex: The minimum structure is small, but it needs to be correct: `name`, `description`, `title`, `labels`, and `body`.

Jamie: I noticed the challenge issue itself has `hidden: true`. Should learners put that in their own template?

Alex: Usually, no. That belongs to the challenge issue form that controls what learners see in the assignment. Your custom template should focus on the public form someone would choose when they click New Issue.

Jamie: Let's slow down on the body fields, because that's where YAML can get intimidating.

Alex: The body is a list of form elements. `markdown` displays instructions and is not an input field. `input` is a single-line answer, like a file name, URL, version, or short title. `textarea` is for longer writing, such as steps to reproduce or a detailed description. `dropdown` gives a fixed list of options, and `checkboxes` supports a checklist or multiple selections.

Jamie: Where does accessibility show up in the design, besides the topic of the form?

Alex: Use clear labels, because those labels are what people rely on when moving through the form. Put real guidance in descriptions, not just in placeholders, because placeholder text can disappear once someone starts typing. Mark a field required only when the maintainer truly needs it. And if a dropdown has choices, make the choices plain enough that a contributor does not have to decode your project slang.

Jamie: Can we walk through the reference example, the accessibility report one?

Alex: Sure. The example file is `.github/ISSUE_TEMPLATE/accessibility-report.yml`. Its name is Accessibility Report, its description says it is for reporting an accessibility barrier in workshop materials, its labels include accessibility and bug, and its title starts with `[A11y]:`.

Jamie: Then the body starts with instructions before asking for information.

Alex: Yes. A markdown block thanks the person and explains why the report matters. Then an input asks where the barrier happened, such as a file name, URL, or line reference. A textarea asks the person to describe the barrier and what they expected instead. Then dropdowns ask about assistive technology and severity.

Jamie: I like that severity question: how much does this affect your ability to participate?

Alex: That's practical intake. Blocked, difficult, and minor tell maintainers how urgent the issue is without making the reporter write a whole priority analysis. The assistive technology question is optional in that example, which is also important, because not every accessibility report depends on a specific tool.

Jamie: Do learners have to make an accessibility report template, or can the topic be different?

Alex: Any useful structured form works. You could make a bug report, feature request, workshop improvement form, session feedback form, help question template, event attendance form, product research form, or accessibility audit request. What matters is that the template guides a contributor better than a blank issue would.

Jamie: The chapter also compares YAML forms with Markdown templates. What's the difference?

Alex: A Markdown issue template is a `.md` file with frontmatter at the top between lines of three hyphens. It uses `name`, `about`, `title`, and `labels`, and then plain Markdown headings like Problem, Context, and Solution Ideas. For a bug report, those headings might be Describe the Bug, Steps to Reproduce, Expected Behavior, Actual Behavior, Environment, Additional Context, and Before Submitting.

Jamie: So Markdown is simpler, but YAML gives more control.

Alex: Right. Use Markdown when a flexible writing prompt is enough. Use YAML forms when you want required fields, dropdowns, checkboxes, clearer labels, and more consistent data. Challenge 14 focuses on YAML, but building a Markdown version is a useful comparison exercise if you want extra practice.

Alex: After the file exists, test the boring details before you celebrate.

Jamie: Because YAML is famous for failing over one tiny spacing problem.

Alex: Yes. Use two spaces, not tabs. Make sure every key has a colon. Keep list items lined up correctly, and quote text when punctuation might confuse the parser. A YAML linter can help you catch mistakes before GitHub does.

Jamie: What does the automated check expect for this challenge?

Alex: The challenge text says the autograder looks for a YAML file in `.github/ISSUE_TEMPLATE/` with a valid `name` field. Some instructions also mention `description`, so include both. In practice, a solid Challenge 14 template should have `name`, `description`, `title`, `labels`, and at least one useful field in `body`.

Jamie: And if the template does not show up in the template chooser?

Alex: Check that the file is in the exact folder, ends in `.yml`, and includes a valid `name`. Some repositories also use `config.yml` to manage the issue chooser, contact links, and whether blank issues are allowed. If you see an option to open a blank issue, that skips the guided form, so use it only when none of the templates fit. For extra practice, activate New Issue, choose your template, move through the fields, preview the issue, and confirm the labels and required fields behave as expected. If you use a screen reader, listen for whether each label and description is announced clearly.

Jamie: What evidence does the learner submit?

Alex: Open your assigned Challenge 14 issue and post the URL of your template file or pull request. Say what you remixed, what purpose your template serves, and which fields you included. You can also note whether YAML validates and whether you tested the template chooser. Then close the challenge issue when the instructions tell you to, because that is what moves you onward to Challenge 15.

Jamie: The chapter also talks about pull request templates. Are those part of the same idea?

Alex: Yes, just at a different point in the workflow. An issue template helps people describe work before it happens. A pull request template helps people explain a change after they have made it, with prompts like what this PR does, the type of change, how to test it, accessibility considerations, and related issues.

Jamie: So for this challenge PR, the description should not just say done.

Alex: Right. Use a clear title like Add custom issue template. In the description, explain the template's purpose, what fields you changed from the registration form, and how you checked the YAML. If someone reviews your PR, respond to the feedback, update the file, and keep the conversation in the PR.

Jamie: Where does Accessibility Agents fit into this without turning Challenge 14 into a different project?

Alex: Chapter 17 uses real issue and pull request templates from Accessibility Agents as examples you can read. The collection is a living catalog, so read the current files instead of memorizing any fixed number of items. For Challenge 14, you're learning to inspect a professional template and build your own; you are not required to fork that catalog to complete this challenge.

Jamie: And later there is a Template Builder Agent, but this challenge is still manual first.

Alex: Yes. The Template Builder Agent is a Day 2 amplifier in a later chapter. Do the manual version first so you can judge whether an automated draft has clear labels, useful descriptions, sensible required fields, and good options. When details change, check GitHub's official documentation about issue and pull request templates and configuring issue templates for the current rules.

Alex: The finish line is not a huge file. It's a working YAML issue form that makes a real contribution easier to explain.

Jamie: Analyze the registration template, remix it for a useful purpose, commit it in the right folder, open the PR, test what you can, and submit the link. That's a very practical Challenge 14.

Transcript

Alex: Welcome back. Today we're talking about Accessibility Agents, a living catalog of specialized AI assistants for accessibility and GitHub workflow tasks.

Jamie: So these are not just general chatbots with a friendly name. They are meant to help with specific work, like reviewing a pull request, checking a page for accessibility issues, or drafting a better issue template.

Alex: Exactly. They extend GitHub Copilot with domain knowledge. Instead of asking a broad assistant to help with everything, you call an agent that has instructions, responsibilities, and guardrails for one kind of task.

Jamie: And the catalog keeps growing, right? The current snapshot names 55 agents, but learners should treat that as a moment in time, not a ceiling.

Alex: Right. The important shape is three teams across five platforms. Accessibility agents cover web, document, and mobile auditing. GitHub Workflow agents help with issues, pull requests, analytics, and templates. Developer Tools agents support Python, desktop apps, CI checks, and custom tooling.

Jamie: That already sounds powerful, but also a little risky. If an agent sounds confident, I can imagine people accepting its answer too quickly.

Alex: Before using any agent, check the basics. You need Git, VS Code, a GitHub account, Copilot working in VS Code, and a repository that either already has a .github/agents folder or can receive custom agent files.

Jamie: And Copilot Free is enough for this workshop, as long as the built-in Copilot features are enabled and working.

Alex: Yes. Then comes the deeper prerequisite: manual skill. If you have not read issues by hand, an issue-tracking agent will not help you judge issue summaries. If you have not reviewed a diff, a pull request review agent can sound useful while missing something important.

Jamie: So the agent is a multiplier. It can speed up a skill I have practiced, but it should not replace learning the skill.

Alex: Exactly. If you want to use @template-builder, you should have designed and tested a template manually. If you want @web-accessibility-wizard or @contrast-master, you should understand the relevant WCAG checks and have tried manual testing. If you want a Python or wxPython agent, you should know enough code and keyboard testing to spot bad advice.

Jamie: I like the self-check: could I do this task manually right now? If the honest answer is no, pause and learn that workflow first.

Alex: That self-check is especially important for blind and low-vision contributors. The agent may summarize a screen, a diff, or a document, but you still need a way to confirm what changed, what evidence exists, and whether the result is accessible.

Jamie: Challenge 15 is where this becomes hands-on. It is a browse-first challenge, not a requirement to fork the Accessibility Agents repository.

Alex: Yes. You start by exploring the living catalog on GitHub.com and matching agents to work you already practiced on Day 1. The beginner-friendly starting set is @daily-briefing, @issue-tracker, and @pr-review because those connect to repository awareness, issues, and pull request review.

Jamie: Then learners post evidence in their assigned Challenge 15 issue, right? Something like, here are three agents, and here is the manual skill that makes me ready to try each one.

Alex: Exactly. Then you validate one agent. You run it carefully, read the output, compare it to what you expected, and write down whether it was accurate, incomplete, or questionable.

Jamie: And the third part is reading the agent itself. Not just using the magic box, but opening the instruction file and asking what it is actually allowed to do.

Alex: Yes. Look for its purpose, capabilities, domain knowledge, responsibilities, response guidelines, and limits. The optional extension path is contribution-oriented: improve an existing agent or propose a new one with a clear accessibility purpose.

Jamie: Completing Challenge 15 matters because it unlocks Challenge 16, the Capstone Project, plus Bonus Challenges A through E. Those bonuses are a structured path, not spare-time extras.

Alex: And do not skip the feedback task. The workshop asks for feedback because these agents, challenges, and examples are evolving with learner experience.

Alex: To run agents locally, you usually work in VS Code with Copilot Chat open. The common shortcut is Ctrl+Alt+I, but if that conflicts with your setup, use the Command Palette and run Chat: Open Chat.

Jamie: What does invoking an agent sound like in practice?

Alex: In Copilot Chat, you mention the agent by name and give it a small task. For example: @daily-briefing morning briefing. Or @issue-tracker find open issues labeled good-first-issue in accessibility-agents. Or @pr-review show open pull requests in accessibility-agents.

Jamie: Small task first. That feels easier to verify than asking for a giant report.

Alex: Exactly. Agents are discovered through files in your repository, commonly under .github/agents, and through related .github configuration. Some setups include a quick install command, with one version for macOS or Linux shells and another for Windows PowerShell.

Jamie: And if the repository carries the agent files, the behavior can travel with the repo. A teammate or contributor can open the project and get the same custom instructions.

Alex: Right. You can also personalize your instance with a preferences file: GitHub username, repositories you work on most, preferred output format, and notification priority. That helps agents produce output that fits your workflow instead of a generic response.

Jamie: On GitHub.com, there are browser-native Copilot features too: PR summaries, PR review help, Copilot in issues, GitHub Models as an AI playground, and release notes drafted from changes.

Alex: Yes, and VS Code 1.120 adds the Agents window as a Preview feature in Stable. It does not replace custom Accessibility Agents. It gives you one place to manage sessions, changed files, customizations, and validation tasks across projects.

Jamie: Let us zoom out to the ecosystem. You said three teams, and I want to understand how they relate.

Alex: Team 1 is Accessibility, with agents for web, document, and mobile work. That includes page audits, contrast checks, keyboard navigation, Word, Excel, PDF, ePub, and remediation support.

Jamie: So that team is closest to accessibility testing and repair.

Alex: Yes. Team 2 is GitHub Workflow. Those agents help with daily briefings, issue tracking, pull request review, analytics, accessibility change monitoring, and template building.

Jamie: And Team 3 is Developer Tools, which sounds like the bridge into code and automation.

Alex: Exactly. That team includes Python and desktop development support, CI accessibility checks, Playwright scanning, and custom tool workflows. Around the agents, there is a supporting ecosystem: slash commands, prompts, hooks in tools like Claude Code, configuration files, and examples for contributors.

Jamie: That is also where the roadmap matters. Learners are not only consumers here; they can help shape what gets built next.

Alex: Yes. A useful contribution might be a clearer instruction, a new workflow example, a bug report about a misleading response, or a new agent proposal for an uncovered accessibility workflow.

Alex: The five platforms give you choices. Most learners should start with GitHub Copilot in VS Code because it is already part of the workshop flow and works well with files, chat, and repository context.

Jamie: But the catalog is not limited to VS Code.

Alex: Right. Claude Code can be useful for faster command-line iteration and hook-based enforcement. Gemini CLI can be a free or low-cost command-line path for some accessibility checks. Claude Desktop can work well for long planning sessions. Codex CLI is another command-line option for agentic coding workflows.

Jamie: How should someone choose without getting overwhelmed?

Alex: Start from your strongest environment. If you use VS Code every day, use the VS Code path. If you prefer the command line, use a CLI path. If you want both, let VS Code handle editing and review while a command-line tool helps with repeatable checks.

Jamie: And accessibility of the platform matters. Screen reader behavior, zoom support, keyboard focus, and how chat output is exposed are all part of the choice.

Alex: Yes. Try the same small task on more than one platform only after you understand the task. Then compare whether the result is easier to navigate, easier to copy, and easier to verify.

Jamie: The slash commands are the part I can imagine using every day. They sound like shortcuts for common prompts.

Alex: That is the idea. The catalog includes 54+ slash commands organized by workflow. A slash command is a named prompt, like /my-issues or /review-pr, that gives the assistant a focused job without making you retype the whole instruction every time.

Jamie: Which ones should learners try first?

Alex: Start with /my-issues to find your work, /review-pr to structure a pull request review, /triage to sort issues, /daily-briefing to get a morning overview, and /a11y-update to summarize accessibility-relevant changes.

Jamie: And reading a command definition is part of the learning, not just running it.

Alex: Yes. Open the command file and look for what it asks the assistant to gather, how it should format the answer, and what behavior it promises. For /a11y-update, for example, you would expect it to focus on accessibility changes, risks, and follow-up actions rather than a generic project summary.

Alex: If a learner asks which agents are worth trying first, I would pick a small, high-impact set. @daily-briefing gives a morning view of issues opened in the last day, PRs awaiting review, CI failures, security alerts, and community activity.

Jamie: That is useful because it turns scattered repository activity into one checklist I can review at my own pace.

Alex: @issue-tracker is good for finding open issues, especially labels like good-first-issue, and it can help draft replies. @pr-review can summarize a pull request, identify risk areas, map changed files, suggest inline comments, and recommend whether minor changes are needed.

Jamie: What about accessibility-specific monitoring?

Alex: @insiders-a11y-tracker watches recent changes for accessibility signals. It might flag a heading hierarchy skip, non-descriptive link text, or a positive change like an ARIA label being added. @template-builder helps create issue templates interactively, which connects back to the template design work from earlier.

Jamie: And @analytics can show team trends, active contributors, files that change a lot, and review turnaround time. That is less about one issue and more about how the project is moving.

Alex: Exactly. The safest habit is to ask for sources and concrete locations: issue numbers, PR numbers, file names, line ranges, or links. Then check those locations yourself before acting.

Jamie: What about building or improving an agent? That sounds like Bonus Challenge A territory.

Alex: Yes. Bonus Challenge A is about improving an existing agent with a clear accessibility purpose. A custom agent usually lives in an agent.md-style file with frontmatter at the top and instructions below it.

Jamie: Frontmatter is the little metadata block, right? The part that tells the system the agent name, description, tools, or permissions.

Alex: Right. Then the body explains purpose, capabilities, domain knowledge, responsibilities, and response guidelines. Informational agents should stay read-only when they only need to summarize or inspect. Task-oriented agents may need file editing, shell execution, or GitHub API access, so their guardrails must be stronger.

Jamie: I want the agent to know when to stop and ask.

Alex: That is the tiered decision pattern. Low-risk actions can be suggested directly. Medium-risk actions should be explained with options. High-risk actions, like changing files, running commands, or opening a PR, should ask for confirmation and leave a clear review path.

Jamie: The template-builder exercises fit here too. Generate a template, extend the agent for a project, then refine the result through feedback.

Alex: Yes, and the pre-built guided workflows give models to study: an accessibility bug report template and a security vulnerability template. You are learning how an agent gathers details, produces a useful file, and invites human review.

Alex: The most powerful workflows chain agents together. One agent can triage issues, another can inspect accessibility risk, another can draft a template or review a PR, and an orchestrator can coordinate the handoff.

Jamie: Orchestrator agents are the ones like @nexus, @accessibility-lead, and @web-accessibility-wizard?

Alex: Yes. @nexus can help route work across the ecosystem. @accessibility-lead can keep the accessibility mission and guardrails visible. @web-accessibility-wizard can coordinate web audit tasks across checks like headings, keyboard flow, contrast, and ARIA usage.

Jamie: Give me a real contribution example.

Alex: You might use /triage to find an accessibility issue, ask @insiders-a11y-tracker what changed recently, ask @web-accessibility-wizard for likely test areas, make a small documentation or code improvement, then ask @pr-review to help prepare a review-ready summary. The human still decides what is true, what should be changed, and whether the evidence is strong enough.

Jamie: That connects directly to Challenge 16, the Capstone Project. The contribution can be to Accessibility Agents, GLOW, or another meaningful repository.

Alex: Yes. Challenge 16 is about choosing a meaningful repository, defining a mission, writing responsibilities and guardrails, and preparing a review-ready contribution. A review-ready draft or a well-supported contribution plan can be valid evidence of completion.

Jamie: Where do GitHub Desktop, GitHub CLI, and Copilot CLI fit into all this?

Alex: GitHub Desktop is useful if you want a visual app for cloning, branching, committing, and pushing. GitHub CLI, the gh command, is useful for signing in, listing issues, checking PRs, viewing workflow runs, and opening links from the terminal.

Jamie: And gh copilot can explain a command, suggest a command, or help write a shell script. That is handy when the terminal is the fastest path but the syntax is hard to remember.

Alex: Exactly. Just keep the same verification habit. If Copilot suggests a command, read it before running it, especially if it edits files, deletes anything, changes permissions, or posts to GitHub.

Jamie: Troubleshooting is pretty practical too. If an agent is not found, check the file location, the agent name, the repository workspace, and whether Copilot or the Agents window has refreshed.

Alex: If the agent gives incorrect output, narrow the prompt, provide the repository or file context, ask for sources, and compare the answer to GitHub itself. If a slash command does not work, check the command name, whether the command file is present, and whether your platform supports that command style.

Jamie: And for going deeper, Appendix V lists the full slash command catalog, while Episode 39 walks through every agent in more detail.

Alex: Exactly. For now, keep the workflow grounded: choose an agent that matches a skill you have, run a small task, verify the output, and only then use it in a contribution.

Transcript

Alex: Welcome back. Episode 39 is a reference companion for Accessibility Agents, so the goal is a little different today. We're not trying to memorize every agent name or every file format. We're learning how the system is organized, how to call on it safely, and how to check its work.

Jamie: That helps, because a complete reference can feel like opening a giant parts drawer. Useful, but only if you know which drawer to reach into.

Alex: Exactly. The reference covers a living catalog of agents, slash commands, instruction files, settings, troubleshooting notes, and the file formats behind them. It also reflects an important platform shift: GitHub's older Copilot extension model has moved toward MCP servers for extensibility, while custom .agent.md files remain a key way to define an agent persona in VS Code.

Jamie: So the reference is both a map of today's agents and a guide to how the whole customization system works.

Alex: Yes. And because this is AI-assisted work, every output still needs human review. An agent can speed up searching, drafting, and organizing, but your manual GitHub and accessibility skills are how you verify the result.

Jamie: Let's start with the big picture. When the reference says agent ecosystem, what are we actually talking about?

Alex: It means a catalog of specialized assistants grouped into three teams: accessibility, GitHub workflow, and developer tools. The catalog grows over time, so treat the number in any one copy of the appendix as a release snapshot, not a permanent fact. The useful part is the organization.

Jamie: And those agents don't all do the same kind of work, right?

Alex: Right. Some are task agents that inspect or change files. Some are informational agents that explain, summarize, or guide. Some are orchestrators, which means they coordinate a larger review by routing parts of the job to more specialized agents.

Jamie: What about platforms? I saw several names in the reference, and that can get confusing fast.

Alex: The main daily workflow is GitHub Copilot in VS Code, where custom agents usually live under .github/agents as .agent.md files. The reference also discusses Claude Code, Gemini CLI, Claude Desktop, and Codex CLI as other environments with their own installation patterns and capabilities. The important accessibility habit is to confirm which platform you are using before expecting a command, tool, or shortcut to behave the same way.

Jamie: So if a learner types an agent name and nothing happens, the problem might not be their typing. It might be platform support or installation location.

Alex: Exactly. Platform, file location, and workspace trust all affect what loads.

Alex: The accessibility team is the largest area of the catalog, and it covers web, document, media, mobile, and content accessibility. You'll see agents for ARIA patterns, modals, color contrast, keyboard navigation, live regions, forms, headings, tables, links, WCAG guidance, cognitive accessibility, data visualization, and more.

Jamie: I like that these are split by accessibility concern. If I have a dialog problem, I don't need a broad audit first. I can ask the modal specialist for focus trapping, Escape behavior, and screen reader announcements.

Alex: Exactly. For documents, the catalog includes agents for Word, Excel, PowerPoint, PDF, ePub, cross-document analysis, inventory, and CSV reporting. That matters because document accessibility has different evidence than web accessibility. A tagged PDF, a spreadsheet header structure, and a web form label all need different checks.

Jamie: And the GitHub workflow team is more about repository activity?

Alex: Yes. It includes agents like @daily-briefing for a morning status report, @issue-tracker for issue triage, @pr-review for structured pull request review, @analytics for team metrics, @insiders-a11y-tracker for accessibility-sensitive changes, and @template-builder for guided issue template creation. The reference notes that some outputs are intentionally arranged with H2 or H3 headings, so a screen reader user can jump through the result by heading.

Jamie: That's a small design choice with a big payoff. If the output is long, headings make it browsable instead of becoming one giant wall of text.

Alex: The developer tools team rounds it out with agents for coding support, testing, documentation, refactoring, security, CI, release work, and similar engineering tasks. They are not a replacement for understanding Git or your codebase, but they can help package work into safer, reviewable chunks.

Jamie: So the agent name should match the job. Accessibility audit, GitHub workflow, or development support.

Alex: Yes. If the request spans more than one area, start with the agent closest to the decision you need, then ask it to produce a clear, checkable output.

Jamie: The reference also talks about slash commands. Are those the same thing as agents?

Alex: Not quite. An agent is a persona with instructions, tools, and behavior. A slash command is a reusable prompt, usually typed with a slash, that packages a common task. The reference covers more than 54 slash commands, and many are designed to produce predictable output formats.

Jamie: So a command might be something like asking for an accessibility update, an issue summary, or a pull request review checklist?

Alex: Yes. A good command says what inputs it expects, what files or tools it may use, and what shape the answer should take. For example, a command could ask for an audit summary with sections for scope, findings, severity, evidence, and suggested fixes.

Jamie: What should learners listen for in the output?

Alex: First, check whether the agent used the right context. Did it look at the correct file, issue, pull request, or repository? Second, check whether the output format matches the request. Third, verify factual claims, especially accessibility claims that cite WCAG, ARIA, keyboard behavior, or screen reader behavior.

Jamie: That verification piece is exactly why Challenge 15 matters. Discover Accessibility Agents is browse-first: learners explore agent files, run agents carefully, and compare AI output against manual skill. They don't have to fork the agent catalog repository just to complete that challenge.

Alex: Right. The evidence is careful exploration and verification, not blind trust. Completing Challenge 15 opens the path to Challenge 16, Capstone Project, and Bonus Challenges A through E. And for the capstone, a review-ready draft or a well-supported contribution plan can count, whether the work targets Accessibility Agents, GLOW, or another meaningful repository.

Alex: Customization is where the reference gets powerful. There are three scopes to understand: personal user-level settings, workspace-level settings shared in a repository, and broader organization-level instructions in supported enterprise environments. When instructions conflict, the more specific or higher-priority instruction wins according to the platform's rules.

Jamie: So if my personal preference says short answers, but the repository says every accessibility audit must include severity and evidence, the repository rule may need to shape that audit.

Alex: Exactly. The reference also describes how multiple instruction files can be combined. That means one repo might have general Copilot instructions, a markdown-specific instructions file, a YAML issue-template instructions file, and a custom agent file all influencing the result.