Using **issue templates**

Using issue templates in GitHub ensures that issues are created with the necessary context and information to make them easier to triage, debug, and resolve. They help standardize issue reporting, improve communication, and save time. Here are best practices for creating and using GitHub issue templates:

1. Create Different Templates for Different Issue Types

Purpose: Not all issues are the same (e.g., bug reports, feature requests, or documentation updates). Having tailored templates for each type ensures that relevant information is captured.
Best Practice:
- Use multiple issue templates to cater to different types of issues such as:
  - Bug Report Template: For reporting bugs.
  - Feature Request Template: For suggesting new features or improvements.
  - Documentation Template: For reporting missing or incorrect documentation.
  - Technical Support Template: For user support or questions.
- This makes it easier for maintainers and contributors to understand the issue and take action faster.
How to Implement:
- Go to your repository.
- Navigate to the .github/ISSUE_TEMPLATE directory or create it if it doesn't exist.
- Add specific markdown files (bug_report.md, feature_request.md, etc.) to create distinct templates for different issue types.

2. Include Relevant Sections in Each Template

Purpose: Ensure that each template gathers all the necessary information required to investigate or work on the issue.
Best Practice:
- For Bug Reports, include sections like:
  - Description: What went wrong.
  - Steps to Reproduce: A clear list of steps to replicate the issue.
  - Expected Behavior: What should happen versus what actually happened.
  - Screenshots and Logs: Provide screenshots, logs, or error messages.
  - Environment Information: Include versions (e.g., OS, application version).
- For Feature Requests:
  - Feature Description: What the user is requesting.
  - Use Case: Why this feature is needed or how it benefits the project.
  - Alternatives: If they have considered other solutions.
- For Documentation Requests:
  - Page or Section: The part of the documentation that is unclear or missing.
  - Improvement Suggestion: Specific details on how to improve the documentation.
- Ensure that each template asks for essential details so that the issue is complete and actionable when submitted.

3. Keep Templates Simple and Concise

Purpose: Ensure that users can fill out the template easily without feeling overwhelmed by too many fields.
Best Practice:
- Limit the number of fields to only what's absolutely necessary.
- Use comments () in the markdown template to guide users without cluttering the final issue with instructions.
- Consider using checklists for common choices or fields (e.g., environment details or issue categories) to make it easier for users to submit issues quickly.

Example for a Bug Report Template:

 <!-- Please fill out the following information: -->

 ### Bug Description
 A clear and concise description of the issue.

 ### Steps to Reproduce
 1. Go to '...'
 2. Click on '...'
 3. Scroll down to '...'
 4. See error '...'

 ### Expected Behavior
 A brief description of what you expected to happen.

 ### Screenshots / Logs
 If applicable, add screenshots or logs to help explain the problem.

 ### Environment Information
 - OS: 
 - LinuxCnc Version:
 - LinuxCnc Configuration: [HAL and INI files]
 - Application Version: [e.g., v1.2.3]

4. Make Use of Dynamic Fields (Checkboxes, Drop-Downs, etc.)

Purpose: To make the issue templates interactive, allowing the user to provide structured responses and reduce ambiguity.
Best Practice:
- Use checkboxes to let users indicate certain conditions.
- Use tables or lists for fields like environment details or error types.
- Example for Checkboxes:
```
- [ ] I have searched the existing issues.
- [ ] I have provided sufficient information to reproduce the issue.
```
- This helps maintainers quickly review the checklist and determine the completeness of the issue submission.

5. Enforce Required Fields

Purpose: Ensure that critical information is always provided by making some fields mandatory for users to fill out.
Best Practice:
- Use HTML comments to specify which fields must be filled in.
- Leave instructions like:
```

```
- You can add validation for certain fields (e.g., prompting users to provide a description or reproduction steps) using third-party bots or custom GitHub Actions, although GitHub itself doesn’t enforce this out-of-the-box.

6. Encourage Users to Search Before Submitting

Purpose: Avoid duplicate issues by encouraging users to search the issue tracker before creating a new issue.
Best Practice:
- Add a reminder or a checklist item at the top of the template asking users to search for existing issues.
- Example:
```
- [ ] I have searched for similar issues and found none.
```
- This ensures that users attempt to find a solution in existing issues before adding redundant reports.

7. Provide Links to Documentation or Contribution Guidelines

Purpose: Direct users to resources that can help them resolve the issue themselves or guide them in making high-quality submissions.
Best Practice:
- Include links to the project’s documentation, FAQ, or contribution guidelines at the top or bottom of the issue template.
- Example:
```
For more details, check out our [Contribution Guidelines](link) and [FAQ](link).
```

8. Use Labels Automatically with Templates

Purpose: Automate the application of labels based on the type of issue template used.
Best Practice:
- GitHub allows you to define default labels for specific issue templates.
- Set a default label like bug, enhancement, or documentation based on the template used so that maintainers can easily filter and triage new issues.
- Example in the issue template frontmatter:
```
---
name: Bug report
about: Report a bug to help us improve
labels: bug
---
```

9. Regularly Review and Update Templates

Purpose: Ensure templates remain relevant as your project evolves.
Best Practice:
- Periodically review the templates to ensure they are still gathering the necessary information.
- Update templates based on common patterns you’ve seen in reported issues (e.g., if users frequently omit crucial steps in reproduction, adjust the template to highlight that section).
- Engage contributors for feedback on whether the templates are effective.

10. Combine Issue Templates with GitHub Actions

Purpose: Automate repetitive tasks or actions once issues are created.
Best Practice:
- Use GitHub Actions to trigger workflows based on specific templates. For example:
  - Automatically assign a maintainer when a certain type of issue is created (e.g., bug reports go to a specific engineer).
  - Trigger tests or CI builds if a bug report includes a reproducible test case.
- This can be configured in your .github/workflows directory.

Example of Bug Report Template:

---
name: Bug report
about: Create a report to help us improve
title: "[Bug]: <Title>"
labels: bug
assignees: ''
---

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error '...'

**Expected behavior**
A clear and concise description of what you expected to happen.

**Screenshots**
If applicable, add screenshots to help explain your problem.

**Environment:**
- OS: [
- LinuxCnc Version: 
- used LinuxCnc Configuration [HAL and INI file]
- Version [e.g., v1.0.0]

**Additional context**
Add any other context about the problem here.

Conclusion

The best practices for using GitHub issue templates ensure that contributors provide the necessary details for every issue. This results in faster resolution, reduced back-and-forth communication, and clearer context for maintainers and contributors. Templates should be simple, customized for different issue types, and automated with labels and actions to streamline the issue management process.

zarfld / LinuxCnc_PokeysLibComp