Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: media: update maintainer-entry-profile for multi-committers
As the media subsystem will experiment with a multi-committers model,
update the Maintainer's entry profile to the new rules.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
Reviewed-by: Sean Young <sean@mess.org>
Reviewed-by: Bryan O'Donoghue <bryan.odonoghue@linaro.org>
Reviewed-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>
+339
-66
+339
-66
Documentation/driver-api/media/maintainer-entry-profile.rst
+339
-66
Documentation/driver-api/media/maintainer-entry-profile.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
1
3
Media Subsystem Profile
2
4
=======================
3
5
4
6
Overview
5
7
--------
6
8
7
-
The media subsystem covers support for a variety of devices: stream
8
-
capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC
9
-
and media pipeline control.
9
+
The Linux Media Community (aka: the LinuxTV Community) is formed by
10
+
developers working on Linux Kernel Media Subsystem, together with users
11
+
who also play an important role in testing the code.
10
12
11
-
It covers, mainly, the contents of those directories:
13
+
The Media Subsystem has code to support a wide variety of media-related
14
+
devices: stream capture, analog and digital TV streams, cameras,
15
+
video codecs, video processing (resizers, etc.), radio, remote controllers,
16
+
HDMI CEC and media pipeline control.
17
+
18
+
The Media Subsystem consists of the following directories in the kernel
19
+
tree:
12
20
13
21
- drivers/media
14
22
- drivers/staging/media
23
+
- include/media
24
+
- Documentation/devicetree/bindings/media/\ [1]_
15
25
- Documentation/admin-guide/media
16
26
- Documentation/driver-api/media
17
27
- Documentation/userspace-api/media
18
-
- Documentation/devicetree/bindings/media/\ [1]_
19
-
- include/media
20
28
21
29
.. [1] Device tree bindings are maintained by the
22
30
OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers
23
31
(see the MAINTAINERS file). So, changes there must be reviewed
24
-
by them before being merged via the media subsystem's development
32
+
by them before being merged into the media subsystem's development
25
33
tree.
26
34
27
35
Both media userspace and Kernel APIs are documented and the documentation
28
36
must be kept in sync with the API changes. It means that all patches that
29
37
add new features to the subsystem must also bring changes to the
30
-
corresponding API files.
38
+
corresponding API documentation.
31
39
32
-
Due to the size and wide scope of the media subsystem, media's
33
-
maintainership model is to have sub-maintainers that have a broad
34
-
knowledge of a specific aspect of the subsystem. It is the sub-maintainers'
35
-
task to review the patches, providing feedback to users if the patches are
36
-
following the subsystem rules and are properly using the media kernel and
37
-
userspace APIs.
40
+
Media Maintainers
41
+
-----------------
38
42
39
-
Patches for the media subsystem must be sent to the media mailing list
40
-
at linux-media@vger.kernel.org as plain text only e-mail. Emails with
41
-
HTML will be automatically rejected by the mail server. It could be wise
42
-
to also copy the sub-maintainer(s).
43
+
Media Maintainers are not just people capable of writing code, but they
44
+
are developers who have demonstrated their ability to collaborate with
45
+
the team, get the most knowledgeable people to review code, contribute
46
+
high-quality code, and follow through to fix issues (in code or tests).
47
+
48
+
Due to the size and wide scope of the media subsystem, multiple layers of
49
+
maintainers are required, each with their own areas of expertise:
50
+
51
+
- **Media Driver Maintainer**:
52
+
Responsible for one or more drivers within the Media Subsystem. They
53
+
are listed in the MAINTAINERS file as maintainer for those drivers. Media
54
+
Driver Maintainers review patches for those drivers, provide feedback if
55
+
patches do not follow the subsystem rules, or are not using the
56
+
media kernel or userspace APIs correctly, or if they have poor code
57
+
quality.
58
+
59
+
If you are the patch author, you work with other Media
60
+
Maintainers to ensure your patches are reviewed.
61
+
62
+
Some Media Driver Maintainers have additional responsibilities. They have
63
+
been granted Patchwork access and keep
64
+
`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
65
+
up to date, decide when patches are ready for merging, and create Pull
66
+
Requests for the Media Subsystem Maintainers to merge.
67
+
68
+
- **Media Core Maintainer**:
69
+
Media Driver Maintainers with Patchwork access who are also responsible for
70
+
one or more media core frameworks.
71
+
72
+
Core framework changes are done via consensus between the relevant Media
73
+
Core Maintainers. Media Maintainers may include core framework changes in
74
+
their Pull Requests if they are signed off by the relevant Media Core
75
+
Maintainers.
76
+
77
+
- **Media Subsystem Maintainers**:
78
+
Media Core Maintainers who are also responsible for the subsystem as a
79
+
whole, with access to the entire subsystem. Responsible for merging Pull
80
+
Requests from other Media Maintainers.
81
+
82
+
Userspace API/ABI changes are made via consensus among Media Subsystem
83
+
Maintainers\ [2]_. Media Maintainers may include API/ABI changes in
84
+
their Pull Requests if they are signed off by all Media Subsystem
85
+
Maintainers.
86
+
87
+
All Media Maintainers shall agree with the Kernel development process as
88
+
described in Documentation/process/index.rst and with the Kernel development
89
+
rules in the Kernel documentation, including its code of conduct.
90
+
91
+
Media Maintainers are often reachable via the #linux-media IRC channel at OFTC.
92
+
93
+
.. [2] Everything that would break backward compatibility with existing
94
+
non-kernel code are API/ABI changes. This includes ioctl and sysfs
95
+
interfaces, v4l2 controls, and their behaviors.
96
+
97
+
Patchwork Access
98
+
----------------
99
+
100
+
All Media Maintainers who have been granted Patchwork access shall ensure that
101
+
`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
102
+
will reflect the current status, e.g. patches shall be delegated to the Media
103
+
Maintainer who is handling them and the patch status shall be updated according
104
+
to these rules:
105
+
106
+
- ``Under Review``: Used if the patch requires a second opinion
107
+
or when it is part of a Pull Request;
108
+
- ``Superseded``: There is a newer version of the patch posted to the
109
+
mailing list.
110
+
- ``Duplicated``: There was another patch doing the same thing from someone
111
+
else that was accepted.
112
+
- ``Not Applicable``: Use for patch series that are not merged at media.git
113
+
tree (e.g. drm, dmabuf, upstream merge, etc.) but were cross-posted to the
114
+
linux-media mailing list.
115
+
- ``Accepted``: Once a patch is merged in the multi-committer tree. Only Media
116
+
Maintainers with commit rights are allowed to set this state.
117
+
118
+
If Media Maintainers decide not to accept a patch, they should reply to the
119
+
patch authors by e‑mail, explaining why it is not accepted, and
120
+
update `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
121
+
accordingly with one of the following statuses:
122
+
123
+
- ``Changes Requested``: if a new revision was requested;
124
+
- ``Rejected``: if the proposed change is not acceptable at all.
125
+
126
+
.. Note::
127
+
128
+
Patchwork supports a couple of clients to help semi-automate
129
+
status updates via its REST interface:
130
+
131
+
https://patchwork.readthedocs.io/en/latest/usage/clients/
132
+
133
+
For patches that fall within their area of responsibility a Media Maintainer
134
+
also decides when those patches are ready for merging, and create Pull Requests
135
+
for the Media Subsystem Maintainers to merge.
136
+
137
+
The most important aspect of becoming a Media Maintainer with Patchwork access
138
+
is that you have demonstrated an ability to give good code reviews. We value
139
+
your ability to deliver thorough, constructive code reviews.
140
+
141
+
As such, potential maintainers must earn enough credibility and trust from the
142
+
Linux Media Community. To do that, developers shall be familiar with the open
143
+
source model and have been active in the Linux Kernel community for some time,
144
+
and, in particular, in the media subsystem.
145
+
146
+
In addition to actually making the code changes, you are basically
147
+
demonstrating your:
148
+
149
+
- commitment to the project;
150
+
- ability to collaborate with the team and communicate well;
151
+
- understanding of how upstream and the Linux Media Community work
152
+
(policies, processes for testing, code review, ...)
153
+
- reasonable knowledge about:
154
+
155
+
- the Kernel development process:
156
+
Documentation/process/index.rst
157
+
158
+
- the Media development profile:
159
+
Documentation/driver-api/media/maintainer-entry-profile.rst
160
+
161
+
- understanding of the projects' code base and coding style;
162
+
- ability to provide feedback to the patch authors;
163
+
- ability to judge when a patch might be ready for review and to submit;
164
+
- ability to write good code (last but certainly not least).
165
+
166
+
Media Driver Maintainers that desire to get Patchwork access are encouraged
167
+
to participate at the yearly Linux Media Summit, typically co-located with
168
+
a Linux-related conference. These summits are announced on the linux-media
169
+
mailing list.
170
+
171
+
If you are doing such tasks and have become a valued developer, an
172
+
existing Media Maintainer can nominate you to the Media Subsystem Maintainers.
173
+
174
+
The ultimate responsibility for accepting a nominated maintainer is up to
175
+
the subsystem's maintainers. The nominated maintainer must have earned a trust
176
+
relationship with all Media Subsystem Maintainers, as, by being granted
177
+
Patchwork access, you will take over part of their maintenance tasks.
178
+
179
+
Media development sites
180
+
-----------------------
181
+
182
+
The `LinuxTV <https://linuxtv.org/>`_ web site hosts news about the subsystem,
183
+
together with:
184
+
185
+
- `Wiki pages <https://www.linuxtv.org/wiki/index.php/Main_Page>`_;
186
+
- `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_;
187
+
- `Linux Media documentation <https://linuxtv.org/docs.php>`_;
188
+
- and more.
189
+
190
+
The main development trees used by the media subsystem are at:
191
+
192
+
- Stable tree:
193
+
- https://git.linuxtv.org/media.git/
194
+
195
+
- Media committers tree:
196
+
- https://gitlab.freedesktop.org/linux-media/media-committers.git
197
+
198
+
Please note that it can be rebased, although only as a last resort.
199
+
200
+
- Media development trees, including apps and CI:
201
+
202
+
- https://git.linuxtv.org/
203
+
- https://gitlab.freedesktop.org/linux-media/
204
+
205
+
206
+
.. _Media development workflow:
207
+
208
+
Media development workflow
209
+
++++++++++++++++++++++++++
210
+
211
+
All changes for the media subsystem shall be sent first as e-mails to the
212
+
media mailing list, following the process documented at
213
+
Documentation/process/index.rst.
214
+
215
+
It means that patches shall be submitted as plain text only via e-mail to
216
+
linux-media@vger.kernel.org (aka: LMML). While subscription is not mandatory,
217
+
you can find details about how to subscribe to it and to see its archives at:
218
+
219
+
https://subspace.kernel.org/vger.kernel.org.html
220
+
221
+
Emails with HTML will be automatically rejected by the mail server.
222
+
223
+
It could be wise to also copy the relevant Media Maintainer(s). You should use
224
+
``scripts/get_maintainers.pl`` to identify whom else needs to be copied.
225
+
Please always copy driver's authors and maintainers.
226
+
227
+
To minimize the chance of merge conflicts for your patch series, and make it
228
+
easier to backport patches to stable Kernels, we recommend that you use the
229
+
following baseline for your patch series:
230
+
231
+
1. Features for the next mainline release:
232
+
233
+
- baseline shall be the ``media-committers.git next`` branch;
234
+
235
+
2. Bug fixes for the next mainline release:
236
+
237
+
- baseline shall be the ``media-committers.git next`` branch. If the
238
+
changes depend on a fix from the ``media-committers.git fixes``
239
+
branch, then you can use that as baseline.
240
+
241
+
3. Bug fixes for the current mainline release (-rcX):
242
+
243
+
- baseline shall be the latest mainline -rcX release or the
244
+
``media-committers.git fixes`` branch if changes depend on a mainline
245
+
fix that is not yet merged;
246
+
247
+
.. Note::
248
+
249
+
See https://www.kernel.org/category/releases.html for an overview
250
+
about Kernel release types.
251
+
252
+
Patches with fixes shall have:
253
+
254
+
- a ``Fixes:`` tag pointing to the first commit that introduced the bug;
255
+
- when applicable, a ``Cc: stable@vger.kernel.org``.
256
+
257
+
Patches that were fixing bugs publicly reported by someone at the
258
+
linux-media@vger.kernel.org mailing list shall have:
259
+
260
+
- a ``Reported-by:`` tag immediately followed by a ``Closes:`` tag.
261
+
262
+
Patches that change API shall update documentation accordingly at the
263
+
same patch series.
264
+
265
+
See Documentation/process/index.rst for more details about e-mail submission.
266
+
267
+
Once a patch is submitted, it may follow either one of the following
268
+
workflows:
269
+
270
+
a. Media Maintainers' workflow: Media Maintainers post the Pull Requests,
271
+
which are handled by the Media Subsystem Maintainers::
272
+
273
+
+-------+ +------------+ +------+ +-------+ +---------------------+
274
+
|e-mail |-->|picked up by|-->|code |-->|pull |-->|Subsystem Maintainers|
275
+
|to LMML| |Patchwork | |review| |request| |merge in |
276
+
| | | | | | | | |media-committers.git |
277
+
+-------+ +------------+ +------+ +-------+ +---------------------+
278
+
279
+
For this workflow, Pull Requests are generated by Media Maintainers with
280
+
Patchwork access. If you do not have Patchwork access, then please don't
281
+
submit Pull Requests, as they will not be processed.
282
+
283
+
b. Media Committers' workflow: patches are handled by Media Maintainers with
284
+
commit rights::
285
+
286
+
+-------+ +------------+ +------+ +--------------------------+
287
+
|e-mail |-->|picked up by|-->|code |-->|Media Committers merge in |
288
+
|to LMML| |Patchwork | |review| |media-committers.git |
289
+
+-------+ +------------+ +------+ +--------------------------+
290
+
291
+
When patches are picked up by
292
+
`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
293
+
and when merged at media-committers, Media CI bots will check for errors and
294
+
may provide e-mail feedback about patch problems. When this happens, the patch
295
+
submitter must fix them or explain why the errors are false positives.
296
+
297
+
Patches will only be moved to the next stage in these two workflows if they
298
+
pass on Media CI or if there are false-positives in the Media CI reports.
299
+
300
+
For both workflows, all patches shall be properly reviewed at
301
+
linux-media@vger.kernel.org (LMML) before being merged in
302
+
``media-committers.git``. Media patches will be reviewed in a timely manner
303
+
by the maintainers and reviewers as listed in the MAINTAINERS file.
304
+
305
+
Media Maintainers shall request reviews from other Media Maintainers and
306
+
developers where applicable, i.e. because those developers have more
307
+
knowledge about some areas that are changed by a patch.
308
+
309
+
There shall be no open issues or unresolved or conflicting feedback
310
+
from anyone. Clear them up first. Defer to the Media Subsystem
311
+
Maintainers if needed.
312
+
313
+
Failures during e-mail submission
314
+
+++++++++++++++++++++++++++++++++
43
315
44
316
Media's workflow is heavily based on Patchwork, meaning that, once a patch
45
317
is submitted, the e-mail will first be accepted by the mailing list
···
319
47
320
48
- https://patchwork.linuxtv.org/project/linux-media/list/
321
49
322
-
If it doesn't automatically appear there after a few minutes, then
50
+
If it doesn't automatically appear there after some time [3]_, then
323
51
probably something went wrong on your submission. Please check if the
324
-
email is in plain text\ [2]_ only and if your emailer is not mangling
52
+
email is in plain text\ [4]_ only and if your emailer is not mangling
325
53
whitespaces before complaining or submitting them again.
326
54
327
-
You can check if the mailing list server accepted your patch, by looking at:
55
+
To troubleshoot problems, you should first check if the mailing list
56
+
server has accepted your patch, by looking at:
328
57
329
58
- https://lore.kernel.org/linux-media/
330
59
331
-
.. [2] If your email contains HTML, the mailing list server will simply
60
+
If the patch is there and not at
61
+
`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
62
+
it is likely that your e-mailer mangled the patch. Patchwork internally
63
+
has logic that checks if the received e-mail contains a valid patch.
64
+
Any whitespace and new line breakages mangling the patch won't be recognized by
65
+
`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
66
+
and such a patch will be rejected.
67
+
68
+
.. [3] It usually takes a few minutes for the patch to arrive, but
69
+
the e-mail server may be busy, so it may take a longer time
70
+
for a patch to be picked by
71
+
`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_.
72
+
73
+
.. [4] If your email contains HTML, the mailing list server will simply
332
74
drop it, without any further notice.
333
75
76
+
.. _media-developers-gpg:
334
77
335
-
Media maintainers
336
-
+++++++++++++++++
78
+
Authentication for pull and merge requests
79
+
++++++++++++++++++++++++++++++++++++++++++
337
80
338
-
At the media subsystem, we have a group of senior developers that
339
-
are responsible for doing the code reviews at the drivers (also known as
340
-
sub-maintainers), and another senior developer responsible for the
341
-
subsystem as a whole. For core changes, whenever possible, multiple
342
-
media maintainers do the review.
81
+
The authenticity of developers submitting Pull Requests and merge requests
82
+
shall be validated by using the Linux Kernel Web of Trust, with PGP signing
83
+
at some moment. See: :ref:`kernel_org_trust_repository`.
343
84
344
-
The media maintainers that work on specific areas of the subsystem are:
85
+
With the Pull Request workflow, Pull Requests shall use PGP-signed tags.
345
86
346
-
- Remote Controllers (infrared):
347
-
Sean Young <sean@mess.org>
87
+
For more details about PGP signing, please read
88
+
Documentation/process/maintainer-pgp-guide.rst.
348
89
349
-
- HDMI CEC:
350
-
Hans Verkuil <hverkuil@kernel.org>
90
+
Subsystem Media Maintainers
91
+
---------------------------
351
92
352
-
- Media controller drivers:
353
-
Laurent Pinchart <laurent.pinchart@ideasonboard.com>
354
-
355
-
- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers:
356
-
Sakari Ailus <sakari.ailus@linux.intel.com>
357
-
358
-
- V4L2 drivers and core V4L2 frameworks:
359
-
Hans Verkuil <hverkuil@kernel.org>
360
-
361
-
The subsystem maintainer is:
362
-
Mauro Carvalho Chehab <mchehab@kernel.org>
363
-
364
-
Media maintainers may delegate a patch to other media maintainers as needed.
365
-
On such case, checkpatch's ``delegate`` field indicates who's currently
366
-
responsible for reviewing a patch.
93
+
The subsystem maintainers are:
94
+
- Mauro Carvalho Chehab <mchehab@kernel.org>
95
+
- Hans Verkuil <hverkuil@kernel.org>
367
96
368
97
Submit Checklist Addendum
369
98
-------------------------
···
379
106
implementing the media APIs:
380
107
381
108
==================== =======================================================
382
-
Type Tool
109
+
Type Utility
383
110
==================== =======================================================
384
-
V4L2 drivers\ [3]_ ``v4l2-compliance``
111
+
V4L2 drivers\ [5]_ ``v4l2-compliance``
385
112
V4L2 virtual drivers ``contrib/test/test-media``
386
113
CEC drivers ``cec-compliance``
387
114
==================== =======================================================
388
115
389
-
.. [3] The ``v4l2-compliance`` also covers the media controller usage inside
390
-
V4L2 drivers.
391
-
392
-
Other compliance tools are under development to check other parts of the
393
-
subsystem.
116
+
.. [5] The ``v4l2-compliance`` utility also covers the media controller usage
117
+
inside V4L2 drivers.
394
118
395
119
Those tests need to pass before the patches go upstream.
396
120
···
403
133
404
134
Be sure to not introduce new warnings on your patches without a
405
135
very good reason.
136
+
137
+
Please see `Media development workflow`_ for e-mail submission rules.
406
138
407
139
Style Cleanup Patches
408
140
+++++++++++++++++++++
···
445
173
In particular, we accept lines with more than 80 columns:
446
174
447
175
- on strings, as they shouldn't be broken due to line length limits;
448
-
- when a function or variable name need to have a big identifier name,
449
-
which keeps hard to honor the 80 columns limit;
176
+
- when a function or variable name needs to have a long identifier name,
177
+
which makes hard to honor the 80 columns limit;
450
178
- on arithmetic expressions, when breaking lines makes them harder to
451
179
read;
452
-
- when they avoid a line to end with an open parenthesis or an open
180
+
- when they avoid a line ending with an open parenthesis or an open
453
181
bracket.
454
182
455
183
Key Cycle Dates
456
184
---------------
457
185
458
-
New submissions can be sent at any time, but if they intend to hit the
186
+
New submissions can be sent at any time, but if they are intended to hit the
459
187
next merge window they should be sent before -rc5, and ideally stabilized
460
188
in the linux-media branch by -rc6.
461
189
462
190
Review Cadence
463
191
--------------
464
192
465
-
Provided that your patch is at https://patchwork.linuxtv.org, it should
466
-
be sooner or later handled, so you don't need to re-submit a patch.
193
+
Provided that your patch has landed in
194
+
`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_, it
195
+
should be sooner or later handled, so you don't need to re-submit a patch.
467
196
468
-
Except for bug fixes, we don't usually add new patches to the development
469
-
tree between -rc6 and the next -rc1.
197
+
Except for important bug fixes, we don't usually add new patches to the
198
+
development tree between -rc6 and the next -rc1.
470
199
471
200
Please notice that the media subsystem is a high traffic one, so it
472
201
could take a while for us to be able to review your patches. Feel free
473
202
to ping if you don't get a feedback in a couple of weeks or to ask
474
-
other developers to publicly add Reviewed-by and, more importantly,
203
+
other developers to publicly add ``Reviewed-by:`` and, more importantly,
475
204
``Tested-by:`` tags.
476
205
477
206
Please note that we expect a detailed description for ``Tested-by:``,
478
-
identifying what boards were used at the test and what it was tested.
207
+
identifying what boards were used during the test and what it was tested.