The Basics of Issue Tracking

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

Issues List

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.

Hey there! 👋 Thank you for reading this article!

Is there something missing or do you have an idea on how to improve the documentation? Do you want to write your own article?

You're invited to contribute to the Codeberg Documentation at its source code repository, for example by Adding a pull request or joining in on the discussion in the issue tracker.

For an introduction on contributing to Codeberg Documentation, please have a look at the Contributor FAQ.

View History View Source