You probably arrived here because of a curt message in response to an issue you filed on a repo that I contribute to. Sorry about that (particularly if you filed the issue long ago and have been waiting patiently for a response). Let me explain:
I work on a lot of different open source projects. I really do like building software that makes other people's lives easier, but it's crazy time-consuming. One of the most time-consuming parts is responding to issues. A lot of OSS maintainers will bend over backwards to try and understand your specific problem and diagnose it, to the point of setting up new test projects, fussing around with different Node versions, reading the documentation for build tools that we don't use, debugging problems in third party dependencies that appear to be involved in the problem... and so on. I've personally spent hundreds of hours of my free time doing these sorts of things to try and help people out, because I want to be a responsible maintainer and I want the users of my software to be productive and happy.
But it's not sustainable.
So I'm instituting a new rule: if you report an issue, you must have a minimal reproduction that demonstrates the problem. You might think you've already provided a repro – in fact you might have spent a lot of time figuring out where you think the problem lies, and writing instructions for maintainers to follow, and we're grateful for that. But if you got sent here, it's because it's not enough.
In some cases, there will be a project-specific way to demonstrate problems – for example, Rollup, Bublé and Svelte all have dedicated REPLs. Use them!
Often, it's not possible to illustrate the problem with a REPL. Here's what you do:
- Create a sample repo on GitHub (or wherever)
- Demonstrate the problem, and nothing but the problem. If the app where you're experiencing the issue happens to use Gulp, I don't care, unless the problem involves Gulp. Remove that stuff. Whittle it down to the bare minimum of code that reliably demonstrates the issue. Get rid of any dependencies that aren't directly related to the problem.
- Install all your dependencies to
package.json. If I can't clone the repo and donpm install && npm run build(or similar – see point 4) to see the problem, because I need some globally installed CLI tool or whatever, then you've made it harder to get to the bottom of the issue. - Include instructions in the repo, along with a description of the expected and actual behaviour. Obviously the issue should include information about the bug as well, but it's really helpful if
README.mdincludes that information, plus a link back to the issue. If there are any instructions beyondnpm install && npm run build, they should go here.
Maintainers will love you if you submit test cases and fixes via pull requests. Generally, if it's a non-trivial or controversial fix then you should probably just file the test case and discuss the solution before adding code, but straightforward fixes (that pass CI and follow the project's code style!) are hugely appreciated.
Really, I mean it. OSS depends on people like you reporting these issues and helping maintainers to create better software. You took time out of your day to do that, and we're really grateful. But we want to help everybody, and if we have to spend a lot of time reproducing complex issues, then we'll only be able to help some people, and we'll eventually get burned out.
So please, always include a repro. 💖
As another reference to this topic: https://stackoverflow.com/help/minimal-reproducible-example