This document describes the GitHub issue template system used by the RealWorld project to standardize bug reports and feature requests. The templates use GitHub's Issue Forms feature to provide structured, validated inputs for contributors, ensuring consistency in issue submissions and making it easier for maintainers to triage and respond to community feedback.
For guidance on creating new RealWorld implementations, see Creating New Implementations. For information about repository management and community resources, see Repository Management & Resources.
The RealWorld project uses GitHub Issue Forms (YAML-based templates) to provide a guided, form-based experience for issue creation. These templates replace traditional Markdown issue templates with structured forms that include dropdowns, text areas, and validation requirements.
The repository currently maintains two issue templates:
| Template | File | Purpose | Auto-Labels |
|---|---|---|---|
| Bug Report | .github/ISSUE_TEMPLATE/BUG_REPORT.yml | Report bugs in specifications or deployed demo | bug |
| Feature Request | .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml | Suggest new features for RealWorld specs | None |
Sources: .github/ISSUE_TEMPLATE/BUG_REPORT.yml1-29 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml1-37
Issue Forms Workflow: When a user clicks "New Issue," GitHub displays a template selection screen. Selecting a template loads the corresponding YAML-defined form with structured fields. The form validates required fields before allowing submission, then creates a GitHub issue with formatted content.
Sources: .github/ISSUE_TEMPLATE/BUG_REPORT.yml1-29 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml1-37
The bug report template is configured at .github/ISSUE_TEMPLATE/BUG_REPORT.yml1-6:
This configuration automatically:
[Bug]: bug label to all created issuesBug Report Field Structure: The template defines three fields in the body array. The dropdown and textarea fields enforce required validation, while the markdown field provides attribution information.
Sources: .github/ISSUE_TEMPLATE/BUG_REPORT.yml7-28
| Field Index | Type | Label | Required | Options/Description |
|---|---|---|---|---|
| 0 | dropdown | "Relevant scope" | Yes | Frontend specs, Backend specs, Deployed demo, Other |
| 1 | textarea | "Description" | Yes | Clear and concise description of the problem |
| 2 | markdown | N/A | N/A | Attribution footer |
The "Relevant scope" dropdown .github/ISSUE_TEMPLATE/BUG_REPORT.yml8-16 allows contributors to categorize issues by:
demo.realworld.show or api.realworld.showThe "Description" textarea .github/ISSUE_TEMPLATE/BUG_REPORT.yml18-23 is the primary field for issue details, requiring contributors to provide a clear explanation of the bug.
Sources: .github/ISSUE_TEMPLATE/BUG_REPORT.yml7-28
The feature request template is configured at .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml1-3:
Unlike the bug report template, feature requests do not receive automatic labels. The title prefix [Feature Request]: helps maintainers identify these issues in the issue list.
The feature request template defines five fields in its body array .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml4-36:
| Field Index | Type | Label | Required | Purpose |
|---|---|---|---|---|
| 0 | markdown | N/A | N/A | Header: "# Feature Request" |
| 1 | dropdown | "Relevant Scope" | Yes | Categorize by Frontend specs, Backend specs, or Other |
| 2 | textarea | "Description" | Yes | Main feature description |
| 3 | textarea | "Describe the solution you'd like" | No | Proposed solution details |
| 4 | textarea | "Describe alternatives you've considered" | No | Alternative approaches or workarounds |
| 5 | markdown | N/A | N/A | Attribution footer |
Scope Categorization: The "Relevant Scope" field .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml8-17 directs feature requests to the appropriate specification domain. This helps maintainers route requests to the correct part of the RealWorld ecosystem.
Sources: .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml8-17
The template includes two optional textarea fields .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml24-31 that encourage contributors to think through their proposals:
Neither field has required: true validation, acknowledging that not all feature requests come with fully formed solutions.
Sources: .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml24-31
GitHub Issue Forms support multiple field types, used in these templates:
Field Type Usage: Both templates use markdown for static content, dropdown for categorization with validated options, and textarea for free-form text input. Only dropdown and textarea fields support validation requirements.
Sources: .github/ISSUE_TEMPLATE/BUG_REPORT.yml1-29 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml1-37
| Validation Type | Syntax | Templates Using It | Effect |
|---|---|---|---|
| Required | validations: required: true | Bug Report (scope, description), Feature Request (scope, description) | Field must be filled before form submission |
| None | Field omitted or required: false | Feature Request (solution, alternatives) | Field is optional |
The validation system .github/ISSUE_TEMPLATE/BUG_REPORT.yml16-17 prevents incomplete bug reports by enforcing that users select a scope and provide a description. Feature requests require only scope and description .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml16-17 allowing for more exploratory submissions.
Sources: .github/ISSUE_TEMPLATE/BUG_REPORT.yml16-23 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml16-31
Both templates include a markdown footer .github/ISSUE_TEMPLATE/BUG_REPORT.yml24-28 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml32-36:
This attribution acknowledges the Issue Forms Creator tool used to generate the initial template structure. The markdown field appears at the bottom of the form but does not affect the created issue's content.
| Template | Title Prefix | Example Result |
|---|---|---|
| Bug Report | [Bug]: | [Bug]: Articles endpoint returns 500 error |
| Feature Request | [Feature Request]: | [Feature Request]: Add pagination to comments |
The title prefixes .github/ISSUE_TEMPLATE/BUG_REPORT.yml3 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml3 provide visual categorization in the issue list and make it easier to filter issues by type.
Sources: .github/ISSUE_TEMPLATE/BUG_REPORT.yml1-6 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml1-3 .github/ISSUE_TEMPLATE/BUG_REPORT.yml24-28 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml32-36
Issue Creation Sequence: Contributors select a template, fill structured fields with validation enforcement, and submit to create a formatted GitHub issue. The template system ensures consistency in issue format and required information.
Sources: .github/ISSUE_TEMPLATE/BUG_REPORT.yml1-29 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml1-37
The issue templates support the RealWorld project's decentralized ecosystem by categorizing issues into specification domains:
demo.realworld.show and api.realworld.showThis categorization aligns with the repository structure documented in Repository Management & Resources, where separate YAML files track frontend and backend implementations.
Sources: .github/ISSUE_TEMPLATE/BUG_REPORT.yml11-15 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml12-15
To add additional issue templates, create a new YAML file in .github/ISSUE_TEMPLATE/ with the following structure:
The RealWorld project currently uses only bug reports and feature requests, keeping the contribution process simple and focused on specification improvements.
Both templates were generated using the Issue Forms Creator tool .github/ISSUE_TEMPLATE/BUG_REPORT.yml24-28 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml32-36 When updating templates:
Sources: .github/ISSUE_TEMPLATE/BUG_REPORT.yml24-28 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml32-36
Refresh this wiki