How to close issues

If you want to start a fight, bring up the topic of closing unresolved issues. People have strong opinions on this topic, and for good reason. To maintainers, open issues can be overwhelming. They represent a backlog of work that will never get done. To users, issues represent a real pain point. If bug reports reports are contributions — and they are — then opening an issue is often the first (or only) contribution a particular person will make to the project. A bad bug reporting experience is a bad contributor experience, and it may chase someone away for good.

Just about everyone would agree that there are some cases where closing an unfixed issue makes sense. Not everyone will agree on where to draw the line, though. In general, the best approach is to have a clear, well-communicated policy and to close issues with respect for the time that people put into filing them. The rest of this post has my suggestions for how to approach closing issues. You, of course, can set whatever policy you want for your project.

Types of issues and how to close them

• Spam. Close these immediately, no comment necessary. If your issue tracker supports hiding or removing issues, make these go away. They add no value except as something you might want to track.
• Duplicate. close these immediately. If your issue tracker supports linking it to the original issue, do that. Otherwise, comment with a link to the original issue.
• Invalid reports
  • Upstream bug. Leave these open with a link to the upstream bug report until a fix reaches your project. Some projects will ask the reporter to file upstream bugs themselves, but I prefer to do it myself so that I can provide project context the user might not know and because I’ll want to be informed when it’s fixed anyway.
  • Downstream bug. This is rarer than the upstream bug case, but it happens somewhat frequently in the case of distro-packaged software. In this case, directing the reporter to the downstream issue tracker in a closure message is sufficient.
  • Unsupported version. If your project has a defined support policy, you can close reports filed against an unsupported version. You can choose to close these immediately with a reference to the supported versions, but it’s friendlier to leave it open to give the reporter a chance to test a supported version.
  • Not a bug. If the issue describes intended behavior, you can close it immediately. Consider whether or not this is actually a bug in your documentation.
• Out of scope. This generally applies to feature requests more than bugs. If someone asks for something that’s not what you intend for the project, close the issue.
• Not reproducible. If neither you nor the reporter can reproduce an issue, close it. In this case, I recommend leaving it open for a period of time (say 30 days or so) in order to give other people a chance to find a reproduction case.
• Unresponsive reporter. If you lack the information necessary to address an issue and the reporter doesn’t reply to your questions, you can close the issue. As with the “not reproducible” case, you should give people a reasonable amount of time to answer. 30 days is a good starting point. Ideally, people would answer within a day or two, but they have lives just like you do.
• Stale. This is a distinct category from “unresponsive reporter” and the one most likely to make people upset. If there’s a valid report with sufficient information but no one has touched it, leave it open. Autoclosing these is not only user-hostile, but it encourages noisy behavior when people leave a comment just to keep the issue open.

Not included in the list above are resolved issues: fixed bugs and implemented feature requests. There’s no question that these should be closed. The only question is “when?” I’m partial to closing these when the fix or feature is in a shipped release. The tooling doesn’t always make that easy. Fedora has some automated connections between its update system and Bugzilla that will move reports through automatically. GitHub-hosted projects tend to close issues when a commit or pull request that says “fixes #12345” lands in the primary branch. There are ways to queue closures for when a corresponding release lands, but it tends to be more effort than most maintainers are willing to set up (myself included).

This post’s featured photo by Neringa Hünnefeld on Unsplash.