Wednesday, December 22, 2021

I've found a bug in your open source library but I'm not going to raise an issue to log it. Sorry.

I suspect many people think this but never say it. 

It comes down to one simple fact: I haven't got the time.

"New Issue" button (from GitHub)

I know many people will be upset with me for saying this. I also know that I've been disappointed by others who have expressed or displayed this attitude themselves.

So, why aren't I going to report the bug/issue/problem I've found?

These aren't always the case but usually:

  • I assume that what I've found is an edge case. (If it wasn't someone else would have logged this previously---I recognize that if everyone thought this nothing would ever get reported.)
  • I don't expect it to get fixed. (This is often tied to it being an edge case.)
  • I've already spent lots more time on this than I wanted to (can really afford to) so another unplanned task related to this doesn't feel like a good use of my time. 

Expanding on that last point, a good bug report takes time to create. It depends on the project and the issue but for something non-trivial, I've found this can often take me several hours.

If what I've found is trivial to explain and recreate then creating a bug report or issue is simple and I'll always try to create one.


If it's not simple to explain and recreate, creating a bug will likely be a waste of my time and effort

Creating a bug/issue doesn't help me with the project I'm working on. I've just created a workaround that works with the code I have now. 

If the issue is fixed in the project I'll need to spend more time verifying the fix and (possibly) removing the workaround I've had to use.

Having found a workaround that meant spending more time than originally planned, I'll have to spend more time creating a bug (& repro), and then possibly spend even more time verifying a fix and making any necessary changes. Stopping once a workaround is found is often very appealing.

But what about other people who may encounter this issue?

Yes, creating an issue for them to find may help them. If I can share a workaround then even better.

If not an issue, maybe a blog post explaining the workaround would be something faster to create. That way at least there's a document somewhere on the internet for others to find. Sadly, very few scenarios (or projects) warrant (or allow) a brief description of a problem and a workaround.

If my aim is to make the best use of my time to help others, documenting a workaround for an obscure edge case doesn't feel like a good use of my time. Surely there are things I could do that would help more people...

This situation isn't good for anyone.

I don't want it to be like this.

I wish quick, simple bug reports were acceptable. - Even just a brief description that could be expanded upon over time. However, a description without a simple reproduction is likely to get closed rather than left open waiting for more details.

If it was an open-source project, I'd be happy to create an issue that has a description of the problem and a workaround (or link to one if documented elsewhere).

Having detailed instructions on how to report issues including having requirements on creating/including minimal ways to reproduce an issue are appealing from the perspective of a maintainer but are offputting for a person who just wants to use the library/tool and doesn't have the time to create a detailed report. 

Or could there be something better?......

I don't have any answers. 😢

I just wanted to start documenting my thoughts on this subject. I expect to have a follow-up post to this, eventually.

As a project maintainer, I'd rather know about any problem, no matter how vague or seemingly lacking in details. Knowing that something's wrong is preferable to not knowing.

At best it might indicate a gap in the documentation.
At worst it means a vague issue remains open. Possibly indefinitely.

Admittedly, if I had millions of users and loads of vague issues being created I may think differently.

Let me try and be clear (although being very aware the people I've most upset will probably not make it this far before saying something rude about me):

  • I want the tools I use to get better, add features, fix bugs, etc.
  • If I can and if you make it easy, I will raise issues.
  • If you make raising issues hard I'm much less likely to do it.
  • I know you're busy and your time is valuable. So is mine.
  • If you want to report an issue with one of my open-source projects, I'll happily take as much (or as little) detail as you can provide. The more detail you provide the more likely I am to be able to do something about it. But, I'd rather know there was a problem, even if it can't easily be recreated (yet!)
  • I'm aware this approach may not apply to very large projects. (If only this was my problem.)

Thoughts? tweet at me


Post a Comment

I get a lot of comment spam :( - moderation may take a while.