/** @page reporting_bugs Reporting bugs A new bug can be filed here: https://gitlab.freedesktop.org/libinput/libinput/issues/new @note libinput has lots of users but very few developers. It is in your own interested to follow these steps precisely to ensure your bug can be dealt with efficiently. When reporting bugs against libinput, please follow the instructions below and provide the required data. You will need: - a reliable @ref reporting_bugs_reproducer "reproducer" for the bug - an @ref evemu "evemu recording" of the device while the bug is reproduced - device-specific information, see - @ref reporting_bugs_touchpad - @ref reporting_bugs_mouse - @ref reporting_bugs_keyboard - @ref reporting_bugs_trackpoint - @ref reporting_bugs_other - the @ref reporting_bugs_version "libinput version" you are on. - the @ref reporting_bugs_options "configuration options" you have set - a [gitlab account](https://gitlab.freedesktop.org/users/sign_in) Stay technical, on-topic, and keep the description concise. @section reporting_bugs_version Obtaining the libinput version If your libinput version is older than the current stable branch, you will get asked to try the latest version. If you run a distribution-provided libinput, use the package manager to get the **full** package name and version of libinput, e.g. - `rpm -q libinput` - `dpkg -s libinput10` If you run a self-compiled version of libinput provide the git commit you have built or the tarball name. As a last resort, use `libinput --version` @section reporting_bugs_reproducer Reproducing bugs Try to identify the bug by reproducing it reliably. Bugs without a reliable reproducer will have lowest priority. The more specific a bug description and reproducer is, the easier it is to fix. Try to replicate the series of events that lead to the bug being triggered. Narrow it down until you have a reliable sequence that can trigger the bug. For the vast majority of bugs you should not take longer than 5 seconds or three interactions (clicks, touches, taps, ...) with the device to reproduce. If it takes longer than that, you can narrow it down further. Once you can reproduce it, use the @ref libinput-debug-events helper tool. The output is textual and can help identify whether the bug is in libinput at all. Note that any configuration options you have set must be specified on the commandline, see the @ref libinput-debug-events "libinput-debug-events" man page. Use the `--verbose` flag to get more information about how libinput processes events. If the bug cannot be reproduced with the @ref libinput-debug-events helper, even with the correct configuration options set, it is likely not a bug in libinput. @section reporting_bugs_options libinput configuration settings libinput has a number of device-specific default configuration settings that may differ from the ones your desktop environment picks by default. You may have changed some options in a settings panel or in an the xorg.conf snippet yourself. You must provide these options in the bug report, otherwise a developer reproducing the issue may not be able to do so. If you are on X11, the current settings can be can be obtained with `xinput list-props "your device name"`. Use `xinput list` to obtain the device name. If you are on Wayland, provide a manual summary of the options you have changed from the default (e.g. "I enabled tap-to-click"). @section reporting_bugs_touchpad Reporting touchpad bugs When you file a bug, please attach the following information: - a virtual description of your input device, see @ref evemu. This is the most important piece of information, do not forget it! - the output from udevadm info, see @ref udev_info. - the vendor model number of your laptop (e.g. "Lenovo Thinkpad T440s") - and the content of `/sys/class/dmi/id/modalias`. - run the `touchpad-edge-detectior` tool (provided by libevdev) and verify that the ranges and sizes it prints match the touchpad (up to 5mm difference is ok) If you are reporting a bug related to button event generation: - does your touchpad have (separate) physical hardware buttons or is the whole touchpad clickable? - Are you using software buttons or clickfinger? See @ref clickpad_softbuttons. - Do you have @ref tapping enabled? @section reporting_bugs_mouse Reporting mouse bugs When you file a bug, please attach the following information: - a virtual description of your input device, see @ref evemu. This is the most important piece of information, do not forget it! - the vendor model number of the device (e.g. "Logitech M325") - the output from udevadm info, see @ref udev_info. If the bug is related to the @ref motion_normalization_customization "speed of the mouse": - the resolution of the mouse as specified by the vendor (in DPI) - the output of the `mouse-dpi-tool` (provided by libevdev) @section reporting_bugs_keyboard Reporting keyboard bugs Is your bug related to a keyboard layout? libinput does not handle keyboard layouts and merely forwards the physical key events. File the bug with your desktop environment instead (e.g. GNOME, KDE, ...), that's most likely where the issue is. When you file a bug, please attach the following information: - a virtual description of your input device, see @ref evemu. This is the most important piece of information, do not forget it! @section reporting_bugs_trackpoint Reporting trackpoint bugs When you file a bug, please attach the following information: - a virtual description of your input device, see @ref evemu. This is the most important piece of information, do not forget it! - the vendor model number of the device (e.g. "Logitech M325") - the output from udevadm info, see @ref udev_info. - the output of `libinput measure trackpoint-range` - the sensitivity of the trackpoint (adjust the event node number as needed): @verbatim $ cat /sys/class/input/event17/device/device/sensitivity @endverbatim @section reporting_bugs_other All other devices When you file a bug, please attach the following information: - a virtual description of your input device, see @ref evemu. This is the most important piece of information, do not forget it! - the vendor model number of the device (e.g. "Sony Plastation3 controller") @section udev_info udev information for the device In many cases, we require the udev properties assigned to the device to verify whether device-specific quirks were applied. This can be obtained with `udevadm info /sys/class/input/eventX`, with the correct event node for your device. An example output is below: @verbatim $ udevadm info /sys/class/input/event4 P: /devices/platform/i8042/serio1/input/input5/event4 N: input/event4 E: DEVNAME=/dev/input/event4 E: DEVPATH=/devices/platform/i8042/serio1/input/input5/event4 E: EVDEV_ABS_00=::41 E: EVDEV_ABS_01=::37 E: EVDEV_ABS_35=::41 E: EVDEV_ABS_36=::37 E: ID_INPUT=1 E: ID_INPUT_HEIGHT_MM=66 E: ID_INPUT_TOUCHPAD=1 E: ID_INPUT_WIDTH_MM=97 E: MAJOR=13 E: MINOR=68 E: SUBSYSTEM=input E: USEC_INITIALIZED=5463031 @endverbatim @section evemu Recording devices with evemu @note Where available, the @ref libinput-record tools should be used instead of evemu [evemu-record](https://www.freedesktop.org/wiki/Evemu/) records the device capabilities together with the event stream from the kernel. On our side, this allows us to recreate a virtual device identical to your device and re-play the event sequence, hopefully triggering the same bug. evemu-record takes a /dev/input/eventX event node, but without arguments it will simply show the list of devices and let you select: @verbatim $ sudo evemu-record > scroll.evemu Available devices: /dev/input/event0: Lid Switch /dev/input/event1: Sleep Button /dev/input/event2: Power Button /dev/input/event3: AT Translated Set 2 keyboard /dev/input/event4: SynPS/2 Synaptics TouchPad /dev/input/event5: Video Bus /dev/input/event6: ELAN Touchscreen /dev/input/event10: ThinkPad Extra Buttons /dev/input/event11: HDA Intel HDMI HDMI/DP,pcm=3 /dev/input/event12: HDA Intel HDMI HDMI/DP,pcm=7 /dev/input/event13: HDA Intel HDMI HDMI/DP,pcm=8 /dev/input/event14: HDA Intel PCH Dock Mic /dev/input/event15: HDA Intel PCH Mic /dev/input/event16: HDA Intel PCH Dock Headphone /dev/input/event17: HDA Intel PCH Headphone /dev/input/event18: Integrated Camera /dev/input/event19: TPPS/2 IBM TrackPoint Select the device event number [0-19]: @endverbatim Select the device that triggers the issue, then reproduce the bug and Ctrl+C the process. The resulting recording, ("scroll.evemu" in this example) will contain the sequence required to reproduce the bug. If the bug fails to reproduce during recording, simply Ctrl+C and restart evemu-record. Always start the recording from a neutral state, i.e. without any buttons or keys down, with the position of the device in the neutral position, without touching the screen/touchpad. @note The longer the recording, the harder it is to identify the event sequence triggering the bug. Please keep the event sequence as short as possible. To verify that the recording contains the bug, you can replay it on your device. For example, to replay the sequence recorded in the example above: @verbatim $ sudo evemu-play /dev/input/event4 < scroll.evemu @endverbatim If the bug is triggered by replaying on your device, attach the recording to the bug report. @note libinput does not affect the evemu recording. libinput and evemu talk directly to the kernel's device nodes. An evemu recording is not influenced by the libinput version or whether a libinput context is currently active. @dotfile evemu.gv @section fixed_bugs My bug was closed as fixed, what now? libinput's policy on closing bugs is: once the fix for a given bug is on git master, the bug is considered fixed and the bugzilla entry will be closed accordingly. Of course, unless you actually run git master, the bug will continue to affect you on your local machine. You are most likely running the distribution's package and you will need to wait until the distribution has updated its package accordingly. Do not re-open a bug just because it hasn't trickled down to your distribution's package version yet. Whether the bug fix ends up in your distribution depends on a number of things. Any given bug fix **may** be cherry-picked into the current stable branch, depending on its severity, impact, and likelyhood to cause regressions. Once cherry-picked it will land in the next stable branch release. These are usually a few weeks apart. Do not re-open a bug because it wasn't picked into a stable branch release or because your distribution didn't update to the latest stable branch release. Stable branches are usually discontinued when the next release comes out. Your distribution may pick a patch up immediately and ship the fix even before the next stable branch update is released. For example, Fedora does this frequently. If a bug needs to be fixed urgently, file a bug in your distribution's bug tracker. Patches on git master will end up in the next libinput release. Once your distribution updates to that release, your local libinput version will contain the fix. Do not re-open a bug because your distribution didn't update to the release. You can always run libinput from git master (see @ref building_libinput). Even while in development, libinput is very stable so this option isn't as scary as it may sounds. @subsection reporting_bugs_reopen When is it ok to re-open a fixed bug? Any time the bug was considered fixed but it turns out that the fix is insufficient and/or causes a regression. However, if the regression is in behavior unrelated to the fix itself it is usually better to file a new bug to reduce the noise. For example, if a fix to improve tapping breaks two-finger scrolling behavior, you should file a new bug but reference the original bug. */