summaryrefslogtreecommitdiffstats
path: root/wiki/src/doc/first_steps/bug_reporting.mdwn
blob: 58758196b0c6f5c8b723f82050105f3305e51e28 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
[[!meta title="Report an error"]]

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

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

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

[[!toc levels=2]]

<a id="already_known"></a>

Check if the bug is already known
=================================

Have a look at:

  - the [[list of known issues|support/known_issues]]
  - 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)

<a id="useful_bug_report"></a>

How to write a useful bug report
================================

  - The first aim of a bug report is to **tell the developers exactly
    how to reproduce the failure**, so try to reproduce the issue
    yourself and describe how you did that.
  - 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.

You can also refer to the great [How to Report Bugs
Effectively](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html), by
Simon Tatham.

<a id="whisperback"></a>

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
cases|bug_reporting#special_cases]].**

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

Start WhisperBack
-----------------

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 Error Reporting</span></span>.

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

WhisperBack lets you give plenty of useful information about your bug:

  - **Summary** a summary of the bug, try to be short, clear and informative
  - **Name of the affected software**
  - **Exact steps to reproduce the error**
  - **Actual result and description of the error**
  - **Desired result**

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.

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

Optional email address
----------------------

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
without any contact information are useless. But note that it also provides
an opportunity for eavesdroppers, like your email or Internet provider, to
confirm that you are using Tails.

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

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

  - 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

Send your report
----------------

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

Once your email has been sent correctly you will get the following
notification: <span class="guilabel">Your message has been sent</span>.

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

If you cannot use <span class="application">WhisperBack</span>
==============================================================

You might not always be able to use WhisperBack. In those cases, you can also
send your bug report by [[email|support/talk]] directly.

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).

<a id="no_internet_access"></a>

No internet access
------------------

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

The following steps can be used as an alternative method:

1. In Tails, start WhisperBack
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)
5. Save the document on a USB stick
6. Boot into a system with Internet connection and send your report

<a id="does_not_start"></a>

Tails does not start
--------------------

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]]

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

Reproducing the bug in Debian (for advanced users)
==================================================

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

Doing so takes much more time so, in doubt, report your bug as instructed
earlier and wait for guidance from our help desk.

- If your bug also affects Debian *stable* then it will have to be fixed
  in Debian directly and not in Tails.

- If your bug affects Debian *stable* but not Debian *testing* then it
  might have been solved already in Debian.

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

Debian stable
-------------

Images for the stable version of Debian, on which Tails is based, are
available on:

<https://cdimage.debian.org/images/unofficial/non-free/images-including-firmware/current-live/amd64/iso-hybrid/>

Download the `gnome+nonfree.iso` image to have the GNOME desktop and
all the non-free firmware for better hardware compatibility.

Debian testing
--------------

Images for the testing version of Debian are available on:

<https://get.debian.org/cdimage/unofficial/non-free/cd-including-firmware/weekly-live-builds/amd64/iso-hybrid/>

Download the `gnome+nonfree.iso` image to have the GNOME desktop and
all the non-free firmware for better hardware compatibility.