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 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------------------------------------------------------------------------------ 181All other devices 182------------------------------------------------------------------------------ 183 184When 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------------------------------------------------------------------------------ 193udev information for the device 194------------------------------------------------------------------------------ 195 196In many cases, we require the udev properties assigned to the device to 197verify whether device-specific quirks were applied. This can be obtained 198with ``udevadm info /sys/class/input/eventX``, with the correct event 199node 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------------------------------------------------------------------------------ 223Recording 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 230device capabilities together with the event stream from the kernel. On our 231side, this allows us to recreate a virtual device identical to your device 232and re-play the event sequence, hopefully triggering the same bug. 233 234evemu-record takes a ``/dev/input/eventX`` event node, but without arguments 235it 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 259Select the device that triggers the issue, then reproduce the bug and Ctrl+C 260the process. The resulting recording, ("scroll.evemu" in this example) will 261contain the sequence required to reproduce the bug. If the bug fails to 262reproduce during recording, simply Ctrl+C and restart evemu-record. 263Always start the recording from a neutral state, i.e. without any buttons or 264keys down, with the position of the device in the neutral position, without 265touching 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 271To verify that the recording contains the bug, you can replay it on your 272device. For example, to replay the sequence recorded in the example above: :: 273 274 $ sudo evemu-play /dev/input/event4 < scroll.evemu 275 276 277If the bug is triggered by replaying on your device, attach the recording to 278the bug report. 279 280libinput does not affect the evemu recording. libinput and evemu talk 281directly to the kernel's device nodes. An evemu recording is not 282influenced by the libinput version or whether a libinput context is 283currently active. 284 285.. graphviz:: evemu.gv 286 287.. _fixed_bugs: 288 289------------------------------------------------------------------------------ 290My bug was closed as fixed, what now? 291------------------------------------------------------------------------------ 292 293libinput's policy on closing bugs is: once the fix for a given bug is on git 294master, the bug is considered fixed and the gitlab issue will be closed 295accordingly. 296 297Of course, unless you actually run git master, the bug will continue to 298affect you on your local machine. You are most likely running the 299distribution's package and you will need to wait until the distribution has 300updated 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 305Whether the bug fix ends up in your distribution depends on a number of 306things. Any given bug fix **may** be cherry-picked into the current stable 307branch, depending on its severity, impact, and likelihood to cause 308regressions. Once cherry-picked it will land in the next stable branch 309release. 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 315Stable branches are usually discontinued when the next release comes out. 316 317Your distribution may pick a patch up immediately and ship the fix 318even before the next stable branch update is released. For example, Fedora 319does this frequently. 320 321.. hint:: If a bug needs to be fixed urgently, file a bug in your 322 distribution's bug tracker. 323 324Patches on git master will end up in the next libinput release. Once your 325distribution updates to that release, your local libinput version will 326contain the fix. 327 328.. warning:: Do not re-open a bug because your distribution didn't update to 329 the release. 330 331You can always run libinput from git master (see :ref:`building_libinput`). 332Even while in development, libinput is very stable so this option isn't as 333scary as it may sounds. 334 335.. _reporting_bugs_reopen: 336 337.............................................................................. 338When is it ok to re-open a fixed bug? 339.............................................................................. 340 341Any time the bug was considered fixed but it turns out that the fix is 342insufficient and/or causes a regression. 343 344However, if the regression is in behavior unrelated to the fix itself it is 345usually better to file a new bug to reduce the noise. For example, if a fix 346to improve tapping breaks two-finger scrolling behavior, you should file a 347new bug but reference the original bug. 348 349.. _reporting_bugs_tags: 350 351------------------------------------------------------------------------------ 352Gitlab issue tracker tags 353------------------------------------------------------------------------------ 354 355The gitlab issue tracker allows developers to add tags to bugs to classify 356them. 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 394These tags are high-level categories only, always look for the comments in 395the issue to get further details. 396