===============
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.