Debian Codegraph @

doc/user/reporting-bugs.rst

raw
1 .. _reporting_bugs:
2
3 ==============================================================================
4 Reporting bugs
5 ==============================================================================
6
7 A new bug can be filed here:
8 https://gitlab.freedesktop.org/libinput/libinput/issues/new
9
10 .. hint:: libinput has lots of users but very few developers. It is in your
11 own interest to follow the steps here precisely to ensure your bug can be
12 dealt with efficiently.
13
14 When reporting bugs against libinput, you will need:
15
16 - a reliable :ref:`reproducer <reporting_bugs_reproducer>` for the bug
17 - a :ref:`recording <libinput-record>` of the device while the bug is reproduced
18 - device-specific information, see
19
20 - :ref:`reporting_bugs_touchpad`
21 - :ref:`reporting_bugs_mouse`
22 - :ref:`reporting_bugs_keyboard`
23 - :ref:`reporting_bugs_trackpoint`
24 - :ref:`reporting_bugs_other`
25
26 - the :ref:`libinput version <reporting_bugs_version>` you are on.
27 - the :ref:`configuration options <reporting_bugs_options>` you have set
28 - a `gitlab account <https://gitlab.freedesktop.org/users/sign_in>`_
29
30 Stay technical, on-topic, and keep the description concise.
31
32 .. _reporting_bugs_version:
33
34 ------------------------------------------------------------------------------
35 Obtaining the libinput version
36 ------------------------------------------------------------------------------
37
38 If your libinput version is older than the current stable branch, please try
39 the latest version. If you run a distribution-provided
40 libinput, use the package manager to get the **full** package name and
41 version of libinput, e.g.
42
43 - ``rpm -q libinput``
44 - ``dpkg -s libinput10``
45
46 If you run a self-compiled version of libinput provide the git commit you
47 have built or the tarball name.
48
49 As a last resort, use ``libinput --version``
50
51 .. _reporting_bugs_reproducer:
52
53 ------------------------------------------------------------------------------
54 Reproducing bugs
55 ------------------------------------------------------------------------------
56
57 Try to identify the bug by reproducing it reliably. Bugs without a
58 reliable reproducer will have lowest priority. The more specific a bug
59 description and reproducer is, the easier it is to fix.
60
61 Try to replicate the series of events that lead to the bug being triggered.
62 Narrow it down until you have a reliable sequence that can trigger the bug.
63 For the vast majority of bugs you should not take longer than 5 seconds or
64 three interactions (clicks, touches, taps, ...) with the device to
65 reproduce. If it takes longer than that, you can narrow it down further.
66
67 Once you can reproduce it, use the :ref:`libinput-debug-events` helper
68 tool::
69
70 $> libinput debug-events --verbose
71
72 The output is textual and can help identify whether the bug is in libinput
73 at all. Note that any configuration options you have set must be specified
74 on the commandline, see the :ref:`libinput-debug-events`
75 man page. Use the ``--verbose`` flag to get more information about how
76 libinput processes events.
77
78 If the bug cannot be reproduced with the :ref:`libinput-debug-events` helper,
79 even with the correct configuration options set, it is likely not a bug in
80 libinput.
81
82 .. _reporting_bugs_options:
83
84 ------------------------------------------------------------------------------
85 libinput configuration settings
86 ------------------------------------------------------------------------------
87
88 libinput has a number of device-specific default configuration settings that
89 may differ from the ones your desktop environment picks by default. You may
90 have changed some options in a settings panel or in an the xorg.conf snippet
91 yourself.
92
93 You must provide these options in the bug report, otherwise a developer
94 reproducing the issue may not be able to do so.
95
96 If you are on X11, the current settings can be can be obtained with
97 ``xinput list-props "your device name"``. Use ``xinput list`` to
98 obtain the device name.
99
100 If you are on Wayland, provide a manual summary of the options you have
101 changed from the default (e.g. "I enabled tap-to-click").
102
103 .. _reporting_bugs_touchpad:
104
105 ------------------------------------------------------------------------------
106 Reporting touchpad bugs
107 ------------------------------------------------------------------------------
108
109 When you file a bug, please attach the following information:
110
111 - a virtual description of your input device, see :ref:`libinput-record`.
112 This is the most important piece of information, do not forget it!
113 - the output from udevadm info, see :ref:`udev_info`.
114 - the vendor model number of your laptop (e.g. "Lenovo Thinkpad T440s")
115 - and the content of ``/sys/class/dmi/id/modalias``.
116 - run ``libinput measure touchpad-size`` tool (see :ref:`absolute_coordinate_ranges_fix`)
117 and verify that the ranges and sizes it prints match the touchpad (up to 5mm
118 difference is ok)
119
120 If you are reporting a bug related to button event generation:
121
122 - does your touchpad have (separate) physical hardware buttons or is the
123 whole touchpad clickable?
124 - Are you using software buttons or clickfinger? See :ref:`clickpad_softbuttons`.
125 - Do you have :ref:`tapping` enabled?
126
127 .. _reporting_bugs_mouse:
128
129 ------------------------------------------------------------------------------
130 Reporting mouse bugs
131 ------------------------------------------------------------------------------
132
133 When you file a bug, please attach the following information:
134
135 - a virtual description of your input device, see :ref:`libinput-record`.
136 This is the most important piece of information, do not forget it!
137 - the vendor model number of the device (e.g. "Logitech M325")
138 - the output from udevadm info, see :ref:`udev_info`.
139
140 If the bug is related to the :ref:`speed of the mouse <motion_normalization_customization>`:
141
142 - the resolution of the mouse as specified by the vendor (in DPI)
143 - the output of the ``mouse-dpi-tool`` (provided by libevdev)
144
145 .. _reporting_bugs_keyboard:
146
147 ------------------------------------------------------------------------------
148 Reporting keyboard bugs
149 ------------------------------------------------------------------------------
150
151 Is your bug related to a keyboard layout? libinput does not handle keyboard
152 layouts and merely forwards the physical key events. File the bug with your
153 desktop environment instead (e.g. GNOME, KDE, ...), that's most likely where
154 the issue is.
155
156 When you file a bug, please attach the following information:
157
158 - a virtual description of your input device, see :ref:`libinput-record`.
159 This is the most important piece of information, do not forget it!
160
161 .. _reporting_bugs_trackpoint:
162
163 ------------------------------------------------------------------------------
164 Reporting trackpoint bugs
165 ------------------------------------------------------------------------------
166
167 When you file a bug, please attach the following information:
168
169 - a virtual description of your input device, see :ref:`libinput-record`.
170 This is the most important piece of information, do not forget it!
171 - the vendor model number of the device (e.g. "Logitech M325")
172 - the output from udevadm info, see :ref:`udev_info`.
173 - the sensitivity of the trackpoint if it exists (adjust the event node number as needed): ::
174
175 $ cat /sys/class/input/event17/device/device/sensitivity
176
177
178 .. _reporting_bugs_other:
179
180 ------------------------------------------------------------------------------
181 All other devices
182 ------------------------------------------------------------------------------
183
184 When you file a bug, please attach the following information:
185
186 - a virtual description of your input device, see :ref:`libinput-record`.
187 This is the most important piece of information, do not forget it!
188 - the vendor model number of the device (e.g. "Sony Plastation3 controller")
189
190 .. _udev_info:
191
192 ------------------------------------------------------------------------------
193 udev information for the device
194 ------------------------------------------------------------------------------
195
196 In many cases, we require the udev properties assigned to the device to
197 verify whether device-specific quirks were applied. This can be obtained
198 with ``udevadm info /sys/class/input/eventX``, with the correct event
199 node for your device. An example output is below: ::
200
201 $ udevadm info /sys/class/input/event4
202 P: /devices/platform/i8042/serio1/input/input5/event4
203 N: input/event4
204 E: DEVNAME=/dev/input/event4
205 E: DEVPATH=/devices/platform/i8042/serio1/input/input5/event4
206 E: EVDEV_ABS_00=::41
207 E: EVDEV_ABS_01=::37
208 E: EVDEV_ABS_35=::41
209 E: EVDEV_ABS_36=::37
210 E: ID_INPUT=1
211 E: ID_INPUT_HEIGHT_MM=66
212 E: ID_INPUT_TOUCHPAD=1
213 E: ID_INPUT_WIDTH_MM=97
214 E: MAJOR=13
215 E: MINOR=68
216 E: SUBSYSTEM=input
217 E: USEC_INITIALIZED=5463031
218
219
220 .. _evemu:
221
222 ------------------------------------------------------------------------------
223 Recording devices with evemu
224 ------------------------------------------------------------------------------
225
226 .. warning:: Where available, the :ref:`libinput-record` tools should be used instead
227 of evemu
228
229 `evemu-record <https://www.freedesktop.org/wiki/Evemu/>`_ records the
230 device capabilities together with the event stream from the kernel. On our
231 side, this allows us to recreate a virtual device identical to your device
232 and re-play the event sequence, hopefully triggering the same bug.
233
234 evemu-record takes a ``/dev/input/eventX`` event node, but without arguments
235 it will simply show the list of devices and let you select: ::
236
237 $ sudo evemu-record > scroll.evemu
238 Available devices:
239 /dev/input/event0: Lid Switch
240 /dev/input/event1: Sleep Button
241 /dev/input/event2: Power Button
242 /dev/input/event3: AT Translated Set 2 keyboard
243 /dev/input/event4: SynPS/2 Synaptics TouchPad
244 /dev/input/event5: Video Bus
245 /dev/input/event6: ELAN Touchscreen
246 /dev/input/event10: ThinkPad Extra Buttons
247 /dev/input/event11: HDA Intel HDMI HDMI/DP,pcm=3
248 /dev/input/event12: HDA Intel HDMI HDMI/DP,pcm=7
249 /dev/input/event13: HDA Intel HDMI HDMI/DP,pcm=8
250 /dev/input/event14: HDA Intel PCH Dock Mic
251 /dev/input/event15: HDA Intel PCH Mic
252 /dev/input/event16: HDA Intel PCH Dock Headphone
253 /dev/input/event17: HDA Intel PCH Headphone
254 /dev/input/event18: Integrated Camera
255 /dev/input/event19: TPPS/2 IBM TrackPoint
256 Select the device event number [0-19]:
257
258
259 Select the device that triggers the issue, then reproduce the bug and Ctrl+C
260 the process. The resulting recording, ("scroll.evemu" in this example) will
261 contain the sequence required to reproduce the bug. If the bug fails to
262 reproduce during recording, simply Ctrl+C and restart evemu-record.
263 Always start the recording from a neutral state, i.e. without any buttons or
264 keys down, with the position of the device in the neutral position, without
265 touching the screen/touchpad.
266
267 .. note:: The longer the recording, the harder it is to identify the event
268 sequence triggering the bug. Please keep the event sequence as short
269 as possible.
270
271 To verify that the recording contains the bug, you can replay it on your
272 device. For example, to replay the sequence recorded in the example above: ::
273
274 $ sudo evemu-play /dev/input/event4 < scroll.evemu
275
276
277 If the bug is triggered by replaying on your device, attach the recording to
278 the bug report.
279
280 libinput does not affect the evemu recording. libinput and evemu talk
281 directly to the kernel's device nodes. An evemu recording is not
282 influenced by the libinput version or whether a libinput context is
283 currently active.
284
285 .. graphviz:: evemu.gv
286
287 .. _fixed_bugs:
288
289 ------------------------------------------------------------------------------
290 My bug was closed as fixed, what now?
291 ------------------------------------------------------------------------------
292
293 libinput's policy on closing bugs is: once the fix for a given bug is on git
294 master, the bug is considered fixed and the gitlab issue will be closed
295 accordingly.
296
297 Of course, unless you actually run git master, the bug will continue to
298 affect you on your local machine. You are most likely running the
299 distribution's package and you will need to wait until the distribution has
300 updated its package accordingly.
301
302 .. warning:: Do not re-open a bug just because it hasn't trickled down to
303 your distribution's package version yet.
304
305 Whether the bug fix ends up in your distribution depends on a number of
306 things. Any given bug fix **may** be cherry-picked into the current stable
307 branch, depending on its severity, impact, and likelihood to cause
308 regressions. Once cherry-picked it will land in the next stable branch
309 release. These are usually a few weeks apart.
310
311 .. warning:: Do not re-open a bug because it wasn't picked into a stable branch
312 release or because your distribution didn't update to the latest stable
313 branch release.
314
315 Stable branches are usually discontinued when the next release comes out.
316
317 Your distribution may pick a patch up immediately and ship the fix
318 even before the next stable branch update is released. For example, Fedora
319 does this frequently.
320
321 .. hint:: If a bug needs to be fixed urgently, file a bug in your
322 distribution's bug tracker.
323
324 Patches on git master will end up in the next libinput release. Once your
325 distribution updates to that release, your local libinput version will
326 contain the fix.
327
328 .. warning:: Do not re-open a bug because your distribution didn't update to
329 the release.
330
331 You can always run libinput from git master (see :ref:`building_libinput`).
332 Even while in development, libinput is very stable so this option isn't as
333 scary as it may sounds.
334
335 .. _reporting_bugs_reopen:
336
337 ..............................................................................
338 When is it ok to re-open a fixed bug?
339 ..............................................................................
340
341 Any time the bug was considered fixed but it turns out that the fix is
342 insufficient and/or causes a regression.
343
344 However, if the regression is in behavior unrelated to the fix itself it is
345 usually better to file a new bug to reduce the noise. For example, if a fix
346 to improve tapping breaks two-finger scrolling behavior, you should file a
347 new bug but reference the original bug.
348
349 .. _reporting_bugs_tags:
350
351 ------------------------------------------------------------------------------
352 Gitlab issue tracker tags
353 ------------------------------------------------------------------------------
354
355 The gitlab issue tracker allows developers to add tags to bugs to classify
356 them.
357
358 - **being worked on**: someone is currently working on this feature. This
359 tag is used for features that will take a long time to implement fully and
360 prevents others from having to duplicate the work. Do reach out and ask if
361 help and/or further testing is needed.
362 - **bug**: issue is confirmed to be a bug
363 - **cantfix**: for technical reasons, this bug cannot be fixed, or at least
364 it cannot be fixed in libinput.
365 - **enhancement**: this issue describes a future feature, not a bug.
366 - **help needed**: this issue requires someone outside the libinput core
367 developer team to implement it. It is unlikely to be implemented
368 without someone stepping up to do the work. If you do see this tag, do ask
369 for guidance on how to implement it.
370 - **hw issue**: an issue that affects a specific device and is a hardware
371 bug, not a software bug. Often these needs to be worked around in libinput
372 but there are cases where a hw issue ends up as *cantfix*.
373 - **janitor**: a cleanup task that does not substantially affect how
374 libinput works. These are usually good bugs for newcomers to start on.
375 - **kernel**: this issue is a kernel bug, not a libinput bug. Often closed
376 as *cantfix* of *wontfix* as we wait for the kernel to address the issue
377 instead.
378 - **needs triage**: bug has not yet been confirmed by a core developer.
379 - **not our bug**: the issue is in some other component of the stack and
380 needs to be addressed there.
381 - **please test**: a fix is available but not yet merged and should be
382 tested by the reporter or others affected by the issue.
383 - **quirk**: this is issue needs :ref:`device-quirks` to be fixed
384 - **regression**: the issue is a regression to previous versions of
385 libinput. These issues get priorities.
386 - **waiting on reporter**: some more information is required from the
387 reporter and the issue cannot be fixed until the issue has been provided.
388 Where a bug is left in this state for too long, the bug will be closed as
389 *cantfix*.
390 - **wontfix**: this issue will not get fixed. This tag is usually assigned
391 to feature requests that are outside the scope of libinput or would put an
392 unreasonable maintenance burdern on the maintainers.
393
394 These tags are high-level categories only, always look for the comments in
395 the issue to get further details.