wiki/src/doc/first_steps/bug_reporting.mdwn

   1 [[!meta title="Report an error"]]
   2
   3 In this documentation we use the term *bug* to refer to a software error.
   4
   5 Reporting bugs is a great way of helping us improving Tails.
   6
   7 Remember that **the more effectively you report a bug**, the more likely we are
   8 to fix it.
   9
  10 [[!toc levels=2]]
  11
  12 <a id="already_known"></a>
  13
  14 Check if the bug is already known
  15 =================================
  16
  17 Have a look at:
  18
  19   - the [[list of known issues|support/known_issues]]
  20   - the [[!tails_redmine desc="list of things to do"]]
  21   - the [list of things that will be fixed or improved in the next release](https://labs.riseup.net/code/projects/tails/issues?query_id=111)
  22
  23 <a id="useful_bug_report"></a>
  24
  25 How to write a useful bug report
  26 ================================
  27
  28   - The first aim of a bug report is to **tell the developers exactly
  29     how to reproduce the failure**.
  30   - If that is not possible, try to **describe what went wrong in
  31     detail**.  Write down the error messages, especially if they have
  32     numbers.
  33   - Write **clearly and be precise**. Say what you mean, and make sure
  34     it cannot be misinterpreted.
  35   - Be ready to provide extra information if the developers need it. If
  36     they did not need it, they would not be asking for it.
  37
  38 You can also refer to the great [How to Report Bugs
  39 Effectively](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html), by
  40 Simon Tatham.
  41
  42 <a id="whisperback"></a>
  43
  44 Use WhisperBack
  45 ===============
  46
  47 **WhisperBack is an application written specifically to report bugs anonymously
  48 from inside Tails. If you are not able to use WhisperBack, see the [[special
  49 cases|bug_reporting#special_cases]].**
  50
  51 WhisperBack will help you fill-up a bug report, including relevant technical
  52 details and send it to us encrypted and through Tor.
  53
  54 Start WhisperBack
  55 -----------------
  56
  57 To start <span class="application">WhisperBack</span>, choose
  58 <span class="menuchoice">
  59   <span class="guimenu">Applications</span>&nbsp;▸
  60   <span class="guisubmenu">System Tools</span>&nbsp;▸
  61   <span class="guimenuitem">WhisperBack</span></span>.
  62
  63 Write the report
  64 ----------------
  65
  66 WhisperBack lets you give plenty of useful information about your bug:
  67
  68   - **Summary** a summary of the bug, try to be short, clear and informative
  69   - **Name of the affected software**
  70   - **Exact steps to reproduce the error**
  71   - **Actual result and description of the error**
  72   - **Desired result**
  73
  74 You can also have a look at the <span class="guilabel">technical details
  75 to include</span> in your bug report. It will give us information about
  76 your hardware, your version of Tails and the startup process.
  77
  78 Optional email address
  79 ----------------------
  80
  81 Giving us an email address allows us to contact you to clarify the problem. This
  82 is needed for the vast majority of the reports we receive as most reports
  83 without any contact information are useless. On the other hand it also provides
  84 an opportunity for eavesdroppers, like your email or Internet provider, to
  85 confirm that you are using Tails.
  86
  87 Optional OpenPGP key
  88 --------------------
  89
  90 You can also indicate an OpenPGP key corresponding to this email address. You
  91 can either give:
  92
  93   - a **key ID**, if the key is available on public key servers
  94   - a **link to the key**, if the key is available on the web
  95   - a **public key block**, if the key is not publicly available
  96
  97 Send your report
  98 ----------------
  99
 100 Once you are done writing your report, send it by clicking the *Send* button.
 101
 102 Once your email has been sent correctly you will get the following
 103 notification: <span class="guilabel">Your message has been sent</span>.
 104
 105 <a id="special_cases"></a>
 106
 107 Special cases
 108 =============
 109
 110 You might not always be able to use WhisperBack. In those cases, you can also
 111 send your bug report by [[email|support/talk]] directly.
 112
 113 Note that if you send the report yourself, it might not be anonymous unless you
 114 take special care (e.g. using Tor with a throw-away email account).
 115
 116 <a id="no_internet_access"></a>
 117
 118 No internet access
 119 ------------------
 120
 121 WhisperBack won't be able to send your bug report.
 122
 123 The following steps can be used as an alternative method:
 124
 125 1. In Tails, start WhisperBack
 126 2. In the bug report window, expand "technical details to include"
 127 3. Copy everything in the "debugging info" box
 128 4. Paste it to another document (using gedit for instance)
 129 5. Save the document on a USB stick
 130 6. Boot into a system with Internet connection and send your report
 131
 132 Tails does not start
 133 --------------------
 134
 135 See [[Tails_does_not_start]].