= Overview
When you submit a bug report, you **MUST** include reproduction steps. We can not help you with bugs we can not reproduce, and will not accept reports which omit reproduction steps or have incomplete or insufficient instructions.
This document explains what we're looking for in good reproduction steps. Briefly:
- Reproduction steps must allow us to reproduce the problem locally
- Reproduction should be as simple as possible.
Good reproduction steps can take time to write out clearly, simplify, and verify. As a reporter, we expect you to shoulder as much of this burden as you can, to allow us to reproduce and resolve bugs more efficiently.
Reproduction steps must be complete and self-contained, and must allow **anyone** to reproduce the issue. If the bug you're seeing depends on data or configuration which would not be present, you need to include that information in your steps.
Mentioning links to various affected objects (sites, users, systems, places on websites) is of enormous help. Good link and textual explanation is worth more than hundreds of screenshots or screencasts. Not to mention that you can't search against screenshot or a video.
= Example Reproduction Steps
Here's an example of what good reproduction steps might look like:
----
Reproduction steps:
- Click "Create Event" in Calendar.
- Fill in the required fields with any text (name, description, etc).
- Set an invalid time for one of the dates, like the meaningless string "Tea Time". This is not valid, so we're expecting an error when we submit the form.
- Click "Create" to save the event.
Expected result:
- Form reloads with an error message about the specific mistake.
- All field values are retained.
Actual result:
- Form reloads with an error message about the specific mistake.
- Most values are discarded, so I have to re-type the name, description, etc.
----
These steps are **complete** and **self-contained**: anyone can reproduce the issue by following these steps. These steps are **clear** and **easy to follow**. These steps are also simple and minimal: they don't include any extra unnecessary steps.
Finally, these steps explain what the reporter expected to happen, what they observed, and how those behaviors differ. This isn't as important when the observation is an obvious error like an exception, but can be important if a behavior is merely odd or ambiguous.
= Getting Started
To generate reproduction steps, first find a sequence of actions which reproduce the issue you're seeing reliably.
Next, write down everything you did as clearly as possible. Make sure each step is self-contained: anyone should be able to follow your steps, without access to private or proprietary data.
Now, to verify that your steps provide a complete, self-contained way to reproduce the issue, follow them yourself.
If you can follow your steps and reproduce the issue, we'll probably be able to follow them and reproduce the issue ourselves.
If you can't follow your steps because they depend on information which is not available (for example, a certain config setting), rewrite them to include instrutions to create that information (for example, adjusting the config to the problematic value).
If you follow your instructions but the issue does not reproduce, the issue might already be fixed.
If you're quite certain that nothing changed and the issue still doesn't reproduce, your reproduction steps are missing important information. You need to figure out what key element differs between attempts.
Once you have working reproduction steps, your steps may have details which aren't actually necessary to reproduce the issue. You may be able to simplify them by removing some steps or describing steps more narrowly.
= Things to avoid
These are common mistakes when providing reproduction instructions:
**Insufficient Information**: The most common issue we see is instructions which do not have enough information: they are missing critical details which are necessary in order to follow them.
**Inaccurate Steps**: The second most common issue we see is instructions which do not actually reproduce a problem when followed. Verify your steps by testing them.
**Private Information**: Some users provide reports which hinge on the particulars of private things we can not access. This is not useful, because we can not examine it and see why it is causing an issue.
**Screenshots and Screencasts**: Screenshots can be helpful to explain a set of steps or show what you're seeing, but they usually aren't sufficient on their own because they don't contain all the information we need to reproduce them. We usually have to guess the site domain, site system, user account, etc.
Also, screenshots and videos cannot be searched. Someone reporting a new issue will not be able to find existing ticket that are potentially related to existing issue(s).