GitHub Issue Forms for Useful Reports and Triage

Start by asking what a maintainer needs to do next. To reproduce a bug, they need the affected version, a small sequence of steps, the observed behavior and the expected behavior. Ask for those facts directly in familiar language. Avoid a large questionnaire whose answers do not influence triage. A user who cannot understand a field may supply invented detail just to get through the form, which makes the resulting report less useful.

Use a textarea when several lines or a sequence of commands are needed, an input for a short version string and a dropdown for a small maintained set of choices. Do not turn every optional diagnostic into a required field. Someone reporting a crash may not yet have a complete log or know the responsible component. Let them state uncertainty and ask a focused follow-up. The form should reduce avoidable ambiguity while keeping the reporting process accessible to people with different levels of technical knowledge.

Place the form in .github/ISSUE_TEMPLATE with a YAML extension and supply its name, description and body fields. Body items have supported types, attributes and optional validations. Give interactive elements stable unique ids that describe their meaning. In the example, version, reproduction and behavior form the report's core contract. A required setting ensures an answer is supplied at form submission; it does not validate every technical claim in that answer.

Form responses become Markdown in an ordinary issue body. The issue can later be edited, and issues created through other paths may not follow the same structure. Do not treat headings as a permanent database schema or assume that every issue has passed the form's UI validation. Automation that parses bodies should handle missing, edited or unexpected content deliberately. For critical workflow decisions, use supported structured platform data or explicit maintainer confirmation instead of relying only on fragile text splitting.

The labels listed in a form should already exist in the repository. A nonexistent label is not automatically created simply because its name appears in the YAML. Create a small shared vocabulary such as bug, needs-triage and needs-information, then explain what transitions mean. Labels should help a maintainer find the next decision, not accumulate indefinitely as a history of every passing thought.

Projects and assignment are separate routing concerns. A form's project settings can have permission requirements that ordinary outside reporters do not meet. Use the documented project automation approach when it better fits your audience. Avoid assigning every new report to one person before anyone has checked scope or duplication. Review the rendered form and create one practice report to confirm labels, fields and any intended routing. Do that in a designated practice repository so the test does not pollute a production backlog.

First decide whether the report is in scope and whether it exposes private security information that belongs in the project's private reporting channel. Then check for duplicates, gather missing reproduction details and attempt the smallest reported case. A reproducible defect can move to confirmed; an incomplete report should receive one clear request for the missing information. Explain why that detail matters rather than repeatedly asking the reporter to provide more details without direction.

A confirmed issue is not automatically scheduled work. Separate reproducibility, impact, priority and ownership so the project can make a transparent planning decision. Link the pull request that addresses the report and verify the intended behavior before closing it. For duplicates, link the active report so the person can follow progress. Periodically review whether form questions actually reduce clarification cycles, and remove fields that do not help maintainers reach a decision.

Review templates, issues and projects. Consult the official issue-form syntax, form schema, template configuration and label management.