Debian Codegraph @

doc/user/contributing.rst

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