Effective bug reports are the most likely to be fixed. These guidelines explain how to write such reports.

Preliminaries

1. Make sure your software is up to date.
   • Ideally, test an in-development version to see whether your bug has already been fixed (e.g. Firefox Beta, Aurora, or bleeding-edge Nightly).
2. Search Github Issues to see whether your bug has already been reported
3. Open a new issue
   • If you have multiple issues, please file separate bug reports.

A good report should have:

• A descriptive title that summarizes the bug
• Steps to reproduce the issues
• Expected result
• Actual observed result
• Details of your environment
  • Version of Ushahidi you were testing on
  • Browser you were testing in
  • Operating system you were testing on
  • Deployment you were testing (including URL if publicly available)
• Screen shots if appropriate

Writing precise steps to reproduce

How can a developer reproduce the bug on his or her own computer?

Steps to reproduce are the most important part of any bug report. If a developer is able to reproduce the bug, the bug is very likely to be fixed. If the steps are unclear, it might not even be possible to know whether the bug has been fixed.

Describe your method of interacting with Firefox in addition to the intent of each step.

• Imprecise: "Open Gmail in another window".
• Precise: "Press Cmd+N to open a new browser window, then type https://mail.google.com/ in the address bar and press Enter".

After your steps, precisely describe the observed result and the expected result. Clearly separate facts (observations) from speculations.

• Imprecise: "It doesn't work"
• Precise: "Instead of showing my Inbox, it shows the message 'Your browser does not support cookies (error -91)'."

If the bug seems egregious, there might be something unusual about your setup that's a necessary part of the steps to reproduce the bug. See if you can reproduce the bug on a new Ushahidi deployment. If the bug only happens in your existing deployment, try to figure out what settings, plugins, or files in your deployment are needed to reproduce the bug.

• What if my bug seems "random" or "intermittent"?

Writing a clear summary

How would you describe the bug using approximately 10 words? This is the first part of your bug report a triager or developer will see.

A good summary should quickly and uniquely identify a bug report. It should explain the problem, not your suggested solution.

• Good: "Cancelling a File Copy dialog crashes File Manager"
• Bad: "Software crashes"

• Good: "Down-arrow scrolling doesn't work in <textarea> styled with overflow:hidden"
• Bad: "Browser should work with my web site"

Finding the correct product repository

There are several different products you can reports bugs under in github

• Ushahidi core https://github.com/ushahidi/Ushahidi_Web/issues
• Ushahidi Android app https://github.com/ushahidi/Ushahidi_Android/issues
• Ushahidi iPhone app https://github.com/ushahidi/Ushahidi_iPhone/issues
• Swiftriver https://github.com/ushahidi/SwiftRiver/issues
• SMSSync https://github.com/ushahidi/SMSSync/issues
• Plugins
  Try and find the appropriate github repository for the plugin. You can start by looking here for plugins built by the Ushahidi Team https://github.com/ushahidi
  If you can't find the appropriate repository, report your bug here https://github.com/ushahidi/Ushahidi_Web/issues

Partially based on work by Mozilla Contributors https://developer.mozilla.org/en-US/docs/Bug_writing_guidelines (Creative Commons: Attribution-Sharealike license)