Please Provide an Example App
An example app is an application that is designed to reproduce a bug or demonstrate an issue.
Q: “What is an example app?”
A way to reliably trigger a bug or demonstrate bad behavior in a contained, easily executable application. It is a specific form of a reproduction.
Q: “What isn’t an example app?”
An example app is not a step-by-step story of things you did to trigger the error, such as “I clicked this link” or “I entered this command” or “I compiled this code.” While such descriptions can sometimes be helpful, they’re often missing crucial contexts that might require guessing on the part of the person debugging. Chances are if your “reproduction” doesn’t involve source control, it’s not “a reproduction app.”
Q: “Why should I make an example app?”
Before someone can fix a bug, they need to understand why it happens. While descriptions can help, the golden standard for debugging code is to be able to reproduce the bug. The easier it is to reproduce the bug, the shorter the debugging cycles will take, and the faster it can be fixed.
Q: “Does that mean I should send my whole application over when I open a bug report?”
Please no. Reproduction code is best when there’s a minimal amount of code necessary to reproduce the issue. The more extra stuff there is, the harder it may be to separate what’s causing the bug versus what’s just there.
Q: “Is a series of shell commands in an issue description reproduction code?”
Instead of making a full-on reproduction committed to source control, it might be tempting to provide a bunch of shell commands instead. While a handful of shell commands is better than nothing, there’s an extremely high chance that the person debugging won’t be able to reproduce your issue. When this happens, they have to ask for clarification. This back-and-forth process takes lots of energy and wastes everyone’s time. Instead, it’s better to provide an executable reproduction from the beginning.
How to make an example app
- Start with a clean app with no other features.
- Add whatever code is necessary to demonstrate the issue.
- Add instructions to the README describing how to boot the app and reproduce the problem.
- Push the example app somewhere public, such as GitHub.
- Bonus: Give the app to a friend or co-worker. See if they can repro the problem without any instructions other than what’s in the README.
- Finally: Give a link to the example app to a maintainer (usually through an issue).
Get Help Faster
If you want the issue fixed as fast as possible, then you should try to help the maintainers as much as possible. Make an example app! Even if it takes extra time for you, it will ultimately lead to your issues getting fixed faster.
Sometimes an Example App Fixes the Problem
When a bug isn’t in the library, but instead in your code - then an example app will help you find and fix it faster.
If you end up finding and fixing a bug in your code, consider re-reading the documentation and seeing if that behavior of the library is unclear. Consider sending a documentation PR.
Spread the word
If you see an open bug report that does not have a working reproduction ask them for an example app!
Better yet, send them a link to this page to help them understand why and how to make an example app:
For additional tips on creating and responding to issues, check out the How to Open Source book.
What is CodeTriage?
CodeTriage is the easiest way to get started contributing to open source.
Sign up, subscribe to repos you want to help, and we send you contribution ideas in your inbox. Easy Peazy. If you want to know more read What is CodeTriage.