GitHub Issues

A GitHub Issue is a discussion or work item created inside a repository.

Issues can be used for:

• Bug reports
• Feature requests
• Tasks
• Questions
• Improvements

Issues provide a central place for tracking project-related work.

• Track bugs
• Record feature ideas
• Assign tasks
• Discuss problems
• Track progress
• Organize development work

To create an issue, open a repository where you have permission to create issues and use the repository's Issues section.

A new issue normally contains:

• Title
• Description
• Labels
• Assignees
• Milestones or project information when applicable

The issue title should clearly describe the problem, task, or request.

Example:

Login button does not work on mobile

A clear title helps developers understand the issue quickly.

The description contains detailed information about the issue.

For a bug report, useful information can include:

• What happened?
• What was expected?
• How can the problem be reproduced?
• What environment was used?
• Are there error messages?

Title:
Login button does not work on mobile

Description:

Steps to reproduce:
1. Open the login page.
2. Enter username and password.
3. Tap the Login button.

Expected:
User should be logged in.

Actual:
Nothing happens after clicking the button.

Issues can also be used to request new features.

Title:
Add dark mode to dashboard

Description:
Add a dark mode option to the user dashboard
so users can switch between light and dark themes.

Team members and contributors can use comments to discuss an issue.

Issue:
Dashboard loading slowly

Comment:
I tested this on the latest version.
The problem appears when there are many records.

Comments keep project discussions connected to the relevant issue.

Labels help categorize and organize issues.

Examples include:

• bug
• feature
• documentation
• enhancement
• help wanted
• question

The exact labels available depend on the repository.

Labels can make it easier to filter and understand project work.

Bug
Feature
Documentation
Priority
Question

For example, a developer can view issues labeled bug to focus on bug reports.

An issue can be assigned to one or more people when the repository settings and permissions allow it.

Assignment helps indicate who is responsible for working on the issue.

Issue
  ↓
Assigned Developer
  ↓
Work
  ↓
Resolution

Issues commonly have an open or closed state.

After the work represented by an issue is completed, the issue can be closed.

Closing an issue does not necessarily mean that the issue was fixed by a particular method. The project team can decide when an issue should be closed.

A closed issue may be reopened when further work or discussion is needed, depending on repository permissions and settings.

For example, a bug may need to be reopened if the reported problem still exists after a proposed fix.

Issues can be connected to pull requests so that development work can be associated with the problem or feature being addressed.

For example:

Issue #25
   ↓
Feature Branch
   ↓
Pull Request
   ↓
Code Review
   ↓
Merge

GitHub supports certain keywords in commit messages and pull request descriptions that can automatically close linked issues when the relevant pull request is merged.

Example:

Fixes #25

The exact behavior depends on how the issue is linked and how the change is merged.

Issues normally have unique numbers within a repository.

#1
#2
#3
#25

An issue number makes it easy to refer to a particular issue.

You can refer to an issue using its number:

#25

When used in an appropriate GitHub repository context, the issue reference can become a clickable link.

Repositories can provide issue templates to help contributors submit consistent information.

Common templates include:

• Bug report
• Feature request
• Documentation issue
• Question

## Description

Describe the problem.

## Steps to Reproduce

1. Step one
2. Step two
3. Step three

## Expected Behavior

What should happen?

## Actual Behavior

What actually happens?

## Environment

Browser:
Operating System:

GitHub provides search and filtering features for finding issues.

You can search based on information such as:

• Keywords
• Labels
• Authors
• Assignees
• Status

This is useful in repositories containing many issues.

Milestones can group issues and pull requests around a larger goal or release.

Milestone: Version 2.0

Issues:
#10 Login improvement
#15 Dashboard update
#20 Report feature

Milestones help teams organize related work.

Issues can be used together with GitHub's project management features to organize tasks and development work.

Issue
  ↓
Project Board
  ↓
Task Tracking
  ↓
Development
  ↓
Pull Request

GitHub can provide notifications for repository activity depending on your notification settings and your relationship to the issue.

Notifications can help contributors keep track of discussions and updates.

• Use a clear title.
• Explain the problem or requested feature.
• Provide steps to reproduce bugs.
• Include relevant error messages.
• Add screenshots when useful.
• Use appropriate labels.
• Avoid unnecessary information.
• Keep the discussion focused.

• Writing unclear titles.
• Not explaining how to reproduce a bug.
• Creating duplicate issues without checking existing ones.
• Providing incomplete information.
• Using irrelevant labels.
• Posting sensitive information.
• Using issues for unrelated conversations.

Title:
Add student attendance report

Description:

The application currently shows daily
attendance but does not provide a monthly
attendance report.

Requested feature:
Add a monthly attendance report with
student name, total classes, present days
and attendance percentage.

Expected result:
Admin should be able to select a month
and view the attendance report.

Create Issue
     ↓
Describe Problem
     ↓
Add Labels
     ↓
Assign Developer
     ↓
Create Branch
     ↓
Make Changes
     ↓
Create Pull Request
     ↓
Review Code
     ↓
Merge Changes
     ↓
Close Issue

• Search for an existing issue first.
• Write a clear title.
• Describe the problem or request.
• Add reproduction steps for bugs.
• Attach useful screenshots or error information.
• Use suitable labels.
• Assign the issue when appropriate.
• Link related pull requests.
• Update the issue as work progresses.
• Close the issue when appropriate.

GitHub Issues provide a structured way to track bugs, features, tasks, questions, and other project work.

Issue
  ↓
Discussion
  ↓
Task / Bug / Feature
  ↓
Development
  ↓
Pull Request
  ↓
Review
  ↓
Resolution

Using clear titles, useful descriptions, labels, assignments, and links to development work can make issue tracking easier for teams and open-source contributors.