What Is Open Source Triage?

When you think of an open source maintainer, you likely imagine someone writing code, releasing new versions, and fixing bugs. But that's only the most visible part of the job. Hidden underneath the sweat, tears, and commits is the equally demanding task of interacting with the humans using your project.

That interaction plays out primarily in issue trackers, where a popular project may have hundreds or thousands of open issues from people who were driven by something to reach out. That something which drove them to the issue tracker is often a problem they've encountered: an error message, a question, a possible bug, or something else blocking them from accomplishing what they want with the software.

The interaction between users and maintainers is at the heart of open source software, and issues can offer a lot of value to a project. However, not every issue is actionable or useful for the project. The only way to find out is to read the issue and assess its content.

That's where triage comes in. It's a special type of maintenance work. Triage is sifting through the artifacts of humans’ interaction with an open source project, and categorizing and cleaning up those artifacts. That way, the most important ones can be used to improve the project.

Triage is an essential part of maintaining a project, but it doesn't have to be done only by the people writing code for the project. You can volunteer to triage for a project even if you're not one of the maintainers. Having others help with triage frees up maintainers to spend more of their time working directly on the project.

How do you triage?

So in practice, what does "sifting through artifacts" actually mean?

Every project will have different needs or approaches to triage, but some of the most common duties are to:

  • Label or add tags to issues
  • Respond to and follow up on new issues or comments
  • Verify bug reports by attempting to reproduce them
  • Request more information when an issue is opened without enough detail
  • Improve the issue description
  • Close stale, resolved, or invalid issues/PRs
  • Bring maintainers' attention to common problems

Triage is often associated with verifying bug reports. While that's a critical part of triage work, it doesn't represent all the work that needs to be done. Bug reports can be a fraction of the issues that get submitted to a project. There is a lot of value that triage can provide outside of looking after bug reports.

A first pass through a project usually involves looking at old issues and closing them if they're stale or no longer relevant. When to close an unresolved issue can be subjective, but there's no need to keep old issues open if they're not going to be worked on. With most issue trackers, an issue can always be reopened if it becomes relevant again.

From there, you can add labels to any unlabeled issues. Common labels might be "question", "waiting for more info", "bug", "feature request", or some variation on those. Labeling makes groups of issues easier to find in the future, and can provide much-needed structure.

Once that's done, you can start to go through what's left: updating labels on existing issues as appropriate, requesting missing information or reproduction steps in issues, attempting to reproduce reported bugs, or reviewing open pull requests.

Triage never really stops -- it's about upkeep over time, so a triager will rotate through these tasks as the need arises.

Why triage matters

Triage is not glamorous work -- it's more a type of hygiene for a project. But it provides real benefits.

The goal of triage is to surface information for use by yourself or maintainers to improve the project. By sifting through what is happening in the project, you'll uncover valuable information that needs to be categorized and made visible. It improves the efficiency of everyone working in the project by refining the quality of information available to them.

When contributors know what bugs are in the code or what features are most requested they can better prioritize their work.

Ideally, an issue queue should only contain productive or informative issues. In reality, that doesn’t happen by itself. Triage is the process that gets you there.

An empathetic view

Triage is the human touch that benefits both users and maintainers. It goes a long way towards reducing the risk of burnout commonly experienced by maintainers in open source. Projects bursting at the seams with uncategorized issues or pull requests can be overwhelming for any contributor.

Triage benefits users who open issues or pull requests by letting them know someone is paying attention. Seeing activity happen on their issue helps users feel heard, even if the issue eventually gets closed. Ignored users won't contribute back to the project, which starves a project of the community it needs in order to improve.

Benefits for triagers

In all seriousness, triaging is a great way to deepen your understanding of a project and make meaningful contributions. It exposes you to different ways people are using a project, edge cases you've never noticed, and common user mistakes.

Triaging leads to familiarity with a codebase. To reproduce bugs or answer questions, you'll have to dive into the source code from time to time.

With that deeper understanding of a project, and how people (mis)use it, you'll identify opportunities to improve the project through new features, bug fixes, or clarifying the documentation. Triage can be a great path towards major code contributions to a project. If you're looking to get seriously involved with a long-term project, starting off with triage is a way to take on responsibility while still learning the ropes.

Although "soft" contributions like triage are not considered as high-profile as creating the next hit framework, they can be incredibly impactful for a project and its community. It’s a valuable way to contribute to a project, and also a great way to get involved in open source.

Triage isn't tech support

One final aside: We believe the goal of triage should be first and foremost to help the maintainers. Triagers should not be expected to provide free debugging and tech support for someone's application.

The triager's role is to ensure a project can get the most value out of the issue queue, and they should prioritize those needs first. The energy put into individually helping people through common problems is better spent improving the documentation so more users don't run into the same problem.

That said, it's perfectly fine to help users diagnose and fix their problems if you'd like to! But exhaustive tech support should not be expected of triagers.

Sounds great -- now what?

At its heart, triage is focused around the people who make and use open source software.

It is a great way to contribute back, and can be well worth the time investment. Triage is most effective when it's done regularly, so making it a habit and sticking to it will yield the best results.

If you're interested in implementing triage in your own project, or becoming a triager, here's some good resources to help you get you started: