Improving Repository Quality via Issue Forms and Templates

[DanialPahlavan]

Improving Repository Quality via Issue Forms and Templates

To keep the repository organized and ensure that feedback is actionable, I suggest we move away from blank issue descriptions and implement structured GitHub Issue Templates. Standardizing how users report bugs and suggest features will save time on triaging and make it much easier to reproduce reported errors.

Structured issues are also significantly more effective if we use automated tools or AI assistants to help debug, as the technical context remains consistent across different reports.

Suggested Structure

1. Bug Report Template

The goal is to eliminate "it doesn't work" comments by requiring the technical steps needed to see the error firsthand.

• Problem Summary: A concise explanation of the bug.
• Reproducible Steps: A numbered list of exactly what to click or run to trigger the issue.
• Environment Details: Specifics on the operating system, app version, or hardware being used.
• Expected vs. Actual: What the user thought would happen versus what actually happened.
• Logs/Screenshots: A dedicated section for terminal output or visual evidence.

2. Feature Request Template

This helps distinguish between "cool ideas" and actual functional improvements that solve a problem.

• Use Case: What specific problem is this new feature trying to solve?
• Proposed Logic: A description of how the feature should ideally work from the user's perspective.
• Alternatives Considered: Any workarounds currently being used.
• Visuals/Mockups: (Optional) Basic sketches or diagrams if the feature involves UI changes.

3. Technical Improvement / Refactoring

A specific template for maintenance tasks that aren't bugs but improve the codebase.

• Affected Module: Which part of the code needs attention.
• Reason for Change: Improvement in performance, readability, or security.
• Suggested Approach: Technical notes for the developer who picks up the task.

Implementation Strategy

The most efficient way to do this is by creating a .github/ISSUE_TEMPLATE folder and using GitHub’s YAML Form format. Unlike basic Markdown templates, YAML forms allow us to create required fields and dropdown menus, which forces a higher standard of input from the user before they can hit submit.

Once these are in place, the repository will be much easier to manage as it grows, and the quality of contributions will stay high.

[Isusami]

I wanted to also raise this because I also have a lot of ideas, features, and performance improvements in mind, but without a proper template I end up just pushing a PR directly instead of opening a structured discussion. Having the right templates in place would make it much easier for everyone to contribute their ideas in a clear and consistent way.
I came across this proposal for improving repository quality through structured issue forms and templates and I think it is exactly what we need. It covers bug reports, feature requests, and technical improvements, and suggests using GitHub's YAML form format so fields can be made required before submitting.
This would save time on triaging, improve consistency, and make contributions much more effective, especially when working with automated tools or AI assistants.