Skip to content

Latest commit

 

History

History
65 lines (47 loc) · 3.13 KB

issues.md

File metadata and controls

65 lines (47 loc) · 3.13 KB
Raw

Guide to Creating Effective GitHub Issues

Creating well-documented issues on GitHub helps teams communicate effectively about tasks, enhancements, and bugs. An essential part of this process is giving your issue a clear title and categorizing it properly.

Naming Your Issue:

The title of your issue should be descriptive yet concise. It should give a clear indication of the problem or feature request at a glance. Here’s a format you might consider using:

  • Bugs: [Bug] Short description of the problem
  • Feature Requests: [Feature] Short description of the new feature
  • Documentation: [Docs] Description of the documentation change
  • Other Types: [Type] Description, where type could be Refactor, Test, Chore, etc.

Differences Between Issue Types:

  • Bugs: Issues that report a problem or unexpected behavior in the project. They should include steps to reproduce the issue, the expected outcome, and the actual outcome.
  • Feature Requests: Suggestions for new features or improvements to existing functionality. Describe what you wish to achieve and why it would be beneficial.
  • Documentation: Requests or suggestions for improvements to the project's documentation. This can include missing documentation or clarifications on existing content.
  • Others: This category includes code refactoring, tests, or maintenance tasks that don't necessarily add new features or fix bugs but are essential for project health.

Creating an Issue:

  1. Navigate to the Issues tab of the relevant repository and click on "New Issue."
  2. Select a Template if applicable. Use the appropriate template for bugs, feature requests, or other issue types.
  3. Fill in the Issue Title: Use the naming conventions mentioned above to provide a clear and concise title.
  4. Describe the Issue in detail:
    • Description: Give a summary of the issue.
    • Steps to Reproduce (for bugs): Clearly list the steps to demonstrate the issue.
    • Expected Behavior: What should happen?
    • Actual Behavior: What actually happens?
    • Possible Solution: Suggest a possible fix if you have one.
    • Additional Context: Any other information, like screenshots or error messages.
  5. Submit the Issue: Review the details and submit your issue.

Simple Issue Template Example

Use the following template in your GitHub repository to streamline the issue creation process:

# Issue Template

## Description
Please provide a brief description of the problem or the feature request. Be clear and concise.

## Steps to Reproduce
For bugs, list the steps required to reproduce the issue, if applicable:
1.
2.
3.

## Expected Behavior
For bugs, describe what you expected to happen.
For feature requests, describe what feature you would like to see implemented.

## Actual Behavior
For bugs, describe what actually happened. Include any error messages or unexpected outcomes.

## Possible Solution
If you have any suggestions on how to fix the bug or implement the feature, please share them here.

## Additional Context
Add any other context or screenshots about the issue here.

Return to Contributing