GitHub Issues

Not everything in a software project is visible directly in the code. You may need to record a bug, plan a new feature, or keep track of a task that should be handled later.

GitHub provides Issues for this purpose.

You can think of an Issue as a task card or problem record attached to the repository.

A project might have Issues such as:

Login button does not work on mobile
Add dark mode
Improve search speed
Update installation documentation

An Issue is not code. It simply describes:

Something in the project needs attention.

What Are Issues Used For?

Common uses include bugs, feature requests, and development tasks.

For a bug, an Issue might look like:

Title:
Login button does not work on mobile

with a description such as:

The login button cannot be clicked on small screens.

Steps to reproduce:
1. Open the login page on a phone
2. Enter email and password
3. Tap the login button

Expected:
The user should be logged in.

Actual:
Nothing happens.

This gives another developer enough information to understand and reproduce the problem.

Issues can also describe new features:

Add dark mode

or simple tasks:

Update README installation steps

Creating an Issue

Open the repository's Issues page on GitHub and create a new Issue.

The title and description are usually the most important parts.

A useful title is specific:

Fix broken login button on mobile

A vague title such as:

There is a problem

is much less useful.

The description can include context, reproduction steps, expected behavior, or any other information that helps someone understand the task.

An Issue does not need to be long or complicated. It simply needs to make the work clear.

What Is an Assignee?

An Issue can be assigned to a person.

For example:

Issue: Fix login button
Assignee: Alice

This tells the team that Alice is responsible for the task.

For a personal project, assigning Issues may not matter much. In a team, it makes ownership clear.

What Are Labels?

Issues can also have labels.

Common examples are:

bug
feature
documentation
help wanted

For example:

Fix login button
Label: bug

and:

Add dark mode
Label: feature

Labels become especially useful when a repository contains many Issues and you want to filter them by type.

Starting Development from an Issue

A natural team workflow often begins with an Issue.

Suppose the Issue is:

#25 Add dark mode

A developer may create a branch:

feature/dark-mode

and start working:

git switch main
git pull
git switch -c feature/dark-mode

After finishing the work:

git add .
git commit -m "Add dark mode"
git push -u origin feature/dark-mode

Then the developer opens a Pull Request.

This creates a clear chain:

Issue → Branch → Commit → Pull Request → Merge

Linking a Pull Request to an Issue

A Pull Request can reference an Issue.

For example, you can write:

Closes #25

in the PR description.

Here:

#25

refers to Issue number 25.

When the Pull Request is merged, GitHub can automatically close the linked Issue.

Other common forms include:

Fixes #25

and:

Resolves #25

This connects the reason for the work with the code that solves it.

Why Are Issues Useful?

Imagine someone casually says:

The login page seems broken. We should fix it later.

If that message only exists in chat, it can easily be forgotten.

If the team creates:

#31 Login page fails on Safari

the problem stays visible in the project until someone resolves and closes it.

That is why Issues are useful not only for bug reports, but also as a lightweight project tracking system.