It’s okay for a software project to have a lot of open issues. It’s okay if you’re not able to triage issues, let alone close them. It’s not okay to use stale bots.

What’s a stale bot?

In a bug tracker1, a stale bot is an automated process that marks an issue as “closed” after a period of inactivity.

If you’re using a piece of software and want to report an issue on a bug tracker, this is how you may end up meeting a stale bot:

  1. You find the bug tracker for the software you’re using, and file a new issue.
  2. Nobody seems to read your report or post any answer. That’s frustrating, but people are busy, and they’re usually not paid to handle your issue.
  3. After a few weeks or a few months, a “bot” account adds a comment on your issue to say that it’s “stale”, and closes the issue or announces that it will be closed soon.

As a user, meeting a stale bot is often a frustrating experience.

Mismatched mindsets

For a user creating an issue in a software project, that issue is strongly related to the software and their experience of the software.

They ran into a bug, or didn’t understand an API. They may be blocked in their work, or will need extra time to find a workaround. And as long as their experience doesn’t improve, the issue remains relevant; it cannot be “stale”.

For a project maintainer, issues are artifacts that are only loosely related to the software.

Issues are often unclear, lack context and steps to reproduce. Just figuring out how the issue relates to the software is a task in and of itself. As time goes by, it becomes very unlikely than whoever opened the issue will come back to reply to requests for information.

For the maintainer, the issue-as-artifact may grow “stale”, hardly actionable in the first place and becoming less so as time goes by. Surely closing that issue automatically makes sense?

Well. Now you have a communication problem.

From your vantage as a maintainer, you are discarding an artifact. From the reporter of the issue, you are deciding against the possibility of fixing or improving the software.

And if bridging this perception gap is hard, automating it — using an impersonal form of one-way communication — will only make it worse.

It might be fine, and indeed useful, to close a vague report where the reporter never replied to requests for information. But when you’re auto-closing issues, you’re also closing issues with good steps to reproduce, screenshots, comments, investigations from users and reduced test cases.

Auto-closing information-rich issues tells users that their efforts — because it does take time and focus to make a good report — are not valued.

Stale bots break your bug tracker

By sweeping dirt under the rug, you have created new UX issues for users of your bug tracker.

If you needed another reason besides users thinking it’s annoying and insulting, take a good look at the bug trackers of projects that auto-close issues after 3, 6 or 12 months.

The list of issues for their GitHub repository may look nice — a few hundred open issues, a few thousand closed issues, good job! — but the actual experience of using that bug tracker is now significantly worse.

First, users can end up on one of your issues from any external source: a link from another repository, a URL in source code, a link in StackOverflow or in a search result page. They may want to know things like:

  • I am holding the software wrong?
  • Is it a known limitation or bug?
  • Was there a recent fix that I could upgrade to?
  • Any workarounds I could use?

The main signal answering those questions is the bug status. Is it green for “Open” or purple for “Closed”?2

On a repository that closes issues as “stale”, you have to scroll to the bottom of the issue to figure out if “Closed” means “fixed”, “will not fix” or “we’re arbitrarily hiding this issue from the main list”.

Which leads us to our second UX issue: auto-closed issues don’t appear in search results.

Now, when a user tries to report an issue and searches the existing issues, as your contributing guidelines say they should, they will not find that identical issue which was auto-closed3.

This leads to more duplicates in your repo. Now everyone is going to waste time:

  • Maintainers may redo a lot of the triaging and investigation work that was done 6 months or one year earlier on the auto-closed issue.
  • Reporters are wasting the time spent reporting an issue, following the many steps in the issue template, making screenshots and reduced test cases.

I’ve seen repos where common problems were reported at least 3 times, with the latest report linking to a “stale” closed issue, itself linking to a previous “stale” issue. What a mess.

Why projects use stale bots

One reason is brand management.

Companies with public bug trackers want to look like they’re on top of bug fixes and feature requests. Open-source projects striving for adoption or looking for sponsorship are aware that some in the software community see a large issue count on GitHub dot com as a marker of a “dead” project.

Stale bots will sweep that dirt under the rug. But while that improves the very first look at a repository,

Meanwhile, large open-source projects like Chromium or Firefox have hundreds of thousands of open bugs in their bugs trackers, and few people bat an eye. Maybe it helps that those projects are not using GitHub4.

Here the solution is simple, but hard to make peace with: don’t artificially reduce issue count. If you need to signal that your project is active, there are other ways.

Alternatives to stale bots

Okay, so you agree that stale bots have big downsides. Still, your project got a bunch of users and you are overwhelmed by way too many issues. What else can you do?

  1. Nothing

    Accept that large projects will have thousands of open issues. It’s fine.

  2. Triage

    Set up a process to qualify issues. The goal is to curate a subset of issues that can actually be worked on.

  3. Project management

    Decide what to work on. Have a roadmap, prioritize high impact, do paper-cuts and/or stability projects.

Every step builds on the previous one. You will need people and work for all steps after the first one.

If you have declared triage and project management bankruptcy5, auto-closing issues won’t fix that.

If you can’t improve your process, then I suggest you stop at step one. Just don’t use a stale bot.

  1. Bug trackers or issue trackers are websites where users of a piece of software can report issues they’re running into, and often voice suggestions for new features. ↩

  2. Other bug trackers have richer statuses, but we’ll focus on GitHub given that’s where most stale bots are lurking. ↩

  3. Some will suggest that maintainers and users of the software can just remove the is:open search filter that GitHub sets by default. But only a fraction of users will do that. It’s more efficient to not create a problem in the first place. ↩

  4. GitHub might be responsible for half of the idea that a project with many open issues is “dead” or somehow “bad”, thanks to their decision to put counts of open issues and pull requests on every single page of their bug tracker. ↩

  5. Maybe because you’re running an open-source project with not enough funding compared to its user base. ↩