Writing Good Bug Reports

Welcome! This is a guide for effective community bug reporting for the Shiny; its goal is to help you write better bug reports.

Basics

A good bug report follows the Show, Don't Tell principle. It has three basic components:

1. What you did.
2. What happened.
3. What you expected to happen.

The impatient reader can stop now, as a well-specified report featuring these three components alone will put you in the upper echelon of bug reporters!

Where is the bug?

When you're having a problem with a Shiny application, there are a number of places that it can be coming from. Just to list a few:

1. Your own R code
2. Code in another R package you're using
3. R itself
4. Ephemeral networking problems

For this reason, we get many bug reports for Shiny which turn out not to have anything to do with Shiny itself. We help here where we can, but many of these reports don't go anywhere.

Reproducible examples

When reporting an issue, it is very, very helpful if you can provide code that other people can run to reproduce the problem. Please see Creating a Reproducible Example to learn how to do this for Shiny applications.

What does the bug look like?

You'd be surprised how many folks take the time to describe what they're doing, but fail to describe the actual issue they encounter. Avoid saying that something "doesn't work". Instead, show, don't tell exactly what happened.

• Did nothing happen when something should have?
• Did the wrong thing happen? If so, what?
• Did you see an error message? If so, what did it say?

When in doubt, share a screenshot showing exactly what the bug looks like when it happens. If you really want to impress us, you could make a short animated gif of the bug happening on your screen. One free program to help do that, that we use ourselves all the time, is LICEcap.

What did you expect to happen?

Sometimes a bug report is a feature request in disguise, and what seems like a problem is actually just something working as designed rather than as expected. For this reason, it's very helpful to tell us why you think the behavior you saw is wrong, if it isn't blindingly obvious.

Don't be afraid or embarrassed to file an issue that might be "as designed". If Shiny isn't working the way most people expect, that's a kind of bug, and we want to know about it!

That said, avoid disguising feature requests as bug reports; read our guide to Writing Good Feature Requests instead.

What problem are you trying to solve?

It's often helpful to describe the larger task you were trying to accomplish. Sometimes what looks like a bug is actually just a symptom of trying to put a round peg in a square hole. If you describe your larger task, we can often suggest a better way to do it, and suggest a workaround that can get you back in business before the bug is fixed.

Does the issue happen in master?

Even if you're using the latest stable version of Shiny, your issue might already be fixed on the master branch on GitHub! If you're able, it's very helpful for you to try to reproduce your problem in the very latest Shiny.

You can always install the latest version of Shiny from GitHub using devtools with this command:

devtools::install_github("rstudio/shiny")

What does your environment look like?

A minority of bugs only reproduce on certain systems, with certain browsers, or when Shiny is combined with certain other packages in an application. To help us make sure our environment matches yours when we try to reproduce, it's always helpful to know your:

1. Browser Version. For example, "Firefox 66" or "Edge 44.17763.1.0" (You can check your version of Edge with these instructions
2. Operating System Version. For example, "macOS 10.14" or "Windows 10"
3. sessionInfo() output.