1 2.. _contributing: 3 4============================================================================== 5Contributing to libinput 6============================================================================== 7 8 9So you want to contribute to libinput? Great! We'd love to help you be a part 10of our community. Here is some important information to help you. 11 12.. contents:: 13 :local: 14 15------------------------------------------------------------------------------ 16Code of Conduct 17------------------------------------------------------------------------------ 18 19As a freedesktop.org project, libinput follows the `freedesktop.org 20Contributor Covenant <https://www.freedesktop.org/wiki/CodeOfConduct>`_. 21 22Please conduct yourself in a respectful and civilised manner when 23interacting with community members on mailing lists, IRC, or bug trackers. 24The community represents the project as a whole, and abusive or bullying 25behaviour is not tolerated by the project. 26 27------------------------------------------------------------------------------ 28Contact 29------------------------------------------------------------------------------ 30 31Questions can be asked on ``#wayland`` on oftc or on the 32`wayland-devel@lists.freedesktop.org 33<https://lists.freedesktop.org/mailman/listinfo/wayland-devel>`_ mailing 34list. 35 36For IRC, ping user ``whot`` (Peter Hutterer, the libinput maintainer) though 37note that he lives on UTC+10 and thus the rest of the world is out of sync 38by default ;) 39 40For anything that appears to be device specific and/or related to a new 41feature, just file `an issue in our issue tracker 42<https://gitlab.freedesktop.org/libinput/libinput/issues>`_. It's usually the 43most efficient way to get answers. 44 45------------------------------------------------------------------------------ 46What to work on? 47------------------------------------------------------------------------------ 48 49If you don't already know what you want to improve or fix with libinput, 50then a good way of finding something is to search for the ``help needed`` 51tag in our `issue tracker <https://gitlab.freedesktop.org/libinput/libinput/issues?label_name%5B%5D=help+needed>`_. 52These are issues that have been triaged to some degree and deemed to be a 53possible future feature to libinput. 54 55.. note:: Some of these issue may require specific hardware to reproduce. 56 57Another good place to help out with is the documentation. For anything you 58find in these pages that isn't clear enough please feel free to reword it 59and add what is missing. 60 61------------------------------------------------------------------------------ 62Getting the code 63------------------------------------------------------------------------------ 64 65The :ref:`building_libinput` have all the details but the short solution 66will be: 67 68:: 69 70 $> git clone https://gitlab.freedesktop.org/libinput/libinput 71 $> cd libinput 72 $> meson setup --prefix=/usr builddir/ 73 $> ninja -C builddir/ 74 $> sudo ninja -C builddir/ install 75 76You can omit the last step if you only want to test locally. 77 78------------------------------------------------------------------------------ 79Working on the code 80------------------------------------------------------------------------------ 81 82If you are planning to send patches, it's a good idea to set up 83`pre-commit <https://pre-commit.com/>`_ with these commands:: 84 85 $> pre-commit install 86 $> pre-commit install --hook-type pre-push 87 88This will check a few things before you commit and/or push to your repos to 89reduce the turnaround time for some common mistakes. 90 91libinput has a roughly three-parts architecture: 92 93- the front-end code which handles the ``libinput_some_function()`` API calls in ``libinput.c`` 94- the generic evdev interface handling which maps those API calls to the 95 backend calls (``evdev.c``). 96- there are device-specific backends which do most of the actual work - 97 ``evdev-mt-touchpad.c`` is the one for touchpads for example. 98 99In general, things that only affect the internal workings of a device only 100get implemented in the device-specific backend. You only need to touch the 101API when you are adding configuration options. For more details, please read 102the :ref:`architecture` document. There's also a `blog post describing the 103building blocks 104<https://who-t.blogspot.com/2019/03/libinputs-internal-building-blocks.html>`_ 105that may help to understand how it all fits together. 106 107Documentation is in ``/doc/api`` for the doxygen-generated API documentation. 108These are extracted from the libinput source code directly. The 109documentation you're reading right now is in ``/doc/user`` and generated with 110sphinx. Simply running ``ninja -C builddir`` will rebuild it and the final 111product ends up in ``builddir/Documentation``. 112 113------------------------------------------------------------------------------ 114Testing the code 115------------------------------------------------------------------------------ 116 117libinput provides a bunch of :ref:`tools` to debug any changes - without 118having to install libinput. 119 120The two most useful ones are :ref:`libinput debug-events 121<libinput-debug-events>` and :ref:`libinput debug-gui <libinput-debug-gui>`. 122Both tools can be run from the build directory directly and are great for 123quick test iterations:: 124 125 $> sudo ./builddir/libinput-debug-events --verbose 126 $> sudo ./builddir/libinput-debug-gui --verbose 127 128The former provides purely textual output and is useful for verifying event 129streams from buttons, etc. The latter is particularly useful when you are 130trying to debug pointer movement or placement. ``libinput debug-gui`` will 131also visualize the raw data from the device so you can compare pointer 132behavior with what comes from the kernel. 133 134These tools create a new libinput context and will not affect your session's 135behavior. Only once you've installed libinput and restarted your session 136will your changes affect the X server/Wayland compositor. 137 138Once everything seems to be correct, it's time to run the 139:ref:`test-suite`:: 140 141 $> sudo ./builddir/libinput-test-suite 142 143This test suite can take test names etc. as arguments, have a look at 144:ref:`test-suite` for more info. There are a bunch of other tests that are 145run by the CI on merge requests, you can run those locally with :: 146 147 $> sudo ninja -C builddir check 148 149So it always pays to run that before submitting. This will also run the code 150through valgrind and pick up any memory leaks. 151 152.. _contributing_submitting_code: 153 154------------------------------------------------------------------------------ 155Submitting Code 156------------------------------------------------------------------------------ 157 158Any patches should be sent via a Merge Request (see the `GitLab docs 159<https://docs.gitlab.com/ce/gitlab-basics/add-merge-request.htm>`_) 160in the `libinput GitLab instance hosted by freedesktop.org 161<https://gitlab.freedesktop.org/libinput/libinput>`_. 162 163Below are the steps required to submit a merge request. They do not 164replace `learning git <https://git-scm.com/doc>`__ but they should be 165sufficient to make some of the more confusing steps obvious. 166 167- `Register an account <https://gitlab.freedesktop.org/users/sign_in>`_ in 168 the freedesktop.org GitLab instance. 169- `Fork libinput <https://gitlab.freedesktop.org/libinput/libinput/-/forks/new>`_ 170 into your username's namespace. Select public visibility. 171- Get libinput's main repository. git will call this repository ``origin``. :: 172 173 git clone https://gitlab.freedesktop.org/libinput/libinput.git 174 175- Add the forked git repository to your remotes (replace ``USERNAME`` 176 with your username). git will call this repository ``gitlab``. :: 177 178 cd /path/to/libinput.git 179 git remote add gitlab git@gitlab.freedesktop.org:USERNAME/libinput.git 180 git fetch gitlab 181 182- Create a new branch and commit your changes to that branch. :: 183 184 git switch -C mynewbranch 185 # edit files, make changes 186 git add file1 file2 187 git commit -s 188 # edit commit message in the editor 189 190 Replace ``mynewbranch`` (here and in the commands below) with a meaningful 191 name. See :ref:`contributing_commit_messages` for details on the commit 192 message format. 193 194- Push your changes to your fork and submit a merge request :: 195 196 git push gitlab mynewbranch 197 198 This command will print the URL to file a merge request, you then only 199 have to click through. Alternatively you can go to: 200 201 https://gitlab.freedesktop.org/USERNAME/libinput/merge_requests 202 203 Select your branch name to merge and ``libinput/libinput`` ``main`` as target branch. 204 205- Verify that the CI completes successfully by visiting the merge request 206 page. A successful pipeline shows only green ticks, failure is indicated 207 by a red cross or a yellow exclamation mark (see 208 the `GitLab Docs 209 <https://docs.gitlab.com/ee/ci/pipelines/#pipeline-mini-graphs>`__). For 210 details about the failures, click on the failed jobs in the pipelines 211 and/or click the ``Expand`` button in the box for the test summaries. 212 213 A merge request without a successful pipeline may never be looked at by a 214 maintainer. 215 216- If changes are requested by the maintainers, please **amend** the 217 commit(s) and **force-push** the updated branch. :: 218 219 # edits in file foo.c 220 git add foo.c 221 git commit --amend 222 git push -f gitlab mynewbranch 223 224 A force-push will re-trigger the CI and notify the merge request that new 225 changes are available. 226 227 If the branch contains more than one commit, please look at 228 `git interactive rebases 229 <https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History>`__ 230 to learn how to change multiple commits, or squash new changes into older 231 commits. 232 233------------------------------------------------------------------------------ 234Commit History 235------------------------------------------------------------------------------ 236 237libinput strives to have a 238`linear, 'recipe' style history <http://www.bitsnbites.eu/git-history-work-log-vs-recipe/>`_ 239This means that every commit should be small, digestible, stand-alone, and 240functional. Rather than a purely chronological commit history like this: :: 241 242 doc: final docs for view transforms 243 fix tests when disabled, redo broken doc formatting 244 better transformed-view iteration (thanks Hannah!) 245 try to catch more cases in tests 246 tests: add new spline test 247 fix compilation on splines 248 doc: notes on reticulating splines 249 compositor: add spline reticulation for view transforms 250 251We aim to have a clean history which only reflects the final state, broken up 252into functional groupings: :: 253 254 compositor: add spline reticulation for view transforms 255 compositor: new iterator for view transforms 256 tests: add view-transform correctness tests 257 doc: fix Doxygen formatting for view transforms 258 259This ensures that the final patch series only contains the final state, 260without the changes and missteps taken along the development process. 261 262The first line of a commit message should contain a prefix indicating 263what part is affected by the patch followed by one sentence that 264describes the change. For example: :: 265 266 touchpad: add software button behavior 267 fallback: disable button debouncing on device foo 268 269If in doubt what prefix to use, look at other commits that change the 270same file(s) as the patch being sent. 271 272.. _contributing_commit_messages: 273 274------------------------------------------------------------------------------ 275Commit Messages 276------------------------------------------------------------------------------ 277 278When you re-send patches, revised or not, it would be very good to document the 279changes compared to the previous revision in the commit message and/or the 280merge request. If you have already received Reviewed-by or Acked-by tags, you 281should evaluate whether they still apply and include them in the respective 282commit messages. Otherwise the tags may be lost, reviewers miss the credit they 283deserve, and the patches may cause redundant review effort. 284 285For further reading, please see 286`'on commit messages' <http://who-t.blogspot.de/2009/12/on-commit-messages.html>`_ 287as a general guideline on what commit messages should contain. 288 289------------------------------------------------------------------------------ 290Coding Style 291------------------------------------------------------------------------------ 292 293Please see the `CODING_STYLE.md 294<https://gitlab.freedesktop.org/libinput/libinput/blob/main/CODING_STYLE.md>`_ 295document in the source tree. 296 297------------------------------------------------------------------------------ 298Tracking patches and follow-ups 299------------------------------------------------------------------------------ 300 301Once submitted to GitLab, your patches will be reviewed by the libinput 302development team on GitLab. Review may be entirely positive and result in your 303code landing instantly, in which case, great! You're done. However, we may ask 304you to make some revisions: fixing some bugs we've noticed, working to a 305slightly different design, or adding documentation and tests. 306 307If you do get asked to revise the patches, please bear in mind the notes above. 308You should use ``git rebase -i`` to make revisions, so that your patches 309follow the clear linear split documented above. Following that split makes 310it easier for reviewers to understand your work, and to verify that the code 311you're submitting is correct. 312 313A common request is to split single large patch into multiple patches. This can 314happen, for example, if when adding a new feature you notice a bug in 315libinput's core which you need to fix to progress. Separating these changes 316into separate commits will allow us to verify and land the bugfix quickly, 317pushing part of your work for the good of everyone, whilst revision and 318discussion continues on the larger feature part. It also allows us to direct 319you towards reviewers who best understand the different areas you are 320working on. 321 322When you have made any requested changes, please rebase the commits, verify 323that they still individually look good, then force-push your new branch to 324GitLab. This will update the merge request and notify everyone subscribed to 325your merge request, so they can review it again. 326 327There are also many GitLab CLI clients, if you prefer to avoid the web 328interface. It may be difficult to follow review comments without using the 329web interface though, so we do recommend using this to go through the review 330process, even if you use other clients to track the list of available 331patches. 332 333------------------------------------------------------------------------------ 334Failed pipeline errors 335------------------------------------------------------------------------------ 336 337After submitting your merge request to GitLab, you might receive an email 338informing you that your pipeline failed. 339 340Visit your merge request page and check the `pipeline mini graph 341<https://docs.gitlab.com/ee/ci/pipelines/#pipeline-mini-graphs>`_ to know which 342step failed. 343 344Follow the appropriate section to fix the errors. 345 346~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 347Committed gitlab-ci.yml differs from generated gitlab-ci.yml. Please verify 348~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 349 350When your merge request modifies the CI templates, you might see this error 351mainly due two reasons: the wrong file was modified and/or 352``ci-fairy generate-template`` wasn't run. 353 354``.gitlab-ci.yaml`` is auto generated, changes should be made in: 355 356- ``.gitlab-ci/ci.template`` 357 358- ``.gitlab-ci/config.yaml`` 359 360Once the changes are ready, run 361`ci-fairy <https://freedesktop.pages.freedesktop.org/ci-templates/ci-fairy.html#templating-gitlab-ci-yml>`_ 362to update ``.gitlab-ci.yaml``: :: 363 364 ci-fairy generate-template 365 366Finally, force-push you changes. See :ref:`contributing_submitting_code` for 367more details. 368 369~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 370Build errors 371~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 372 373Usually, checking the CI log is enough to catch this errors. However, your merge 374request is built using different configurations you might have not tested. 375 376In order to fix this kind of problems, you can compile libinput using the same 377flags used by the CI. 378 379For example, if an error is found in the ``build-no-libwacom`` step, open the 380log and search the build options: :: 381 382 [...] 383 + rm -rf 'build dir' 384 + meson 'build dir' -Dlibwacom=false 385 The Meson build system 386 [...] 387 388Use the same flags to fix the issue and force-push you changes. See 389:ref:`contributing_submitting_code` for more details. 390 391~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 392Test errors 393~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 394 395The test suite is run for your merge request to check for bugs, regressions and 396memory leaks among other issues. 397 398Open the CI error log and search for a message similar to: :: 399 400 :: Failure: ../test/test-touchpad.c:465: touchpad_2fg_scroll_slow_distance(synaptics-t440) 401 402See :ref:`test-suite` to learn how to run the failing tests. 403 404Once the tests are fixed, force-push you changes. See 405:ref:`contributing_submitting_code` for more details. 406