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 --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 82libinput has a roughly three-parts architecture: 83 84- the front-end code which handles the ``libinput_some_function()`` API calls in ``libinput.c`` 85- the generic evdev interface handling which maps those API calls to the 86 backend calls (``evdev.c``). 87- there are device-specific backends which do most of the actual work - 88 ``evdev-mt-touchpad.c`` is the one for touchpads for example. 89 90In general, things that only affect the internal workings of a device only 91get implemented in the device-specific backend. You only need to touch the 92API when you are adding configuration options. For more details, please read 93the :ref:`architecture` document. There's also a `blog post describing the 94building blocks 95<https://who-t.blogspot.com/2019/03/libinputs-internal-building-blocks.html>`_ 96that may help to understand how it all fits together. 97 98Documentation is in ``/doc/api`` for the doxygen-generated API documentation. 99These are extracted from the libinput source code directly. The 100documentation you're reading right now is in ``/doc/user`` and generated with 101sphinx. Simply running ``ninja -C builddir`` will rebuild it and the final 102product ends up in ``builddir/Documentation``. 103 104------------------------------------------------------------------------------ 105Testing the code 106------------------------------------------------------------------------------ 107 108libinput provides a bunch of :ref:`tools` to debug any changes - without 109having to install libinput. 110 111The two most useful ones are :ref:`libinput debug-events 112<libinput-debug-events>` and :ref:`libinput debug-gui <libinput-debug-gui>`. 113Both tools can be run from the build directory directly and are great for 114quick test iterations:: 115 116 $> sudo ./builddir/libinput-debug-events --verbose 117 $> sudo ./builddir/libinput-debug-gui --verbose 118 119The former provides purely textual output and is useful for verifying event 120streams from buttons, etc. The latter is particularly useful when you are 121trying to debug pointer movement or placement. ``libinput debug-gui`` will 122also visualize the raw data from the device so you can compare pointer 123behavior with what comes from the kernel. 124 125These tools create a new libinput context and will not affect your session's 126behavior. Only once you've installed libinput and restarted your session 127will your changes affect the X server/Wayland compositor. 128 129Once everything seems to be correct, it's time to run the 130:ref:`test-suite`:: 131 132 $> sudo ./builddir/libinput-test-suite 133 134This test suite can take test names etc. as arguments, have a look at 135:ref:`test-suite` for more info. There are a bunch of other tests that are 136run by the CI on merge requests, you can run those locally with :: 137 138 $> sudo ninja -C builddir check 139 140So it always pays to run that before submitting. This will also run the code 141through valgrind and pick up any memory leaks. 142 143.. _contributing_submitting_code: 144 145------------------------------------------------------------------------------ 146Submitting Code 147------------------------------------------------------------------------------ 148 149Any patches should be sent via a Merge Request (see the `GitLab docs 150<https://docs.gitlab.com/ce/gitlab-basics/add-merge-request.htm>`_) 151in the `libinput GitLab instance hosted by freedesktop.org 152<https://gitlab.freedesktop.org/libinput/libinput>`_. 153 154Below are the steps required to submit a merge request. They do not 155replace `learning git <https://git-scm.com/doc>`__ but they should be 156sufficient to make some of the more confusing steps obvious. 157 158- `Register an account <https://gitlab.freedesktop.org/users/sign_in>`_ in 159 the freedesktop.org GitLab instance. 160- `Fork libinput <https://gitlab.freedesktop.org/libinput/libinput/forks/new>`_ 161 into your username's namespace 162- Get libinput's main repository. git will call this repository ``origin``. :: 163 164 git clone https://gitlab.freedesktop.org/libinput/libinput.git 165 166- Add the forked git repository to your remotes (replace ``USERNAME`` 167 with your username). git will call this repository ``gitlab``. :: 168 169 cd /path/to/libinput.git 170 git remote add gitlab git@gitlab.freedesktop.org:USERNAME/libinput.git 171 git fetch gitlab 172 173- Create a new branch and commit your changes to that branch. :: 174 175 git switch -C mynewbranch 176 # edit files, make changes 177 git add file1 file2 178 git commit -s 179 # edit commit message in the editor 180 181 Replace ``mynewbranch`` (here and in the commands below) with a meaningful 182 name. See :ref:`contributing_commit_messages` for details on the commit 183 message format. 184 185- Push your changes to your fork and submit a merge request :: 186 187 git push gitlab mynewbranch 188 189 This command will print the URL to file a merge request, you then only 190 have to click through. Alternatively you can go to: 191 192 https://gitlab.freedesktop.org/USERNAME/libinput/merge_requests 193 194 Select your branch name to merge and ``libinput/libinput`` ``main`` as target branch. 195 196- Verify that the CI completes successfully by visiting the merge request 197 page. A successful pipeline shows only green ticks, failure is indicated 198 by a red cross or a yellow exclamation mark (see 199 the `GitLab Docs 200 <https://docs.gitlab.com/ee/ci/pipelines/#pipeline-mini-graphs>`__). For 201 details about the failures, click on the failed jobs in the pipelines 202 and/or click the ``Expand`` button in the box for the test summaries. 203 204 A merge request without a successful pipeline may never be looked at by a 205 maintainer. 206 207- If changes are requested by the maintainers, please **amend** the 208 commit(s) and **force-push** the updated branch. :: 209 210 # edits in file foo.c 211 git add foo.c 212 git commit --amend 213 git push -f gitlab mynewbranch 214 215 A force-push will re-trigger the CI and notify the merge request that new 216 changes are available. 217 218 If the branch contains more than one commit, please look at 219 `git interactive rebases 220 <https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History>`__ 221 to learn how to change multiple commits, or squash new changes into older 222 commits. 223 224------------------------------------------------------------------------------ 225Commit History 226------------------------------------------------------------------------------ 227 228libinput strives to have a 229`linear, 'recipe' style history <http://www.bitsnbites.eu/git-history-work-log-vs-recipe/>`_ 230This means that every commit should be small, digestible, stand-alone, and 231functional. Rather than a purely chronological commit history like this: :: 232 233 doc: final docs for view transforms 234 fix tests when disabled, redo broken doc formatting 235 better transformed-view iteration (thanks Hannah!) 236 try to catch more cases in tests 237 tests: add new spline test 238 fix compilation on splines 239 doc: notes on reticulating splines 240 compositor: add spline reticulation for view transforms 241 242We aim to have a clean history which only reflects the final state, broken up 243into functional groupings: :: 244 245 compositor: add spline reticulation for view transforms 246 compositor: new iterator for view transforms 247 tests: add view-transform correctness tests 248 doc: fix Doxygen formatting for view transforms 249 250This ensures that the final patch series only contains the final state, 251without the changes and missteps taken along the development process. 252 253The first line of a commit message should contain a prefix indicating 254what part is affected by the patch followed by one sentence that 255describes the change. For example: :: 256 257 touchpad: add software button behavior 258 fallback: disable button debouncing on device foo 259 260If in doubt what prefix to use, look at other commits that change the 261same file(s) as the patch being sent. 262 263.. _contributing_commit_messages: 264 265------------------------------------------------------------------------------ 266Commit Messages 267------------------------------------------------------------------------------ 268 269Commit messages **must** contain a **Signed-off-by** line with your name 270and email address. An example is: :: 271 272 A description of this commit, and it's great work. 273 274 Signed-off-by: Claire Someone <name@domain> 275 276If you're not the patch's original author, you should 277also gather S-o-b's by them (and/or whomever gave the patch to you.) The 278significance of this is that it certifies that you created the patch, that 279it was created under an appropriate open source license, or provided to you 280under those terms. This lets us indicate a chain of responsibility for the 281copyright status of the code. An example is: :: 282 283 A description of this commit, and it's great work. 284 285 Signed-off-by: Claire Someone <name@domain> 286 Signed-off-by: Ferris Crab <name@domain> 287 288When you re-send patches, revised or not, it would be very good to document the 289changes compared to the previous revision in the commit message and/or the 290merge request. If you have already received Reviewed-by or Acked-by tags, you 291should evaluate whether they still apply and include them in the respective 292commit messages. Otherwise the tags may be lost, reviewers miss the credit they 293deserve, and the patches may cause redundant review effort. 294 295For further reading, please see 296`'on commit messages' <http://who-t.blogspot.de/2009/12/on-commit-messages.html>`_ 297as a general guideline on what commit messages should contain. 298 299------------------------------------------------------------------------------ 300Coding Style 301------------------------------------------------------------------------------ 302 303Please see the `CODING_STYLE.md 304<https://gitlab.freedesktop.org/libinput/libinput/blob/main/CODING_STYLE.md>`_ 305document in the source tree. 306 307------------------------------------------------------------------------------ 308Tracking patches and follow-ups 309------------------------------------------------------------------------------ 310 311Once submitted to GitLab, your patches will be reviewed by the libinput 312development team on GitLab. Review may be entirely positive and result in your 313code landing instantly, in which case, great! You're done. However, we may ask 314you to make some revisions: fixing some bugs we've noticed, working to a 315slightly different design, or adding documentation and tests. 316 317If you do get asked to revise the patches, please bear in mind the notes above. 318You should use ``git rebase -i`` to make revisions, so that your patches 319follow the clear linear split documented above. Following that split makes 320it easier for reviewers to understand your work, and to verify that the code 321you're submitting is correct. 322 323A common request is to split single large patch into multiple patches. This can 324happen, for example, if when adding a new feature you notice a bug in 325libinput's core which you need to fix to progress. Separating these changes 326into separate commits will allow us to verify and land the bugfix quickly, 327pushing part of your work for the good of everyone, whilst revision and 328discussion continues on the larger feature part. It also allows us to direct 329you towards reviewers who best understand the different areas you are 330working on. 331 332When you have made any requested changes, please rebase the commits, verify 333that they still individually look good, then force-push your new branch to 334GitLab. This will update the merge request and notify everyone subscribed to 335your merge request, so they can review it again. 336 337There are also many GitLab CLI clients, if you prefer to avoid the web 338interface. It may be difficult to follow review comments without using the 339web interface though, so we do recommend using this to go through the review 340process, even if you use other clients to track the list of available 341patches. 342 343------------------------------------------------------------------------------ 344Failed pipeline errors 345------------------------------------------------------------------------------ 346 347After submitting your merge request to GitLab, you might receive an email 348informing you that your pipeline failed. 349 350Visit your merge request page and check the `pipeline mini graph 351<https://docs.gitlab.com/ee/ci/pipelines/#pipeline-mini-graphs>`_ to know which 352step failed. 353 354Follow the appropriate section to fix the errors. 355 356~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 357Missing "Signed-off-by: author information" 358~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 359 360As explained in :ref:`contributing_commit_messages`, every commit must contain a 361Signed-off-by line with your name and email address. 362 363When this line is not present, it can be added to your commit afterwards: :: 364 365 git commit --amend -s 366 367If the merge request contains more than one commit, it must be added to all of 368them: :: 369 370 git rebase --interactive --exec 'git commit --amend -s' main 371 372Once the problem is fixed, force-push your branch. See 373:ref:`contributing_submitting_code` for more details about how to push your code 374and interactive rebases. 375 376~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 377Committed gitlab-ci.yml differs from generated gitlab-ci.yml. Please verify 378~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 379 380When your merge request modifies the CI templates, you might see this error 381mainly due two reasons: the wrong file was modified and/or 382``ci-fairy generate-template`` wasn't run. 383 384``.gitlab-ci.yaml`` is auto generated, changes should be made in: 385 386- ``.gitlab-ci/ci.template`` 387 388- ``.gitlab-ci/config.yaml`` 389 390Once the changes are ready, run 391`ci-fairy <https://freedesktop.pages.freedesktop.org/ci-templates/ci-fairy.html#templating-gitlab-ci-yml>`_ 392to update ``.gitlab-ci.yaml``: :: 393 394 ci-fairy generate-template 395 396Finally, force-push you changes. See :ref:`contributing_submitting_code` for 397more details. 398 399~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 400Build errors 401~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 402 403Usually, checking the CI log is enough to catch this errors. However, your merge 404request is built using different configurations you might have not tested. 405 406In order to fix this kind of problems, you can compile libinput using the same 407flags used by the CI. 408 409For example, if an error is found in the ``build-no-libwacom`` step, open the 410log and search the build options: :: 411 412 [...] 413 + rm -rf 'build dir' 414 + meson 'build dir' -Dlibwacom=false 415 The Meson build system 416 [...] 417 418Use the same flags to fix the issue and force-push you changes. See 419:ref:`contributing_submitting_code` for more details. 420 421~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 422Test errors 423~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 424 425The test suite is run for your merge request to check for bugs, regressions and 426memory leaks among other issues. 427 428Open the CI error log and search for a message similar to: :: 429 430 :: Failure: ../test/test-touchpad.c:465: touchpad_2fg_scroll_slow_distance(synaptics-t440) 431 432See :ref:`test-suite` to learn how to run the failing tests. 433 434Once the tests are fixed, force-push you changes. See 435:ref:`contributing_submitting_code` for more details. 436