CONTRIBUTING.md 4.68 KB
Newer Older
1
2
3
CONTRIBUTING
============

4
Patches to igt-gpu-tools are very much welcome, we really want this to be the
Rodrigo Vivi's avatar
Rodrigo Vivi committed
5
universal set of low-level tools and testcases for kernel graphics drivers
Daniel Vetter's avatar
Daniel Vetter committed
6
7
8
on Linux and similar platforms. So please bring on porting patches, bugfixes,
improvements for documentation and new tools and testcases.

9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

The Code
--------

- The code should follow kernel coding style:
  https://www.kernel.org/doc/html/latest/process/coding-style.html

- Testcases (subtests) have to use minus signs (-) as a word separator.
  The generated documentation contains glossary of commonly used terms.

- All new test have to be described using `igt_describe()` family of
  functions. The description should contain the spirit of the test (what is
  the general idea behind the test) and *not* the letter (C to English
  translation of the test). Refer to [`igt_describe()`
  documentation][igt-describe] for more details.

- The generated documentation contains explanation of magic control blocks like
  `igt_subtest` and `igt_fixture`. Please make sure that you understand their
  roles and limitation before using/altering them.

- Also please make full use of all the helpers and convenience macros
  provided by the igt library. The semantic patch lib/igt.cocci can help with
  more automatic conversions.

[igt-describe]: https://drm.pages.freedesktop.org/igt-gpu-tools/igt-gpu-tools-Core.html#igt-describe


Sending Patches
---------------

- igt-gpu-tools is MIT licensed and we require contributions to follow the
  developer's certificate of origin: http://developercertificate.org/
Daniel Vetter's avatar
Daniel Vetter committed
41
42

- Please submit patches formatted with git send-email/git format-patch or
43
44
  equivalent to:

45
      Development mailing list for IGT GPU Tools <igt-dev@lists.freedesktop.org>
46

Rodrigo Vivi's avatar
Rodrigo Vivi committed
47
48
  For patches affecting the driver directly please "cc" the appropriate driver
  mailing list and make sure you are using:
49

Rodrigo Vivi's avatar
Rodrigo Vivi committed
50
      --subject-prefix="PATCH i-g-t"
Daniel Vetter's avatar
Daniel Vetter committed
51

Rodrigo Vivi's avatar
Rodrigo Vivi committed
52
53
54
  so IGT patches are easily identified in the massive amount mails on driver's
  mailing list. To ensure this is always done, meson.sh (and autogen.sh) will
  run:
Daniel Vetter's avatar
Daniel Vetter committed
55

56
      git config format.subjectprefix "PATCH i-g-t"
Daniel Vetter's avatar
Daniel Vetter committed
57

58
  on its first invocation.
Daniel Vetter's avatar
Daniel Vetter committed
59

60
61
62
- Patches need to be reviewed on the mailing list. Exceptions only apply for
  testcases and tooling for drivers with just a single contributor (e.g. vc4).
  In this case patches must still be submitted to the mailing list first.
Rhys Kidd's avatar
Rhys Kidd committed
63
  Testcase should preferably be cross-reviewed by the same people who write and
64
  review the kernel feature itself.
Daniel Vetter's avatar
Daniel Vetter committed
65
66
67

- When patches from new contributors (without commit access) are stuck, for
  anything related to the regular releases, issues with packaging and
68
  integrating platform support or any other igt-gpu-tools issues, please
Thomas Wood's avatar
Thomas Wood committed
69
  contact one of the maintainers (listed in the MAINTAINERS file) and cc the
70
  igt-dev mailing list.
Daniel Vetter's avatar
Daniel Vetter committed
71

Rhys Kidd's avatar
Rhys Kidd committed
72
73
- Changes to the testcases are automatically tested. Take the results into
  account before merging.
Daniel Vetter's avatar
Daniel Vetter committed
74

75
76

Commit Rights
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
-------------

Commit rights will be granted to anyone who requests them and fulfills the
below criteria:

- Submitted a few (5-10 as a rule of thumb) non-trivial (not just simple
  spelling fixes and whitespace adjustment) patches that have been merged
  already.

- Are actively participating on discussions about their work (on the mailing
  list or IRC). This should not be interpreted as a requirement to review other
  peoples patches but just make sure that patch submission isn't one-way
  communication. Cross-review is still highly encouraged.

- Will be regularly contributing further patches. This includes regular
  contributors to other parts of the open source graphics stack who only
  do the oddball rare patch within igt itself.

- Agrees to use their commit rights in accordance with the documented merge
  criteria, tools, and processes.

98
99
100
101
Create a gitlab account at https://gitlab.freedesktop.org/ and apply
for access to the IGT gitlab project,
http://gitlab.freedesktop.org/drm/igt-gpu-tools and please ping the
maintainers if your request is stuck.
102
103
104
105
106
107
108
109

Committers are encouraged to request their commit rights get removed when they
no longer contribute to the project. Commit rights will be reinstated when they
come back to the project.

Maintainers and committers should encourage contributors to request commit
rights, especially junior contributors tend to underestimate their skills.

110

111
112
113
114
115
116
117
118
119
120
121
122
123
Code of Conduct
---------------

Please be aware the fd.o Code of Conduct also applies to igt:

https://www.freedesktop.org/wiki/CodeOfConduct/

See the MAINTAINERS file for contact details of the igt maintainers.

Abuse of commit rights, like engaging in commit fights or willfully pushing
patches that violate the documented merge criteria, will also be handled through
the Code of Conduct enforcement process.

Daniel Vetter's avatar
Daniel Vetter committed
124
Happy hacking!