Documentation/content/getting-started/issue-tracking-basics.md

---
eleventyNavigation:
  key: IssueTrackingBasics
  title: The Basics of Issue Tracking
  parent: GettingStarted
  order: 40
---

Issues are an important mean of communication on Codeberg.
Besides their original purpose - reporting bugs to a project's maintainer -
they can be used to suggest enhancements, ask for new features, discuss a project's
direction, ask questions and much more.

### The Issue Tracker
<picture>
  <source srcset="/assets/images/getting-started/issue-tracking-basics/issues-list.webp" type="image/webp">
  <img src="/assets/images/getting-started/issue-tracking-basics/issues-list.png" alt="Issues List">
</picture>

You can find the issue tracker of a project by clicking its "Issues" tab (1).

There, you will see browsable and filterable (2) list of all issues.
Many projects use labels to categorize issues. A good label to look for, if you want
to contribute to a project is the "help wanted" label.

You can switch between issues that are still open, and those that are already resolved (3).

Some projects define milestones (4), to which issues can be assigned. They are good for
visualizing the high-level progress of a project's development.

You can create an issue by clicking on the green "New Issue" button (5) at the top left
of the issues list.

Issues in the issue tracker are public and everyone is able to read and answer to them.

An Issue can have an assignee, meaning someone responsible for resolving or moderating
the issue. Their profile picture, with a link to their profile, can be seen in the issue
list.

### Life of an Issue
Once an Issue in the Issue Tracker has been created, it will usually pass through a
process of review, discussion and closure, which is sometimes more, sometimes less
strictly defined, based on the project you're contributing to.

The first thing that might happen is that your issue is categorized using labels.
Your issue may be reviewed by the project's maintainer(s) and evaluated whether it i.e. might be a duplicate or an invalid bug report.

Then, depending on what kind of issue it is, there might be additional questions
or a discussion and, if applicable, the implementation of a solution (or the rejection of
the issue).

Finally, the issue is closed, thus vanishing from the list of open issues.
Issues might have dependencies on other issues or pull requests preventing them from being closed.

Occasionally, issues might become stale. That's when there hasn't been any progress for
an extended period of time (usually months). You might consider reviving these, if there
is a strong interest in getting them resolved (and, preferably, if you can contribute
something to them).

> If you encounter an abandoned project and there is no way to contact the maintainer(s),
> consider forking it, if you want to assume responsibility for it (or, rather, your fork).

### Things to consider
#### Security bugs
If the bug you have found has security implications, **do not create
an issue right away!** Instead try contacting the project's maintainers privately.
Many projects have a dedicated e-mail-address for reporting security bugs. If the
project in question doesn't, consider writing an email directly to the project's
maintainer or ask for the address in the issue tracker.

> **⚠** What's important is that you **don't publicly expose security bugs before they are
> fixed *and* the fixes are deployed** because **otherwise you might put the users of that
> project at severe risk**.

#### Existing issues
Before creating a new issue, please make sure that there isn't already an existing
issue covering i.e. the bug that you want to report or the feature that you want to
request.

If there already is an existing issue, please consider commenting that issue instead,
if there is something more that you can contribute to it.

You should also make sure that the issue has not already been solved by having a look
the closed issues (3) as well.

#### Try to be precise and helpful
Project maintainers love precise information about why i.e. a bug is happening.

Some projects may even have templates that specifically ask for information like
the operating system or database software used.

If you can provide that information, it will be easier for the project maintainer(s)
to quickly resolve your issue. And if you want it resolved even quicker,
consider writing a Pull Request solving the issue (if possible).

#### Be (reasonably) patient
Please remember that many project maintainers work on their free software projects
in their free time. Some maintainers may answer you within minutes, others within days.
Don't be discouraged if there isn't an immediate answer.