Skip to main content

GitHub Issues

Welcome back to Bite-Sized! In this episode, Fabian and Timnah introduce you to GitHub Issues, a core feature for tracking tasks, reporting problems, and discussing ideas directly within a GitHub repository.

Why Use Issues?

Issues help you keep work visible and organized. They make tasks, questions, and decisions transparent for everyone involved in a project.

Effective Issue Management

Unclear or outdated issues can quickly pile up. Write focused issues and close them once they're resolved!

What is an Issue?​

A GitHub Issue is a discussion thread associated with a repository. Issues can be used to:

  • Report bugs or problems
  • Propose new features or improvements
  • Track to-do items and project tasks
  • Ask questions or start discussions
  • Document decisions and project progress

Each issue has a title, a description written in Markdown, and a unique number. Issues remain part of the repository’s history, making them well suited for open and collaborative work.

When to Use Issues:​

  • Report bugs or unexpected behavior.
  • Suggest new features or improvements.
  • Track to-do items and project tasks.
  • Ask questions or start discussions.
  • Document decisions and project progress.

Creating a New Issue​

  1. Navigate to the Issues tab of the repository.
  2. Click “New issue”.
  3. Add a clear, concise title.
  4. Describe the problem, task, or idea in the issue body.
    • Explain the context.
    • Describe what needs to be done or discussed.
    • Add links, code snippets, or references if helpful.
  5. Submit the issue.

Managing Issues​

  • Use labels to categorize issues (e.g., bug, enhancement, question).
  • Assign issues to team members responsible for addressing them using assignees.
  • Use milestones to group related issues for larger projects or releases.

Discussing and Closing Issues​

Issues are designed for discussion:

  • Team members can comment on issues to discuss details, ask questions, or provide updates.
  • You can reference issues in commits and pull requests by using #issue_number.
  • Once an issue is resolved, it should be closed to indicate completion.

Best Practices for Issues​

  • Write issues from the perspective of someone unfamiliar with the project.
  • Use templates for common issue types (e.g. bug reports or task descriptions).
  • Break down large tasks into smaller, manageable issues.
  • Link issues to related pull requests for better traceability.
  • Close issues when they are resolved to keep the issue tracker clean.

Further Resources​

If you want to learn more about GitHub Issues, check out the official documentation.

What's Next?​

GitHub Issues integrate closely with pull requests. In the next Bite-Sized video, you’ll learn how to link issues to code changes and automatically close them when work is completed.

Thanks for watching and happy collaborating!