Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add bug triaging process #175

Merged
merged 1 commit into from
Feb 21, 2025
+36 −0
Merged

Add bug triaging process #175

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions content/community/4.reporting-and-support/2.bug-reporting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,39 @@ If you're experiencing issues or think you have found a problem in Directus, be
If you happen to run into a bug, please post an issue on [our main GitHub issue board](https://github.com/directus/directus/issues).

Please be as detailed as you can in the bug report, we ask within the template to include details on how to reproduce your issue as well as which version, hosting strategy, and database you are using. The more information available, the easier it is for other contributors to help you find a solution. For example, it might be worth adding a schema snapshot file or a database dump.

## Bug Triage Process

We follow a structured process to evaluate and prioritize bugs effectively. Each issue is assessed based on its severity, impact on users, and alignment with our roadmap. We manually review each issue to ensure critical issues are addressed promptly while maintaining a sustainable balance between bug fixes and new feature development.

When a new bug report is opened, we go through the following steps:

1. **Check if this is a known issue**
If this issue describes an already open issue, or is a different symptom of the same problem, we close the new issue and update the existing issue with a link to the duplicate.
1. **Confirm there's enough information to reproduce the issue**
A bug that can't (easily) be reproduced is exponentially harder to resolve. To make sure an issue is an actionable item, we request the poster to describe the issue in as much detail as possible. If there's not enough information available to reproduce or triage the issue, we add a `Needs Info` label and request the original poster for more information. If no additional information is provided within a week of opening the issue, it gets closed.
1. **Label the issue**
Proper labeling is crucial in keeping an overview of all the known issues. Every issue should have the following labels attached before it's moved to the backlog:
**Scope** — What part of the project is this related to?
(**Core Area**) — What feature area of the studio or engine is this related to?
**Severity** — How does this impact the running state of Directus?
**Impact** — How many users does this affect?
**Frequency** — How often do users run into this problem?

The core maintainers determine what to prioritize based on a weighted matrix of severity, impact, frequency, and level of effort to resolve.

## Backlog Grooming Process

Not every reported bug is kept in our backlog. Doing so is counterproductive for several reasons. An every-growing backlog becomes increasingly difficult to manage, making it harder to focus on what truly matters. When developers face a list of hundreds or even thousands of issues, important bugs can get lost in the noise, and the sheer volume can be demoralizing for maintainers and contributors. Many low-impact bugs also become irrelevant over time as features change or code gets rewritten, yet they continue to consume bandwidth during triage and planning. Additionally, maintaining the backlog requires ongoing effort — each bug needs to be periodically reviewed to ensure it's still relevant, reproducible, and correctly prioritized. By being selective about which bugs we track, we can maintain a focused, actionable backlog that helps us effectively improve product quality rather than drowning in a sea of minor issues that may never be worth fixing.

We close out unresolved issues in the following situations:

- It's a duplicate of another (open) issue
- It has gone without activity in 3 months and is medium or lower priority
- It has a low severity and impact score and takes a lot of effort to fix

An issue being closed does not mean we think it's not a valid bug.

## Contributing

We accept Pull Requests (PR) for any open issue. If you'd like to implement a PR for a closed issue, please leave a comment on the closed issue first. For more information on opening PRs, please refer to our [docs on Pull Requests](https://directus.io/docs/community/contribution/pull-requests).