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.