How to Triage Open Source Issues

Issue triage is the maintainer practice of sorting new and existing issues into clear next steps. A triaged issue might become an accepted bug, a duplicate, a support redirect, a feature request, a documentation task, a security escalation, a contributor-ready issue, or a respectful closure.

Good triage protects maintainer attention. It keeps actionable reports visible, prevents support questions from filling the development queue, and gives users a clear answer when the project cannot take the work.

Start with the issue's job

The first triage question is not "Do we like this issue?" It is "What kind of work is this asking the project to do?" A crash report, installation question, design proposal, vulnerability report, stale package request, and duplicate feature idea all need different handling.

Classifying the issue early prevents every report from competing in the same queue. It also helps maintainers answer consistently. A bug may need reproduction. A support request may need a discussion thread or documentation link. A security report may need a private disclosure path.

Do not make users guess the classification. If the issue is being redirected, explain why and where the next step belongs.

Separate common issue types

Most open source trackers need at least these categories:

• Bugs: behavior differs from expected or documented behavior.
• Regressions: behavior worked before and now fails.
• Feature requests: proposed new behavior, workflow, platform, or API.
• Documentation gaps: users cannot install, upgrade, configure, or contribute because information is missing or stale.
• Support questions: users need help using the software, not necessarily a code change.
• Security reports: possible vulnerabilities, unsafe defaults, exposed secrets, or abuse paths.
• Duplicates: existing issues already cover the report.
• Maintenance tasks: refactors, dependency updates, tests, build fixes, or release work.

The labels can differ by project. The important part is that the category maps to an action.

Use labels that change decisions

A label set should be small enough to maintain and meaningful enough to route work. Labels such as bug, needs reproduction, support, security, duplicate, good first issue, and blocked can be useful when maintainers agree what each means.

Avoid labels that decorate issues without changing behavior. If no one acts differently when a label is applied, the label probably adds noise. GitLab's triage tutorial emphasizes deciding criteria for type, severity, and priority before creating the labels; that sequence is useful beyond GitLab.

Labels should not replace comments. If an issue is closed as unsupported, add a short reason. If it needs information, say what information is missing. If it is a duplicate, link the canonical issue.

Decide what evidence is required

Actionable issues usually need enough evidence for someone else to continue the work. For bugs, that might include version, platform, steps to reproduce, expected behavior, actual behavior, logs, screenshots, sample files, or a reduced example.

For feature requests, evidence may include the user problem, affected workflow, alternatives considered, compatibility risks, and maintenance cost. For documentation issues, evidence may be the confusing page, missing command, stale screenshot, or repeated support question.

Do not demand excessive information for simple issues. A typo does not need a system profile. A crash usually does. The evidence requirement should match the work.

When information is missing, ask for the next smallest useful piece of evidence. A maintainer might request the exact version and operating system first, then reproduction steps if the report still looks current. Asking for every possible detail at once can discourage a valid reporter and fill the thread with data no one needs.

Evidence requests should also say what will happen next. "Please add a minimal reproduction; without one we cannot tell whether this is a project bug or an environment issue" gives the reporter a reason to respond. If the project will close the issue after a period without the required detail, say that plainly and apply the rule consistently.

Route support away from the development queue

Support requests are not bad issues, but they can consume the tracker if every usage question stays open as development work. If the project has discussions, forums, chat, documentation, or paid support, route support questions there.

The redirect should be respectful. "This tracker is for actionable bugs and project work. Please ask usage questions in the discussion forum, and include version and platform details" is clearer than "not a bug."

If the same support question appears repeatedly, create or update documentation. Repeated support is often documentation debt in disguise.

Treat security reports differently

Security-sensitive issues should not be handled as ordinary public support. If an issue describes a vulnerability, exposed secret, exploit path, unsafe default, or private data exposure, route it to the project's security policy or responsible disclosure channel.

Do not ask the reporter to post exploit details publicly. Do not promise severity, fix timing, or impact before review. The first triage decision is where the report belongs and who can safely evaluate it.

If the project has no security contact, triage will expose that gap. Add one before the next incident if the project has users who depend on it.

Duplicate handling

Duplicates should reduce noise without making reporters feel ignored. Link the existing issue, explain that related discussion should continue there, and mention whether the new report adds useful evidence.

Sometimes a duplicate contains new platform details, logs, or reproduction steps. Preserve that evidence by copying a summary to the canonical issue or linking the duplicate before closing it.

If several duplicates appear, improve the title, labels, or documentation around the canonical issue so users can find it before opening another report.

Stale and blocked issues

Stale issues need judgment. Old issues are not automatically invalid, but a queue full of uncertain old work makes the project hard to read. Review whether the issue is still reproducible, still in scope, still awaiting reporter information, or still blocked by a decision.

Use closure language that explains the condition. "Closing because the requested logs were not provided and we cannot reproduce this on supported versions" is better than a silent stale bot close.

Blocked issues should say what blocks them: design decision, missing maintainer, upstream dependency, security review, platform support, or funding. A blocked label without context is just another stale queue.

Stale handling is especially sensitive for bugs that affect older releases. If the project still supports the affected version, the issue may need renewed reproduction rather than closure. If the version is no longer supported, the issue can point users to the supported upgrade path without implying that the old report was wrong.

For long-running feature requests, separate "popular" from "accepted." Many comments may show user demand, but maintainers still need to decide whether the request fits the project, can be maintained, and has someone available to design and review it. A clear "not planned" closure is often kinder than leaving a request open for years.

Contributor-ready triage

An issue is contributor-ready when it has scope, context, expected outcome, and a reviewer. A small bug can be a poor starter task if it needs hidden architecture knowledge. A documentation fix can be a strong starter task if the page, problem, and preview command are clear.

Before applying a newcomer label, check:

1. The issue is current.
2. The expected change is narrow.
3. The relevant files or docs are named.
4. Acceptance criteria are visible.
5. A maintainer can review the work.
6. The issue does not require private access or unresolved design authority.

Labels that invite contributors must be maintained. Stale starter issues damage trust.

Automation without hiding judgment

Templates, saved replies, label rules, issue forms, and bots can reduce repetitive work. They can ask for version details, mark missing information, link support channels, or flag stale issues.

Automation should make maintainer judgment easier, not disappear it. A bot can request reproduction steps, but a maintainer still decides whether the issue is important. A stale bot can identify old issues, but maintainers should define when automatic closure is fair.

Review automation regularly. If users keep fighting the template, the template may be asking the wrong questions.

Weekly triage pass

A weekly or regular triage pass does not need to solve every issue. It should move issues into clearer states.

During a pass:

• scan new issues for security-sensitive reports;
• label bugs, support, documentation gaps, and feature requests;
• ask for missing evidence;
• link duplicates;
• identify issues ready for contributors;
• close issues outside scope with a reason;
• note blocked issues with the blocker;
• escalate release, security, or maintainer-capacity risks.

The expected result is not an empty queue. It is a queue that tells maintainers and contributors what can happen next.

Priority and severity are different decisions

Severity describes impact. Priority describes when the project should act. A crash that affects a rare unsupported configuration may be severe for one user but low priority for the project. A small documentation bug may be low severity but high priority if it blocks every new contributor from setting up the project.

Keeping those decisions separate reduces arguments in the issue queue. A triager can acknowledge that a report is serious while still explaining that it is blocked by missing evidence, unsupported platform status, or release timing. Likewise, a small issue can be moved quickly when it is easy to fix and affects many people.

If the project uses severity labels, define them. "Critical" might mean data loss, security exposure, broken installation, or a release-blocking regression depending on the project. Without definitions, severity labels become a way for users to compete for attention rather than a tool for maintainers.

Preserve useful context when closing

Closing an issue does not mean deleting its value. A rejected feature request may contain a good explanation of a user workflow. A duplicate bug may include a new operating-system detail. A support thread may reveal a missing documentation step.

Before closing, decide whether any information should be moved to another issue, a discussion, a documentation task, or a roadmap note. Link the destination so future readers understand what happened. This keeps the tracker smaller without throwing away signal.

Good closure comments are short, specific, and reusable. They name the reason, point to the next place if one exists, and avoid debating the reporter's intent.

Issue triage matrix

Triage checklist

Before leaving an issue:

1. The issue type is clear.
2. Missing evidence is requested specifically.
3. Security-sensitive material is routed safely.
4. Support requests are redirected respectfully.
5. Duplicates link to the canonical issue.
6. Contributor-ready labels are used only when review is available.
7. Closure explains why the project is not taking the work.
8. Repeated confusion becomes documentation or template work.

Issue triage is successful when the tracker becomes easier to act on. Maintainers do not need to accept every request, but they do need a repeatable way to decide what each issue is asking for.