bug_reporting.mdwn 5.56 KB
Newer Older
1
[[!meta title="Report an error"]]
2

3
4
In this documentation we use the term *bug* to refer to a software error.

5
Reporting bugs is a great way of helping us improving Tails.
6

7
8
Remember that **the more effectively you report a bug**, the more likely we are
to fix it.
9

10
11
[[!toc levels=2]]

Tails developers's avatar
Tails developers committed
12
13
<a id="already_known"></a>

14
15
Check if the bug is already known
=================================
16

17
Have a look at:
18

Tails developers's avatar
Tails developers committed
19
  - the [[list of known issues|support/known_issues]]
20
  - 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)
21

Tails developers's avatar
Tails developers committed
22
23
<a id="useful_bug_report"></a>

24
25
26
How to write a useful bug report
================================

Tails developers's avatar
Tails developers committed
27
  - The first aim of a bug report is to **tell the developers exactly
sajolida's avatar
sajolida committed
28
29
    how to reproduce the failure**, so try to reproduce the issue
    yourself and describe how you did that.
Tails developers's avatar
Tails developers committed
30
31
32
33
34
35
36
  - If that is not possible, try to **describe what went wrong in
    detail**.  Write down the error messages, especially if they have
    numbers.
  - Write **clearly and be precise**. Say what you mean, and make sure
    it cannot be misinterpreted.
  - Be ready to provide extra information if the developers need it. If
    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
127.0.0.1's avatar
127.0.0.1 committed
39
Effectively](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html), by
40
41
Simon Tatham.

Tails developers's avatar
Tails developers committed
42
43
<a id="whisperback"></a>

44
45
46
47
48
Use WhisperBack
===============

**WhisperBack is an application written specifically to report bugs anonymously
from inside Tails. If you are not able to use WhisperBack, see the [[special
49
cases|bug_reporting#special_cases]].**
50
51
52
53

WhisperBack will help you fill-up a bug report, including relevant technical
details and send it to us encrypted and through Tor.

Tails developers's avatar
Tails developers committed
54
55
Start WhisperBack
-----------------
56

57
58
59
60
61
To start <span class="application">WhisperBack</span>, choose
<span class="menuchoice">
  <span class="guimenu">Applications</span>&nbsp;▸
  <span class="guisubmenu">System Tools</span>&nbsp;▸
  <span class="guimenuitem">WhisperBack</span></span>.
62
63
64
65

Write the report
----------------

Tails developers's avatar
Tails developers committed
66
WhisperBack lets you give plenty of useful information about your bug:
67

Tails developers's avatar
Tails developers committed
68
69
  - **Summary** a summary of the bug, try to be short, clear and informative
  - **Name of the affected software**
70
71
  - **Exact steps to reproduce the error**
  - **Actual result and description of the error**
Tails developers's avatar
Tails developers committed
72
73
  - **Desired result**

Tails developers's avatar
Tails developers committed
74
75
76
You can also have a look at the <span class="guilabel">technical details
to include</span> in your bug report. It will give us information about
your hardware, your version of Tails and the startup process.
77

78
[[!inline pages="support/talk/languages.inline" raw="yes" sort="age"]]
79

80
81
Optional email address
----------------------
82

83
84
Giving us an email address allows us to contact you to clarify the problem. This
is needed for the vast majority of the reports we receive as most reports
Tails developers's avatar
Tails developers committed
85
without any contact information are useless. But note that it also provides
86
87
an opportunity for eavesdroppers, like your email or Internet provider, to
confirm that you are using Tails.
88
89
90
91
92
93
94

Optional OpenPGP key
--------------------

You can also indicate an OpenPGP key corresponding to this email address. You
can either give:

Tails developers's avatar
Tails developers committed
95
96
97
  - a **key ID**, if the key is available on public key servers
  - a **link to the key**, if the key is available on the web
  - a **public key block**, if the key is not publicly available
98

Tails developers's avatar
Tails developers committed
99
100
Send your report
----------------
101
102
103

Once you are done writing your report, send it by clicking the *Send* button.

Tails developers's avatar
Tails developers committed
104
105
Once your email has been sent correctly you will get the following
notification: <span class="guilabel">Your message has been sent</span>.
106

107
108
<a id="special_cases"></a>

sajolida's avatar
sajolida committed
109
110
If you cannot use <span class="application">WhisperBack</span>
==============================================================
111

112
You might not always be able to use WhisperBack. In those cases, you can also
Tails developers's avatar
Tails developers committed
113
send your bug report by [[email|support/talk]] directly.
114

115
116
Note that if you send the report yourself, it might not be anonymous unless you
take special care (e.g. using Tor with a throw-away email account).
117

118
<a id="no_internet_access"></a>
Tails developers's avatar
Tails developers committed
119

120
121
122
No internet access
------------------

123
124
WhisperBack won't be able to send your bug report.

Tails developers's avatar
Tails developers committed
125
The following steps can be used as an alternative method:
126

127
1. In Tails, start WhisperBack
128
129
130
2. In the bug report window, expand "technical details to include"
3. Copy everything in the "debugging info" box
4. Paste it to another document (using gedit for instance)
131
132
5. Save the document on a USB stick
6. Boot into a system with Internet connection and send your report
133

sajolida's avatar
sajolida committed
134
135
<a id="does_not_start"></a>

Tails developers's avatar
Tails developers committed
136
137
Tails does not start
--------------------
138

139
140
141
142
143
144
For troubleshooting instructions in case Tails fails to start, refer to
our installation instructions on:

  - [[Starting a PC on a USB|install/debian/usb#start-tails]]
  - [[Starting a Mac on a USB|install/mac/usb#start-intermediary]]
  - [[Starting a Mac on a DVD|install/mac/dvd#start-dvd]]
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164

<a id="debian"></a>

Reproducing the bug in Debian
=============================

It is very useful for us to know if your bug only affects Tails or also
affects Debian, on which Tails is based.

You can:

1. Download the [latest version of Debian (testing)](http://get.debian.org/cdimage/unofficial/non-free/cd-including-firmware/weekly-live-builds/amd64/iso-hybrid/debian-live-testing-amd64-gnome+nonfree.iso) (2.5 GB).

1. Install Debian on a USB stick using <span class="application">GNOME
   Disks</span>. To do so, you can follow our instructions to [[Install an
   intermediary Tails|install/linux/usb#install-intermediary]] from
   Linux.

1. Try to reproduce your bug and tell us about the results in your
   report.