Creating Issues#

This guide explains how to create issues and understand the different issue categories available in our issue tracker.

Issue Categories#

We have several issue templates to help organize different types of requests and problems:

Bug Reports#

Use the bug report template when you encounter something that isn’t working as expected. When filing a bug report, please include:

  • Clear description of the problem

  • Steps to reproduce

  • Expected vs actual behavior

  • Environment details (OS, version, etc.)

  • Screenshots if applicable

Feature Requests#

For suggesting new features or improvements, use the feature request template. Include:

  • Description of the problem the feature would solve

  • Detailed explanation of the desired solution

  • Any alternative solutions you’ve considered

  • Additional context or examples

Documentation Issues#

If you find problems in the documentation or want to suggest improvements, use the documentation issue template. Include:

  • Location of the issue (URL or file path)

  • Description of what’s unclear or incorrect

  • Suggested improvements

  • Any additional context

Design/UX Enhancements#

For suggesting improvements to the user interface or experience, use the design/UX template. Include:

  • Description of the current design issue

  • Proposed enhancement

  • Impact on users

  • Mockups or examples if available

Security Issues#

For reporting security vulnerabilities, use the security issue template. Include:

  • Clear description of the vulnerability

  • Steps to reproduce (if safe to share)

  • Impact assessment

  • Any suggested fixes

Support Requests#

If you need help using the software, use the support request template. Include:

  • Clear description of what you’re trying to do

  • What you’ve already tried

  • Your environment details

  • Any relevant error messages or screenshots

Task/Management#

For project management and general tasks, use the task template. Include:

  • Clear task description

  • Specific objectives or deliverables

  • Timeline if applicable

  • Dependencies or blockers

  • Required resources

CI/CD Issues#

For issues related to continuous integration or deployment, use the CI/CD template. Include:

  • Affected workflow or pipeline

  • Current behavior

  • Expected behavior

  • Build logs if relevant

  • Proposed changes

Best Practices#

When creating an issue:

  1. Choose the Right Template: Select the most appropriate template for your issue type.

  2. Be Specific: Provide clear, concise descriptions and include all requested information.

  3. One Issue Per Report: Create separate issues for separate problems or requests.

  4. Search First: Before creating a new issue, search existing issues to avoid duplicates.

  5. Follow Up: Monitor your issue for questions and provide additional information if requested.

  6. Labels: Pay attention to the automatically applied labels, and add additional ones if needed.

Issue Labels#

Common labels you might see on issues:

  • bug: Something isn’t working as expected

  • enhancement: New feature requests or improvements

  • documentation: Related to documentation

  • design: UI/UX related issues

  • security: Security-related issues

  • question: Requests for help or clarification

  • task: General project management items

  • ci-cd: Continuous Integration/Deployment related

Updating Issues#

When working on or following up on an issue:

  1. Use comments to provide updates or ask questions

  2. Reference related issues or pull requests using # followed by the issue number

  3. Use checkboxes (- [ ]) to track subtasks

  4. Close issues when they’re resolved

  5. Use reactions (👍, etc.) to show agreement rather than writing “+1” comments

Getting Help#

If you’re unsure which template to use or need help creating an issue:

  1. Start with the support request template

  2. Ask in our community channels

  3. Reference our documentation

  4. Contact the maintainers

Remember that well-written issues help maintainers understand and address your needs more effectively.