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