02 October 2022

You don’t say what version of THING you’re on or code examples how you’re using THING and what’s different from your expectations.

You also don’t say what you’ve tried, or what docs you’ve read, so it’s hard to know your investment in solving it yourself vs. asking the internet to do the work for you. If that sounds harsh, sorry, it just comes from experience handling open source issues.

QUICK GUESS AT WHAT IT COULD BE FROM EXPERIENCE, RATHER THAN INVESTIGATION.

It is a common problem in asking tech questions to not give enough info. I recommend you take a look at Simon Tathan’s ‘How to Report Bugs Effectively’ or CONTRIBUTING.md#filing-an-issue or yourbugreportneedsmore.info

Quoting the last one:

Hello there!

You've been directed to this website because you submitted a bug report to an open source project, but you provided too little information for the developers to be able to help you. Does this look familiar?

Hi, I'm getting a weird error when I use <program>, do you know what might be wrong?

Debugging software is hard, even when you have the code in front of you. Now imagine, trying to debug software on somebody else's computer, without any access to the code, without knowing what operating system is on the computer, or even what version of your software is being used. Your only hint is that "there's a weird error" and you have 1 line out of a 50 line stack trace to work with. Sound impossible? That's because it is!

So you want help?

If you want to actually get your problem solved, here is how you can submit a good bug report that a developer will actually respond to:

  • Got a stack trace? Send the whole thing - or better yet, send a link to it pasted on Gist or Pastie.
  • Provide context, for example what version of Ruby or Python or COBOL or whatever you're using, as well as the code that causes the problem. Again, Gist and Pastie are your friends.
  • Better yet, create a small program that reproduces the problem, and put it on Github, or zip it and send it in an email.
  • Even better yet, if you are able to, add a failing test case that demonstrates the problem you are having, and send it as a pull request or patch.

Too much info?

If you only remember one thing, remember this: reproducibility is key. If I can't reproduce your problem, I can't fix it.

Not enough info?

For a longer guide on proper bug reporting, please check Simon Tatham's excellent article.

I also recommend taking a look at the slides for Maintaining Open Source Projects.



blog comments powered by Disqus