8 AM. Like any other day, I take a quick glance at my GitHub notifications via Octobox.
- “Problem”
- “Doesn’t work”
- “Broken”
- “Failure”
- “Error”
- “Bug”
- “Doesn’t work”
- “Crash”
- “Can’t build”
- “Install failed”
- “Not working”
- “Help”
- “Does not compile”
- “Bug”
- “Not connecting”
- “Problem”
Perfect. Nothing special.
The vast majority of open source projects were born the same way. A desire to quickly solve a personal need, or to learn something.
Why not make the code public? It may be useful to other people and having the code archived and indexed by GitHub is convenient.
The first lines of code have been written. That code is not pretty, but it partially solves the initial problem already. Time to push it to GitHub. That feels like a great achievement.
The issue tracker may quickly start to fill in. “Thank you, this is exactly what I needed” would be a heartwarming thing to read, but you will never see such a comment ever. Most likely:
“It doesn’t work.”
Obviously, the project DOES “work.” You’ve been using it daily for a couple days already, and it does exactly what you wanted it to do.
The reporter may not have been able to install it, to configure it the way they wanted, or to use it to solve a different problem than yours.
They are actually asking for free support services. In the real life, explicitly asking for help feels natural. It may even start with “hello” and end with “thank you.”
In the GitHub issue tracker, we don’t call for help. We complain about something we tried to do, and that “didn’t work.”
Certainly, this is an issue tracker. This is a place to complain, not to provide positive feedback.
However, what is often overlooked is the psychological impact this can have.
Every new filled issue is akin to a new item in a “todo” list for the project developer. It has to be handled in some way. By reading and trying to understand it, and by responding to it in order to solve a stranger’s issue. This alone, puts some mental pressure. Watching a list of open issues grow is stressful. It feels like a never-ending todo list that you never really asked for, and whose resolution is not going to improve your own issues.
The vast majority of these support tickets are negatively formulated. If a user didn’t manage to install the software on their device, they will call it a bug. If there’s a syntax error in their configuration file, they will report that “it crashes.” Everything else is a “problem,” “doesn’t work” or “fails.”
While it was certainly not the intent, this overwhelming negativity has consequences. It makes developers gradually feel like shit. Their software is just a pile of junk that cannot do anything but fail.
As the number of projects you release as open source grows, the number of issues grows as well. Complains keep coming even for projects you don’t really use any more. Can these issues be ignored? Every time you make a new project public, you sign an implicit contract with “the community” to support it, forever. And support is not much about bug fixes than helping users solve problems you never had yourself, whose root causes are often completely unrelated to your very projects.
A report for an actual bug, something that can be easily reproduced on an already running successful installation of the software, and that also affects the developers, is immensely welcome. Unfortunately, these are pretty much nonexistent.
Adding categories and templates doesn’t help. “It doesn’t work” calls to solve individual problems will eventually end up in categories you may expect actual bug reports in. So, you still need to check what’s behind every “doesn’t work” description in case a real bug report would hide in there.
Behind some of these “doesn’t work” issues are anonymous company employees, opening issues with accounts having no activity on GitHub besides opening support and “feature requests” tickets. With “thumb up” votes from similar accounts appearing right after the post. “Doesn’t work. We are waiting for a solution.” If this is not a “doesn’t work” ticket, this is a command: “Tag a new release. This is blocking our processes.”
There is no “we.” I am not part of your team, nor am I supposed to do the work you are being paid for, no matter if you somehow use one of my projects or not.
There’s a sense that installing free software grants the ability to get free support from their maintainers. And to some extent, it does. Because it’s hard to say “do your homework” and close the ticket. Every closed ticket needs a justification. Which will live forever in the issue tracker history, and that people are going to look at, even years after the fact. So, you may have to keep solving users’ problems, even if they are completely unrelated to the way you run the software yourself.
“Doesn’t install on the Titan framework running BeOS for iPhone 4 (Chinese version 2.7 Pro)”
Some tickets refer to environments and tools you may have never heard of. Or to custom builds. Or to configurations insanely more complicated than what you ever used.
“I don’t know” and “I don’t care” would be honest answers. The former is not a valid justification for closing the issue. The latter would backfire. So, you spend time Googling for that obscure thing, try to understand the user’s issue from the pieces of the puzzle you somehow manage to collect, and tentatively come up with a credible answer. All you really want is that issue to be closed in the best possible way: by the user themselves.
Meanwhile, stress intensifies. Every single new ticket is causing stress and anxiety. Not about the content, but about what will have to be done in order to get it closed. How much time and effort it is going to take.
Only with the hope of having some time left to actually work on the project. Time spent helping people is not spent writing code.
Projects maintainers know how to install and use the software. And for their use case, it works. If the documentation is incomplete, one has to remember that this very documentation was written as a gift, to help other people. If the project doesn’t work in an environment maintainers don’t use, they shouldn’t be blamed for it.
Having feedback is great. Realizing that a project is useful to other people is fantastic and encouraging. The ability to report bugs and make suggestions is very powerful. But this is not what the GitHub issue tracker is mostly used for. It is used to complain or ask for personalized help, describing what was tried and didn’t succeed as a “bug,” or as a “problem” in a piece of software that’s “broken,” “fails” and “doesn’t work.”
People working in support departments have to handle far more painful situations, all day long. If only for that, they deserve a lot of respect.
However, they have training. They know how to handle different types of customers. They can transfer to other people. They have relevant skills and experience.
Project maintainers don’t have these. Furthermore, support employees are supporting a company’s products. They certainly share a corporate culture, however, complains are targeted to the company’s work, not to their own work.
A “doesn’t work” ticket on a personal project issue tracker is something we take personally. There’s no one to ask for help about how to handle it in the best way, no manager or coworker to transfer the case to. Ignoring it will not make it disappear. It will still show up every single day until it eventually gets closed somehow.
Until then, “doesn’t work” tickets piling up make your work look like junk and hurt.
The GitHub issue tracker made me cry more than once. I couldn’t get any sleep after having closed tickets without substantial justification. Sometimes, I’d still like to somehow be able to say “please leave me alone” as support requests keep coming. And “ping” messages being posted on old issues that I postponed the review of because deciphering the actual problem being described was challenging.
On some projects, I eventually had to give up, and closed the issue tracker. But “doesn’t work” issues kept coming. As comments on old commits instead, because these can’t be disabled.
Issues vary a lot from one project to another, though. On a project meant to be used only by people already familiar with the domain, “it doesn’t work” issues are far less common. But instead of a free customer service center, the issue tracker can become a free consulting service, with people asking how to build an application or protocol, with your software being used somehow. It’s hard not to help. It’s hard to say no. So, spend time solving other people’s problems while you are struggling with your own, unrelated work? That’s the only way they will close the issue themselves. If you want it closed prematurely, you need a justification. “Sorry, I don’t have time” is not a justification for not leaving the ticket open. Even if this is the truth, and the best thing to do for your own mental health.
Open communication is great and necessary. And an issue tracker is definitely a very valuable tool. But it is a many-to-few topology, fueling a constant stream of negativity (in its form), which can eventually be mentally devastating.
Mitigations
Over the past 24 months, after repeated nervous breakdowns due to GitHub issues, I did a few things that helped a lot.
Probably the most important decision was to enforce a hard limit on the time spent daily handling issues, trying to convince myself that it was okay not to respond immediately.
With github-auto-locker, closed issues are automatically locked after a couple months. If an issue is closed, the case is over. Having a “me too” popping up on something discussed years ago is annoying. If there’s something new, please open a new ticket, especially since the software may have changed a lot since the original discussion and the context may be different.
After 30 days of inactivity, issues are closed with a timeout label. If there hasn’t been any activity for that long, it is unlikely that leaving the ticket open is going to change anything. Maybe it was a feature request that no one is interested in implementing. Maybe the reporter was asked for details but is never going to provide them. Maybe nobody knows how to answer the question or what it even means.
A timeout label doesn’t mean that the issue is going to be ignored. By opposition to a closed, unlabeled issue, it means that this is something to possibly give a new look at, later, when time permits. A lot of feature requests were closed in that state, but eventually got implemented later.
This helps a lot. It helps reducing the size of the task lists showing up every time you log in, with the same issues being displayed repeatedly, along with their age, reminding you that the clock is ticking. A shorter list, with fresher issues, is a little bit less depressing.
Finally, I learned to say “no” or “I don’t know.” Sometimes in a harsh way just for the sake of getting a ticket closed, but for my own sanity, that was necessary.