Skip to content

Instantly share code, notes, and snippets.

@Rich-Harris
Last active November 25, 2024 12:04
Show Gist options
  • Save Rich-Harris/88c5fc2ac6dc941b22e7996af05d70ff to your computer and use it in GitHub Desktop.
Save Rich-Harris/88c5fc2ac6dc941b22e7996af05d70ff to your computer and use it in GitHub Desktop.
Please include a repro

Please include a repro

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.

How to create a minimal reproduction

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:

  1. Create a sample repo on GitHub (or wherever)
  2. 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.
  3. Install all your dependencies to package.json. If I can't clone the repo and do npm 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.
  4. 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.md includes that information, plus a link back to the issue. If there are any instructions beyond npm install && npm run build, they should go here.

Better still, file a test case or a fix!

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.

Thank you

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. 💖

@arnegroskurth
Copy link

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment