===== Writing Useful Bug Reports =====
Adapted from this page at the qTox wiki[[https://github.com/tux3/qTox/wiki/Writing-Useful-Bug-Reports| article]], in turn adapted from the Textmate wiki [[https://github.com/textmate/textmate/wiki/Writing-Bug-Reports| article]]. Primarily adapted for generalization to other clients.

==== What To Include ====

//Adapted from the guide in the [[https://github.com/textmate/textmate/wiki/Writing-Bug-Reports|textmate/textmate]] repository//

A good bug report must include the following four things:

  - **The steps to reproduce the bug**: Give detailed steps on how to reproduce the problem.
    * Start from scratch
    * Explicitly mention every action involved, and how you invoked it (e.g., rather than “delete the text”, say “Select //Cut// from the context menu”)
  - **The expected behavior of the application**: It’s important to include the result you’re expecting, as it might differ from how the program was designed to work.
  - **The observed behavior of the application**: This is also important, since it’s possible that following your steps on a different system doesn’t reproduce the issue.
    * Include the data found in your qtox.log file. You can find the log in ''%%~/.config/tox/%%'' on UNIX-like platforms, and in ''%%%APPDATA\tox\%%'' on Windows. Do not paste the log directly into the report. Post it somewhere else (e.g. [[https://gist.github.com/|Gist]] or [[http://pastebin.com/|Pastebin]]) and link to it.
  - **Information about your environment/platform**
    * Include the operating system name/version
    * Include the version of qTox you are using. You can find a commit hash in the ''%%About%%'' tab in the settings menu.
    * If you are able to test multiple operating systems, do so
    * If your problem involves hardware, include information about that hardware
    * If your problem involves a crash, provide a backtrace

==== Providing Backtraces ====

If you are familiar with your platform's debugging tools, and your bug involves your Tox client crashing, some of the most useful info you can provide would be found in a backtrace.

To acquire a backtrace, you will need to use the debugger appropriate for your platform. For Unix-Like systems that will probably be [[https://www.gnu.org/software/gdb/|gdb]]. You will also need to use the latest debug build of your Tox client. Debug binaries are available for most clients and the core library, but you don't have to use them if you know how to compile Tox with debugging symbols included.

=== Acquiring Debug Builds of Toxcore and your Tox Client ===

**From your distribution's package manager:**

**Compiling from source:**

=== Acquiring a Backtrace ===

1: Execute the binary in a debugger

<code>
#load the debug binary
gdb /path/to/debug-bin
</code>

2: Reproduce the circumstances causing the issue(i.e. deliberately cause it to crash), making sure the steps correspond to what you will report per the [[#bug_report_template| template]].

<code>
#start the program in the debugger
(gdb) run
#now reproduce the crash
</code>

3: Prompt your debugger to trace the error
<code>
(gdb) backtrace
</code>

3b: If you need to collect information from all the running threads
<code>
(gdb) thread apply all backtrace full
</code>

4: Paste the backtrace somewhere (e.g. [[https://gist.github.com/discover| Gist]] or [[https://pastebin.com/| Pastebin]]), and provide a link to it in your bug report.
==== Bug Report Template ====

When reporting bugs, you may choose to use the following template, either in its entirety, or with non-applicable sections left out.

<code>Brief Description:

Operating System: Windows / OS X / Linux (include version and/or distro)
Hardware: 
…

Reproducible: Always / Almost Always / Sometimes / Rarely / Couldn't Reproduce

Steps to reproduce:
1. 
2. 
3. 
…

Observed Behavior:

Expected Behavior:

Additional info:
(links, images, etc go here)</code>
**If your issue includes images, upload them to github.** Don't use imgur, etc.

If you're using multiple embedded images, be sure to include a description for every image, preferably using the following format:

<code>++++++++
+IMAGE1+
++++++++
↑ *Description of Image 1*

++++++++
+IMAGE2+
++++++++
↑ *Description of Image 2*</code>
===== Misc. Bug Reporting Tips =====

  - **Always** include text in English. If your English is not very good, you may optionally include text in your native language, so that someone else may attempt to translate it more appropriately for you.

===== Misc. Troubleshooting =====

Some tips for troubleshooting Tox Clients include:

  - Use Echobot for testing audio. If you start a voice/video call with Echobot, it will echo back all audio you send it with a 1-2 second delay. Echobot's ID can be found at [[https://toxme.io/u/echobot|Toxme]]

===== Reading Material =====

If you'd like to read other articles describing methods for writing bug reports, the following list contains a few very good picks:

  * [[http://www.chiark.greenend.org.uk/~sgtatham/bugs.html]]
  * [[https://github.com/textmate/textmate/wiki/Writing-Bug-Reports]]