[PATCHv7 0/3] docs: media: multicommitters model documentation

[PATCHv7 0/3] docs: media: multicommitters model documentation

[Hans Verkuil]

Here is v7, based on yesterday's meeting.

The main change is what a "Media Maintainer" is. In v6 I considered a
Media Maintainer to be someone who has patchwork access and has
responsibility for an area of the media subsystem, deciding when a
patch is ready to be merged and making PRs.

That was confusing since that name was too generic.

In v7 a "Media Driver Maintainer" is anyone who is listed in MAINTAINERS
for a media driver. "Media Driver/Core/Subsystem Maintainers" are collectively
called "Media Maintainers".

I also added the distinction of being granted patchwork access: only Media
Maintainers with patchwork access can decide when a patch is ready to be
merged and make PRs. If you are trusted enough to be able to do that, then
patchwork access is granted since you need that to be able to delegate patches
and update the patch status.

I'm still not entirely satisfied with this, as I would prefer to have a
specific name for such maintainers. Saying "Media Maintainers with patchwork
access" is a mouthful. I can't think of a good name, though.

So the hierarchy is as follows:

- Media Contributor: posts patches
- Media Driver Maintainer: as above, but also reviews patches and is
  listed in MAINTAINERS
- Media Driver Maintainer with patchwork access: decides when patches are
  ready for mainline, posts PRs, keeps patchwork up to date. Optionally
  has commit rights.
- Media Core Maintainer: same as above, but is also responsible for one
  or more media core frameworks.
- Media Subsystem Maintainer: as above, but is also responsible for the
  whole subsystem, processes PRs and has commit rights.



Patch 1/3 updates maintainer-entry-profile.rst: it introduces the
three Media maintainer levels (Media Driver Maintainer, Media Core Maintainer
and Media Subsystem Maintainer) and what the responsibilities are.

Patch 2/3 adds back and updates the list of Media Maintainers that
disappeared in patch 1/3. Please verify this whether the email
addresses are the correct ones, and verify that the areas of responsibility
are correct and that nothing is missing.

Patch 3/3 adds media-committer.rst: that focusses on the additional
commit rights that can be granted to a Media Maintainer.

It feels much more consistent to me, I'm looking forward to the
review comments.

I have uploaded the documentation with these patches here:

https://hverkuil.home.xs4all.nl/spec/driver-api/maintainer-entry-profile.html
https://hverkuil.home.xs4all.nl/spec/driver-api/media-committer.html

Regards,

	Hans

Hans Verkuil (1):
  docs: media: document Media Maintainers

Mauro Carvalho Chehab (2):
  docs: media: update maintainer-entry-profile for multi-committers
  docs: media: document media multi-committers rules and process

 Documentation/driver-api/media/index.rst      |   1 +
 .../media/maintainer-entry-profile.rst        | 436 +++++++++++++++---
 .../driver-api/media/media-committer.rst      | 197 ++++++++
 3 files changed, 577 insertions(+), 57 deletions(-)
 create mode 100644 Documentation/driver-api/media/media-committer.rst

-- 
2.51.0

[PATCHv7 1/3] docs: media: update maintainer-entry-profile for multi-committers

[Hans Verkuil]

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

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>
Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>
---
 .../media/maintainer-entry-profile.rst        | 382 +++++++++++++++---
 1 file changed, 321 insertions(+), 61 deletions(-)

diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
index 2127e5b15e8f..be4728b97759 100644
--- a/Documentation/driver-api/media/maintainer-entry-profile.rst
+++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
@@ -4,19 +4,25 @@ Media Subsystem Profile
 Overview
 --------
 
-The media subsystem covers support for a variety of devices: stream
-capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC
-and media pipeline control.
+The Linux Media Community (aka: the LinuxTV Community) is formed of
+developers working on Linux Kernel Media Subsystem, together with users
+who also play an important role in testing the code.
 
-It covers, mainly, the contents of those directories:
+The Media Subsystem has code to support a wide variety of media-related
+devices: stream capture, analog and digital TV streams, cameras,
+video codecs, video processing (resizers, etc.), radio, remote controllers,
+HDMI CEC and media pipeline control.
+
+The Media Subsystem consists of the following directories in the kernel
+tree:
 
   - drivers/media
   - drivers/staging/media
+  - include/media
+  - Documentation/devicetree/bindings/media/\ [1]_
   - Documentation/admin-guide/media
   - Documentation/driver-api/media
   - Documentation/userspace-api/media
-  - Documentation/devicetree/bindings/media/\ [1]_
-  - include/media
 
 .. [1] Device tree bindings are maintained by the
        OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers
@@ -27,19 +33,271 @@ It covers, mainly, the contents of those directories:
 Both media userspace and Kernel APIs are documented and the documentation
 must be kept in sync with the API changes. It means that all patches that
 add new features to the subsystem must also bring changes to the
-corresponding API files.
+corresponding API documentation.
 
-Due to the size and wide scope of the media subsystem, media's
-maintainership model is to have sub-maintainers that have a broad
-knowledge of a specific aspect of the subsystem. It is the sub-maintainers'
-task to review the patches, providing feedback to users if the patches are
-following the subsystem rules and are properly using the media kernel and
-userspace APIs.
+Media Maintainers
+-----------------
 
-Patches for the media subsystem must be sent to the media mailing list
-at linux-media@vger.kernel.org as plain text only e-mail. Emails with
-HTML will be automatically rejected by the mail server. It could be wise
-to also copy the sub-maintainer(s).
+Due to the size and wide scope of the media subsystem, multiple layers of
+maintainers are required, each with their own areas of expertise:
+
+- Media Driver Maintainer:
+    Responsible for one or more drivers within the Media Subsystem. You
+    are listed in the MAINTAINERS file as maintainer for those drivers. Media
+    Driver Maintainers review patches for those drivers, provide feedback if
+    the patches are not following the subsystem rules, or are not using the
+    media kernel or userspace APIs correctly, or have poor code quality.
+
+    If you are the author of the patches, then you work with other Media
+    Maintainers to ensure your patches are reviewed.
+
+    Some Media Driver Maintainers have additional responsibilities.  They have
+    been granted patchwork access and keep
+    `patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
+    up to date, decide when patches are ready for merging, and create Pull
+    Requests for the Media Subsystem Maintainers to merge.
+
+    Such Media Driver Maintainers are not just someone who is capable of creating code,
+    but someone who has demonstrated their ability to collaborate with the team,
+    get the most knowledgeable people to review code, contribute high-quality code,
+    and follow through to fix issues (in code or tests).
+
+- Media Core Maintainer:
+    Media Driver Maintainers with patchwork access who are also responsible for
+    one or more media core frameworks.
+
+    Core framework changes are done via consensus between the relevant Media
+    Core Maintainers. Media Maintainers may include core framework changes in
+    their Pull Requests if they are signed off by the relevant Media Core
+    Maintainers.
+
+- Media Subsystem Maintainers:
+    Media Core Maintainers who are also responsible for the subsystem as a whole,
+    with access to the entire subsystem. Responsible for merging Pull Requests
+    from other Media Maintainers.
+
+    Userspace API/ABI changes are done via consensus between Media Subsystem
+    Maintainers\ [2]_. Media Maintainers may include API/ABI changes in
+    their Pull Requests if they are signed off by the all Media Subsystem
+    Maintainers.
+
+All Media Maintainers shall explicitly agree with the Kernel development process
+as described at Documentation/process/index.rst and to the Kernel
+development rules inside the Kernel documentation, including its code of
+conduct.
+
+Media Maintainers are reachable via the #linux-media IRC channel at OFTC.
+
+.. [2] Everything that would break backward compatibility with existing
+       non-kernel code are API/ABI changes. This includes ioctl and sysfs
+       interfaces, v4l2 controls, and their behaviors.
+
+Patchwork Access
+----------------
+
+All Media Maintainers who have been granted patchwork access shall ensure that
+`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
+will reflect the current status, e.g. patches shall be delegated to the Media
+Maintainer who is handling them and the patch status shall be updated according
+to these rules:
+
+- ``Under Review``: Used if the patch requires a second opinion
+  or when it is part of a pull request;
+- ``Accepted``: Once a patch is merged in the multi-committer tree.
+- ``Superseded``: There is a newer version of the patch posted to the
+  mailing list.
+- ``Duplicated``: There was another patch doing the same thing from someone
+  else that was accepted.
+- ``Not Applicable``: Use for patch series that are not merged at media.git
+  tree (e.g. drm, dmabuf, upstream merge, etc.) but were cross-posted to the
+  linux-media mailing list.
+
+If a Media Maintainer decides not to accept a patch, then reply by email to
+the patch authors, explaining why it is not accepted, and
+`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_ shall be
+updated accordingly with either:
+
+- ``Changes Requested``: if a new revision was requested;
+- ``Rejected``: if the proposed change is not acceptable at all.
+
+.. Note::
+
+   Patchwork supports a couple of clients to help semi-automating
+   status updates via its REST interface:
+
+   https://patchwork.readthedocs.io/en/latest/usage/clients/
+
+For those patches that fall in your area of responsibility you alse decide
+when those patches are ready for merging, and create Pull Requests for the
+Media Subsystem Maintainers to merge.
+
+The most important aspect of becoming a Media Maintainer with patchwork access
+is that you have demonstrated the ability to give good code reviews. So we are
+looking for whether or not we think you will be good at doing that.
+
+As such, potential maintainers must earn enough credibility and trust from the
+Linux Media Community. To do that, developers shall be familiar with the open
+source model and have been active in the Linux Kernel community for some time,
+and, in particular, in the media subsystem.
+
+In addition to actually making the code changes, you are basically
+demonstrating your:
+
+- commitment to the project;
+- ability to collaborate with the team and communicate well;
+- understand of how upstream and the Linux Media Community work
+  (policies, processes for testing, code review, ...)
+- reasonable knowledge about:
+
+  - the Kernel development process:
+    Documentation/process/index.rst
+
+  - the Media development profile:
+    Documentation/driver-api/media/maintainer-entry-profile.rst
+
+- understanding of the projects' code base and coding style;
+- ability to provide feedback to the patch authors;
+- ability to judge when a patch might be ready for review and to submit;
+- ability to write good code (last but certainly not least).
+
+Media Driver Maintainers that desire to get patchwork access are encouraged
+to participate at the yearly Linux Media Summit, typically co-located with
+a Linux related conference. These summits are announced on the linux-media
+mailing list.
+
+If you are doing such tasks and have become a valued developer, an
+existing Media Maintainer can nominate you to the Media Subsystem Maintainers.
+
+The ultimate responsibility for accepting a nominated maintainer is up to
+the subsystem's maintainers. The nominated maintainer must have earned a trust
+relationship with all Media Subsystem Maintainers, as, by being granted patchwork
+access, you will take over part of their maintenance tasks.
+
+Media development tree
+----------------------
+
+The main development tree used by the media subsystem is hosted at
+https://gitlab.freedesktop.org/linux-media/.
+https://linuxtv.org/ hosts news about the subsystem,
+`wiki <https://www.linuxtv.org/wiki/index.php/Main_Page>`_ pages
+and a `patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
+instance where we track patches though their lifetime.
+
+The main tree used by media developers is at:
+
+https://gitlab.freedesktop.org/linux-media/media-committers.git
+
+Please note that this tree can be rebased, although only as a last resort.
+
+.. _Media development workflow:
+
+Media development workflow
+++++++++++++++++++++++++++
+
+All changes for the media subsystem shall be sent first as e-mails to the
+media mailing list, following the process documented at
+Documentation/process/index.rst.
+
+It means that patches shall be submitted as plain text only via e-mail to
+linux-media@vger.kernel.org (aka: LMML). While subscription is not mandatory,
+you can find details about how to subscribe to it and to see its archives at:
+
+  https://subspace.kernel.org/vger.kernel.org.html
+
+Emails with HTML will be automatically rejected by the mail server.
+
+It could be wise to also copy the Media Maintainer(s). You should use
+``scripts/get_maintainers.pl`` to identify whom else needs to be copied.
+Please always copy driver's authors and maintainers.
+
+To minimize the chance of merge conflicts for your patch series, and make
+easier to backport patches to stable Kernels, we recommend that you use the
+following baseline for your patch series:
+
+1. Features for the next mainline release:
+
+   - baseline shall be the media-committers.git ``next`` branch;
+
+2. Bug fixes for the next mainline release:
+
+   - baseline shall be the media-committers.git ``next`` branch. If the
+     changes depend on a fix from the media-committers.git
+     ``fixes`` branch, then you can use that as baseline.
+
+3. Bug fixes for the current mainline release (-rcX):
+
+   - baseline shall be the latest mainline -rcX release or the
+     media-committers.git ``fixes`` branch if changes depend on a mainline
+     fix that is not yet merged;
+
+.. Note::
+
+   See https://www.kernel.org/category/releases.html for an overview
+   about Kernel release types.
+
+Patches with fixes shall have:
+
+- a ``Fixes:`` tag pointing to the first commit that introduced the bug;
+- when applicable, a ``Cc: stable@vger.kernel.org``.
+
+Patches that were fixing bugs publicly reported by someone at the
+linux-media@vger.kernel.org mailing list shall have:
+
+- a ``Reported-by:`` tag immediately followed by a ``Closes:`` tag.
+
+Patches that change API shall update documentation accordingly at the
+same patch series.
+
+See Documentation/process/index.rst for more details about e-mail submission.
+
+Once a patch is submitted, it may follow either one of the following
+workflows:
+
+a. Media Maintainers' workflow: Media Maintainers post the PRs, which are
+   handled by the Media Subsystem Maintainers::
+
+     +-------+   +------------+   +------+   +-------+   +----------------------------+
+     |e-mail |-->|picked up by|-->|code  |-->|pull   |-->|Subsystem Maintainers merge |
+     |to LMML|   |patchwork   |   |review|   |request|   |in media-committers.git     |
+     +-------+   +------------+   +------+   +-------+   +----------------------------+
+
+   For this workflow, pull requests are generated by Media Maintainers with
+   patchwork access.  If you do not have patchwork access, then please don't
+   submit pull requests, as they will not be processed.
+
+b. Media Committers' workflow: patches are handled by Media Maintainers with
+   commit rights::
+
+     +-------+   +------------+   +------+   +--------------------------+
+     |e-mail |-->|picked up by|-->|code  |-->|Media Committers merge in |
+     |to LMML|   |patchwork   |   |review|   |media-committers.git      |
+     +-------+   +------------+   +------+   +--------------------------+
+
+When patches are picked up by
+`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
+and when merged at media-committers,
+Media CI bots will check for errors and may provide e-mail feedback about
+patch problems. When this happens, the patch submitter must fix them or
+explain why the errors are false positives.
+
+Patches will only be moved to the next stage in these two workflows if they
+pass on Media CI or if there are false-positives in the Media CI reports.
+
+For both workflows, all patches shall be properly reviewed at
+linux-media@vger.kernel.org (LMML) before being merged in media-committers.git.
+Media patches will be reviewed in a timely manner by the maintainers and
+reviewers as listed in the MAINTAINERS file.
+
+Media Maintainers shall request reviews from other Media Maintainers and
+developers where applicable, i.e. because those developers have more
+knowledge about some areas that are changed by a patch.
+
+There shall be no open issues or unresolved or conflicting feedback
+from anyone. Clear them up first. Defer to the Media Subsystem
+Maintainers if needed.
+
+Failures during e-mail submission
++++++++++++++++++++++++++++++++++
 
 Media's workflow is heavily based on Patchwork, meaning that, once a patch
 is submitted, the e-mail will first be accepted by the mailing list
@@ -47,51 +305,53 @@ server, and, after a while, it should appear at:
 
    - https://patchwork.linuxtv.org/project/linux-media/list/
 
-If it doesn't automatically appear there after a few minutes, then
+If it doesn't automatically appear there after some time [3]_, then
 probably something went wrong on your submission. Please check if the
-email is in plain text\ [2]_ only and if your emailer is not mangling
+email is in plain text\ [4]_ only and if your emailer is not mangling
 whitespaces before complaining or submitting them again.
 
-You can check if the mailing list server accepted your patch, by looking at:
+To troubleshoot problems, you should first check if the mailing list
+server has accepted your patch, by looking at:
 
    - https://lore.kernel.org/linux-media/
 
-.. [2] If your email contains HTML, the mailing list server will simply
+If the patch is there and not at
+`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
+it is likely that your e-mailer
+mangled the patch. Patchwork internally has logic that checks if the
+received e-mail contains a valid patch. Any whitespace and new line
+breakages mangling the patch won't be recognized by
+`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
+and such a patch will be rejected.
+
+.. [3] It usually takes a few minutes for the patch to arrive, but
+       the e-mail server may be busy, so it may take up a longer time
+       for a patch to be picked by
+       `patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_.
+
+.. [4] If your email contains HTML, the mailing list server will simply
        drop it, without any further notice.
 
+.. _media-developers-gpg:
 
-Media maintainers
-+++++++++++++++++
+Authentication for pull and merge requests
+++++++++++++++++++++++++++++++++++++++++++
 
-At the media subsystem, we have a group of senior developers that
-are responsible for doing the code reviews at the drivers (also known as
-sub-maintainers), and another senior developer responsible for the
-subsystem as a whole. For core changes, whenever possible, multiple
-media maintainers do the review.
+The authenticity of developers submitting pull requests and merge requests
+shall be validated by using PGP signing at some moment.
+See: :ref:`kernel_org_trust_repository`.
 
-The media maintainers that work on specific areas of the subsystem are:
+With the pull request workflow, pull requests shall use PGP-signed tags.
 
-- Remote Controllers (infrared):
-    Sean Young <sean@mess.org>
+For more details about PGP signing, please read
+Documentation/process/maintainer-pgp-guide.rst.
 
-- HDMI CEC:
-    Hans Verkuil <hverkuil@kernel.org>
+Subsystem Media Maintainers
+---------------------------
 
-- Media controller drivers:
-    Laurent Pinchart <laurent.pinchart@ideasonboard.com>
-
-- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers:
-    Sakari Ailus <sakari.ailus@linux.intel.com>
-
-- V4L2 drivers and core V4L2 frameworks:
-    Hans Verkuil <hverkuil@kernel.org>
-
-The subsystem maintainer is:
-  Mauro Carvalho Chehab <mchehab@kernel.org>
-
-Media maintainers may delegate a patch to other media maintainers as needed.
-On such case, checkpatch's ``delegate`` field indicates who's currently
-responsible for reviewing a patch.
+The subsystem maintainers are:
+  - Mauro Carvalho Chehab <mchehab@kernel.org>
+  - Hans Verkuil <hverkuil@kernel.org>
 
 Submit Checklist Addendum
 -------------------------
@@ -106,18 +366,15 @@ that should be used in order to check if the drivers are properly
 implementing the media APIs:
 
 ====================	=======================================================
-Type			Tool
+Type			Utility
 ====================	=======================================================
-V4L2 drivers\ [3]_	``v4l2-compliance``
+V4L2 drivers\ [5]_	``v4l2-compliance``
 V4L2 virtual drivers	``contrib/test/test-media``
 CEC drivers		``cec-compliance``
 ====================	=======================================================
 
-.. [3] The ``v4l2-compliance`` also covers the media controller usage inside
-       V4L2 drivers.
-
-Other compliance tools are under development to check other parts of the
-subsystem.
+.. [5] The ``v4l2-compliance`` utility also covers the media controller usage
+       inside V4L2 drivers.
 
 Those tests need to pass before the patches go upstream.
 
@@ -134,6 +391,8 @@ Where the check script is::
 Be sure to not introduce new warnings on your patches without a
 very good reason.
 
+Please see `Media development workflow`_ for e-mail submission rules.
+
 Style Cleanup Patches
 +++++++++++++++++++++
 
@@ -183,23 +442,24 @@ In particular, we accept lines with more than 80 columns:
 Key Cycle Dates
 ---------------
 
-New submissions can be sent at any time, but if they intend to hit the
+New submissions can be sent at any time, but if they are intended to hit the
 next merge window they should be sent before -rc5, and ideally stabilized
 in the linux-media branch by -rc6.
 
 Review Cadence
 --------------
 
-Provided that your patch is at https://patchwork.linuxtv.org, it should
-be sooner or later handled, so you don't need to re-submit a patch.
+Provided that your patch has landed in
+`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_, it
+should be sooner or later handled, so you don't need to re-submit a patch.
 
-Except for bug fixes, we don't usually add new patches to the development
-tree between -rc6 and the next -rc1.
+Except for important bug fixes, we don't usually add new patches to the
+development tree between -rc6 and the next -rc1.
 
 Please notice that the media subsystem is a high traffic one, so it
 could take a while for us to be able to review your patches. Feel free
 to ping if you don't get a feedback in a couple of weeks or to ask
-other developers to publicly add Reviewed-by and, more importantly,
+other developers to publicly add ``Reviewed-by:`` and, more importantly,
 ``Tested-by:`` tags.
 
 Please note that we expect a detailed description for ``Tested-by:``,
-- 
2.51.0

[PATCHv7 2/3] docs: media: document Media Maintainers

[Hans Verkuil]

Document who the Media Maintainers are and what their
responsibilities are.

Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>
---
 .../media/maintainer-entry-profile.rst        | 47 +++++++++++++++++--
 1 file changed, 44 insertions(+), 3 deletions(-)

diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
index be4728b97759..4f73ee073860 100644
--- a/Documentation/driver-api/media/maintainer-entry-profile.rst
+++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
@@ -346,13 +346,54 @@ With the pull request workflow, pull requests shall use PGP-signed tags.
 For more details about PGP signing, please read
 Documentation/process/maintainer-pgp-guide.rst.
 
-Subsystem Media Maintainers
----------------------------
+List of Media Maintainers
+-------------------------
 
-The subsystem maintainers are:
+The Media Maintainers listed here all have patchwork access and can
+make Pull Requests or have commit rights.
+
+The Media Subsystem Maintainers are:
   - Mauro Carvalho Chehab <mchehab@kernel.org>
   - Hans Verkuil <hverkuil@kernel.org>
 
+The Media Core Maintainers are:
+  - Sakari Ailus <sakari.ailus@linux.intel.com>
+
+    - ISP
+    - sensor drivers
+    - v4l2-async and v4l2-fwnode core frameworks
+    - v4l2-flash-led-class core framework
+
+  - Mauro Carvalho Chehab <mchehab@kernel.org>
+
+    - DVB
+
+  - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+
+    - Media controller drivers
+    - Core media controller framework
+
+  - Hans Verkuil <hverkuil@kernel.org>
+
+    - V4L2 drivers
+    - V4L2 and videobuf2 core frameworks
+    - HDMI CEC drivers
+    - HDMI CEC core framework
+
+  - Sean Young <sean@mess.org>
+
+    - Remote Controller (infrared) drivers
+    - Remote Controller (infrared) core framework
+
+The Media Driver Maintainers responsible for specific areas are:
+  - Nicolas Dufresne <nicolas.dufresne@collabora.com>
+
+    - Codec drivers
+
+  - Bryan O'Donoghue <bryan.odonoghue@linaro.org>
+
+    - Qualcomm drivers
+
 Submit Checklist Addendum
 -------------------------
 
-- 
2.51.0

[PATCHv7 3/3] docs: media: document media multi-committers rules and process

[Hans Verkuil]

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

As the media subsystem will experiment with a multi-committers model,
update the Maintainer's entry profile to the new rules, and add a file
documenting the process to become a committer and to maintain such
rights.

Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>
---
 Documentation/driver-api/media/index.rst      |   1 +
 .../media/maintainer-entry-profile.rst        |  21 ++
 .../driver-api/media/media-committer.rst      | 197 ++++++++++++++++++
 3 files changed, 219 insertions(+)
 create mode 100644 Documentation/driver-api/media/media-committer.rst

diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst
index d5593182a3f9..d0c725fcbc67 100644
--- a/Documentation/driver-api/media/index.rst
+++ b/Documentation/driver-api/media/index.rst
@@ -26,6 +26,7 @@ Documentation/userspace-api/media/index.rst
     :numbered:
 
     maintainer-entry-profile
+    media-committer
 
     v4l2-core
     dtv-core
diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
index 4f73ee073860..0024f85101b7 100644
--- a/Documentation/driver-api/media/maintainer-entry-profile.rst
+++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
@@ -173,6 +173,17 @@ the subsystem's maintainers. The nominated maintainer must have earned a trust
 relationship with all Media Subsystem Maintainers, as, by being granted patchwork
 access, you will take over part of their maintenance tasks.
 
+Media Committers
+----------------
+
+Experienced and trusted Media Maintainers may be granted commit rights
+which allow them to directly push patches to the media development tree instead
+of posting a Pull Request for the Media Subsystem Maintainers. This helps
+offloading some of the work of the Media Subsystem Maintainers.
+
+More details about Media Committers' roles and responsibilities can be
+found here: :ref:`Media Committers`.
+
 Media development tree
 ----------------------
 
@@ -343,9 +354,19 @@ See: :ref:`kernel_org_trust_repository`.
 
 With the pull request workflow, pull requests shall use PGP-signed tags.
 
+With the committers' workflow, this is ensured at the time merge request
+rights will be granted to the gitlab instance used by the media-committers.git
+tree, after receiving the e-mail documented in
+:ref:`media-committer-agreement`.
+
 For more details about PGP signing, please read
 Documentation/process/maintainer-pgp-guide.rst.
 
+Maintaining media maintainer status
+-----------------------------------
+
+See :ref:`Maintain Media Status`.
+
 List of Media Maintainers
 -------------------------
 
diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
new file mode 100644
index 000000000000..18cce6e06a2b
--- /dev/null
+++ b/Documentation/driver-api/media/media-committer.rst
@@ -0,0 +1,197 @@
+.. _Media Committers:
+
+Media Committers
+================
+
+Who is a Media Committer?
+-------------------------
+
+A Media Committer is a Media Maintainer with patchwork access who has been
+granted commit access to push patches from other developers and their own
+patches to the
+`media-committers <https://gitlab.freedesktop.org/linux-media/media-committers>`_
+tree.
+
+These commit rights are granted with expectation of responsibility:
+committers are people who care about the Linux Kernel as a whole and
+about the Linux media subsystem and want to advance its development. It
+is also based on a trust relationship among other committers, maintainers
+and the Linux Media community.
+
+.. Note::
+
+   1. Patches you authored must have a Signed-off-by, Reviewed-by or Acked-by
+      of another Media Maintainer;
+   2. If a patch introduces a regression, then it is the Media Committer's
+      responsibility to correct that as soon as possible. Typically the
+      patch is either reverted, or an additional patch is committed to
+      fix the regression;
+   3. If patches are fixing bugs against already released Kernels, including
+      the reverts above mentioned, the Media Committer shall add the needed
+      tags. Please see :ref:`Media development workflow` for more details.
+
+Becoming a Media Committer
+--------------------------
+
+Existing Media Committers can nominate a Media Maintainer to be granted
+commit rights. The Media Maintainer must already have patchwork access and
+have been in that role for some time, and has demonstrated a good
+understanding of the maintainer's duties and processes.
+
+The ultimate responsibility for accepting a nominated committer is up to
+the Media Subsystem Maintainers. The nominated committer must have earned a
+trust relationship with all Media Subsystem Maintainers, as, by granting you
+commit rights, part of their responsibilities are handed over to you.
+
+Due to that, to become a Media Committer, a consensus between all Media
+Subsystem Maintainers is required.
+
+.. Note::
+
+   In order to preserve/protect the developers that could have their commit
+   rights granted, denied or removed as well as the subsystem maintainers who
+   have the task to accept or deny commit rights, all communication related to
+   changing commit rights should happen in private as much as possible.
+
+.. _media-committer-agreement:
+
+Media Committer's agreement
+---------------------------
+
+Once a nominated committer is accepted by all Media Subsystem Maintainers,
+they will ask if the developer is interested in the nomination and discuss
+what area(s) of the media subsystem the committer will be responsible for.
+Those areas will typically be the same as the areas that are already
+maintained by the nominated committer.
+
+When the developer accepts being a committer, the new committer shall
+explicitly accept the Kernel development policies described under its
+Documentation/, and in particular to the rules in this document, by writing
+an e-mail to media-committers@linuxtv.org, with a declaration of intent
+following the model below::
+
+   I, John Doe, would like to change my status to: Committer
+
+   As Media Maintainer I accept commit rights for the following areas of
+   the media subsystem:
+
+   ...
+
+   For the purpose of committing patches to the media-committer's tree,
+   I'll be using my user https://gitlab.freedesktop.org/users/<username>.
+
+Followed by a formal declaration of agreement with the Kernel development
+rules::
+
+   I agree to follow the Kernel development rules described at:
+
+   https://www.kernel.org/doc/html/latest/driver-api/media/media-committer.rst
+
+   and to the Linux Kernel development process rules.
+
+   I agree to abide by the Code of Conduct as documented in:
+   https://www.kernel.org/doc/html/latest/process/code-of-conduct.rst
+
+   I am aware that I can, at any point of time, retire. In that case, I will
+   send an e-mail to notify the Media Subsystem Maintainers for them to revoke
+   my commit rights.
+
+   I am aware that the Kernel development rules change over time.
+   By doing a new push to media-committer tree, I understand that I agree
+   to follow the rules in effect at the time of the commit.
+
+That e-mail shall be signed with a PGP key cross signed by other Kernel and
+media developers. As described at :ref:`media-developers-gpg`, the PGP
+signature, together with the gitlab user security are fundamental components
+that ensure the authenticity of the merge requests that will happen at the
+media-committer.git tree.
+
+In case the kernel development process changes, by merging new commits
+to the
+`media-committer tree <https://gitlab.freedesktop.org/linux-media/media-committers>`_,
+the Media Committer implicitly declares their agreement with the latest
+version of the documented process including the contents of this file.
+
+If a Media Committer decides to retire, it is the committer's duty to
+notify the Media Subsystem Maintainers about that decision.
+
+.. note::
+
+   1. Changes to the kernel media development process shall be announced in
+      the media-committers mailinglist with a reasonable review period. All
+      committers are automatically subscribed to that mailinglist;
+   2. Due to the distributed nature of the Kernel development, it is
+      possible that kernel development process changes may end being
+      reviewed/merged at the linux-docs mailing list, specially for the
+      contents under Documentation/process and for trivial typo fixes.
+
+Media Core Committers
+---------------------
+
+As described in Documentation/driver-api/media/maintainer-entry-profile.rst
+a Media Core Maintainer maintains media core frameworks as well, besides
+just drivers, and so is able to change core files and the media subsystem's
+Kernel API. A Media Core Committer is a Media Core Maintainer with commit
+rights. The extent of the core committer's grants will be detailed by the
+Media Subsystem Maintainers when they nominate a Media Core Committer.
+
+Existing Media Committers may become Media Core Committers and vice versa.
+Such decisions will be taken in consensus between the Media Subsystem
+Maintainers.
+
+Media committers rules
+----------------------
+
+Media committers shall do their best efforts to avoid merging patches that
+would break any existing drivers. If it breaks, fixup or revert patches
+shall be merged as soon as possible, aiming to be merged at the same Kernel
+cycle the bug is reported.
+
+Media committers shall behave accordingly to the rights granted by
+the Media Subsystem Maintainers, specially with regards of the scope of changes
+they may apply directly at the media-committers tree. That scope can
+change over time on a mutual agreement between media committers and
+maintainers.
+
+The Media Committer workflow is described at :ref:`Media development workflow`.
+
+.. _Maintain Media Status:
+
+Maintaining media maintainer or committer status
+------------------------------------------------
+
+A community of maintainers working together to move the Linux Kernel
+forward is essential to creating successful projects that are rewarding
+to work on. If there are problems or disagreements within the community,
+they can usually be solved through healthy discussion and debate.
+
+In the unhappy event that a media maintainer or committer continues to
+disregard good citizenship (or actively disrupts the project), we may need
+to revoke that person's status. In such cases, if someone suggests the
+revocation with a good reason, then after discussing this among the media
+maintainers, the final decision is taken by the Media Subsystem Maintainers.
+As the decision to become a media maintainer or committer comes from a
+consensus between Media Subsystem Maintainers, a single subsystem maintainer
+not trusting the media maintainer or committer anymore is enough to revoke
+the maintenance/patchwork or commit rights.
+
+A previous committer that had their commit rights revoked can keep
+contributing to the subsystem via the pull request workflow as documented
+at the :ref:`Media development workflow`, unless they were also removed as
+Media Maintainer.
+
+If a maintainer is inactive for more than a couple of Kernel cycles,
+maintainers will try to reach you via e-mail. If not possible, they may
+revoke your maintainer/patchwork and committer rights and update MAINTAINERS file
+entries accordingly. If you wish to resume contributing later on, then contact
+the Media Subsystem Maintainers to ask if your maintenance/patchwork and
+commit rights can be restored.
+
+References
+----------
+
+Much of this was inspired by/copied from the committer policies of:
+
+- `Chromium <https://chromium.googlesource.com/chromium/src/+/main/docs/contributing.md>`_;
+- `WebKit <https://webkit.org/commit-and-review-policy/>`_;
+- `Mozilla <https://www.mozilla.org/hacking/committer/>`_.
-- 
2.51.0

Re: [PATCHv7 0/3] docs: media: multicommitters model documentation

[Mauro Carvalho Chehab]

Hi Hans,

On Tue, 27 Jan 2026 11:53:24 +0100
Hans Verkuil <hverkuil+cisco@kernel.org> wrote:

> Here is v7, based on yesterday's meeting.
> 
> The main change is what a "Media Maintainer" is. In v6 I considered a
> Media Maintainer to be someone who has patchwork access and has
> responsibility for an area of the media subsystem, deciding when a
> patch is ready to be merged and making PRs.
> 
> That was confusing since that name was too generic.
> 
> In v7 a "Media Driver Maintainer" is anyone who is listed in MAINTAINERS
> for a media driver. "Media Driver/Core/Subsystem Maintainers" are collectively
> called "Media Maintainers".
> 
> I also added the distinction of being granted patchwork access: only Media
> Maintainers with patchwork access can decide when a patch is ready to be
> merged and make PRs. If you are trusted enough to be able to do that, then
> patchwork access is granted since you need that to be able to delegate patches
> and update the patch status.
> 
> I'm still not entirely satisfied with this, as I would prefer to have a
> specific name for such maintainers. Saying "Media Maintainers with patchwork
> access" is a mouthful. I can't think of a good name, though.
> 
> So the hierarchy is as follows:
> 
> - Media Contributor: posts patches
> - Media Driver Maintainer: as above, but also reviews patches and is
>   listed in MAINTAINERS
> - Media Driver Maintainer with patchwork access: decides when patches are
>   ready for mainline, posts PRs, keeps patchwork up to date. Optionally
>   has commit rights.
> - Media Core Maintainer: same as above, but is also responsible for one
>   or more media core frameworks.
> - Media Subsystem Maintainer: as above, but is also responsible for the
>   whole subsystem, processes PRs and has commit rights.
> 
> 
> 
> Patch 1/3 updates maintainer-entry-profile.rst: it introduces the
> three Media maintainer levels (Media Driver Maintainer, Media Core Maintainer
> and Media Subsystem Maintainer) and what the responsibilities are.
> 
> Patch 2/3 adds back and updates the list of Media Maintainers that
> disappeared in patch 1/3. Please verify this whether the email
> addresses are the correct ones, and verify that the areas of responsibility
> are correct and that nothing is missing.
> 
> Patch 3/3 adds media-committer.rst: that focusses on the additional
> commit rights that can be granted to a Media Maintainer.
> 
> It feels much more consistent to me, I'm looking forward to the
> review comments.
> 
> I have uploaded the documentation with these patches here:
> 
> https://hverkuil.home.xs4all.nl/spec/driver-api/maintainer-entry-profile.html
> https://hverkuil.home.xs4all.nl/spec/driver-api/media-committer.html
> 
> Regards,
> 
> 	Hans

This new version is much better than v6. There are a couple of
minor changes to be changes, but afterwards, I guess we're ready
to go. I'll submit such changes as two patches at the end of this
series.


-- 
Thanks,
Mauro

[PATCH 1/2] docs: media: maintainer-entry-profile: do some editorial reviews

[Mauro Carvalho Chehab]

Do some editorial improvements to the Media Subsystem Profile
documentation:

- Some English fixups and cleanups;
- Capitalize patchwork;
- Uncapitalize pull requests, as other occurrences are in lower case;
- Added bold markups to the 3 types of media maintainers;
- ensure that the document uses 80 chars per line;

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../media/maintainer-entry-profile.rst        | 157 +++++++++---------
 1 file changed, 80 insertions(+), 77 deletions(-)

diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
index 0024f85101b7..bb95611f0a84 100644
--- a/Documentation/driver-api/media/maintainer-entry-profile.rst
+++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
@@ -4,7 +4,7 @@ Media Subsystem Profile
 Overview
 --------
 
-The Linux Media Community (aka: the LinuxTV Community) is formed of
+The Linux Media Community (aka: the LinuxTV Community) is formed by
 developers working on Linux Kernel Media Subsystem, together with users
 who also play an important role in testing the code.
 
@@ -27,7 +27,7 @@ tree:
 .. [1] Device tree bindings are maintained by the
        OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers
        (see the MAINTAINERS file). So, changes there must be reviewed
-       by them before being merged via the media subsystem's development
+       by them before being merged into the media subsystem's development
        tree.
 
 Both media userspace and Kernel APIs are documented and the documentation
@@ -38,32 +38,33 @@ corresponding API documentation.
 Media Maintainers
 -----------------
 
+Media Maintainers are not just people capable of writing code, but they
+are developers who have demonstrated their ability to collaborate with
+the team, get the most knowledgeable people to review code, contribute
+high-quality code, and follow through to fix issues (in code or tests).
+
 Due to the size and wide scope of the media subsystem, multiple layers of
 maintainers are required, each with their own areas of expertise:
 
-- Media Driver Maintainer:
-    Responsible for one or more drivers within the Media Subsystem. You
+- **Media Driver Maintainer**:
+    Responsible for one or more drivers within the Media Subsystem. They
     are listed in the MAINTAINERS file as maintainer for those drivers. Media
     Driver Maintainers review patches for those drivers, provide feedback if
-    the patches are not following the subsystem rules, or are not using the
-    media kernel or userspace APIs correctly, or have poor code quality.
+    patches do not follow the subsystem rules, or are not using the
+    media kernel or userspace APIs correctly, or if they have poor code
+    quality.
 
-    If you are the author of the patches, then you work with other Media
+    If you are the patch author, you work with other Media
     Maintainers to ensure your patches are reviewed.
 
-    Some Media Driver Maintainers have additional responsibilities.  They have
-    been granted patchwork access and keep
-    `patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
+    Some Media Driver Maintainers have additional responsibilities. They have
+    been granted Patchwork access and keep
+    `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
     up to date, decide when patches are ready for merging, and create Pull
     Requests for the Media Subsystem Maintainers to merge.
 
-    Such Media Driver Maintainers are not just someone who is capable of creating code,
-    but someone who has demonstrated their ability to collaborate with the team,
-    get the most knowledgeable people to review code, contribute high-quality code,
-    and follow through to fix issues (in code or tests).
-
-- Media Core Maintainer:
-    Media Driver Maintainers with patchwork access who are also responsible for
+- **Media Core Maintainer**:
+    Media Driver Maintainers with Patchwork access who are also responsible for
     one or more media core frameworks.
 
     Core framework changes are done via consensus between the relevant Media
@@ -71,22 +72,21 @@ maintainers are required, each with their own areas of expertise:
     their Pull Requests if they are signed off by the relevant Media Core
     Maintainers.
 
-- Media Subsystem Maintainers:
-    Media Core Maintainers who are also responsible for the subsystem as a whole,
-    with access to the entire subsystem. Responsible for merging Pull Requests
-    from other Media Maintainers.
+- **Media Subsystem Maintainers**:
+    Media Core Maintainers who are also responsible for the subsystem as a
+    whole, with access to the entire subsystem. Responsible for merging Pull
+    Requests from other Media Maintainers.
 
-    Userspace API/ABI changes are done via consensus between Media Subsystem
+    Userspace API/ABI changes are made via consensus among Media Subsystem
     Maintainers\ [2]_. Media Maintainers may include API/ABI changes in
-    their Pull Requests if they are signed off by the all Media Subsystem
+    their pull requests if they are signed off by all Media Subsystem
     Maintainers.
 
-All Media Maintainers shall explicitly agree with the Kernel development process
-as described at Documentation/process/index.rst and to the Kernel
-development rules inside the Kernel documentation, including its code of
-conduct.
+All Media Maintainers shall agree with the Kernel development process as
+described in Documentation/process/index.rst and with the Kernel development
+rules in the Kernel documentation, including its code of conduct.
 
-Media Maintainers are reachable via the #linux-media IRC channel at OFTC.
+Media Maintainers are often reachable via the #linux-media IRC channel at OFTC.
 
 .. [2] Everything that would break backward compatibility with existing
        non-kernel code are API/ABI changes. This includes ioctl and sysfs
@@ -95,8 +95,8 @@ Media Maintainers are reachable via the #linux-media IRC channel at OFTC.
 Patchwork Access
 ----------------
 
-All Media Maintainers who have been granted patchwork access shall ensure that
-`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
+All Media Maintainers who have been granted Patchwork access shall ensure that
+`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
 will reflect the current status, e.g. patches shall be delegated to the Media
 Maintainer who is handling them and the patch status shall be updated according
 to these rules:
@@ -112,28 +112,28 @@ to these rules:
   tree (e.g. drm, dmabuf, upstream merge, etc.) but were cross-posted to the
   linux-media mailing list.
 
-If a Media Maintainer decides not to accept a patch, then reply by email to
-the patch authors, explaining why it is not accepted, and
-`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_ shall be
-updated accordingly with either:
+If Media Maintainers decide not to accept a patch, they should reply to the
+patch authors by e‑mail, explaining why it is not accepted, and
+update `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
+accordingly with one of the following statuses:
 
 - ``Changes Requested``: if a new revision was requested;
 - ``Rejected``: if the proposed change is not acceptable at all.
 
 .. Note::
 
-   Patchwork supports a couple of clients to help semi-automating
+   Patchwork supports a couple of clients to help semi-automate
    status updates via its REST interface:
 
    https://patchwork.readthedocs.io/en/latest/usage/clients/
 
-For those patches that fall in your area of responsibility you alse decide
-when those patches are ready for merging, and create Pull Requests for the
-Media Subsystem Maintainers to merge.
+For patches that fall within their area of responsibility a Media Maintainer
+also decide when those patches are ready for merging, and create Pull Requests
+for the Media Subsystem Maintainers to merge.
 
-The most important aspect of becoming a Media Maintainer with patchwork access
-is that you have demonstrated the ability to give good code reviews. So we are
-looking for whether or not we think you will be good at doing that.
+The most important aspect of becoming a Media Maintainer with Patchwork access
+is that you have demonstrated an ability to give good code reviews. We value
+your ability to deliver thorough, constructive code reviews.
 
 As such, potential maintainers must earn enough credibility and trust from the
 Linux Media Community. To do that, developers shall be familiar with the open
@@ -145,7 +145,7 @@ demonstrating your:
 
 - commitment to the project;
 - ability to collaborate with the team and communicate well;
-- understand of how upstream and the Linux Media Community work
+- understanding of how upstream and the Linux Media Community work
   (policies, processes for testing, code review, ...)
 - reasonable knowledge about:
 
@@ -160,9 +160,9 @@ demonstrating your:
 - ability to judge when a patch might be ready for review and to submit;
 - ability to write good code (last but certainly not least).
 
-Media Driver Maintainers that desire to get patchwork access are encouraged
+Media Driver Maintainers that desire to get Patchwork access are encouraged
 to participate at the yearly Linux Media Summit, typically co-located with
-a Linux related conference. These summits are announced on the linux-media
+a Linux-related conference. These summits are announced on the linux-media
 mailing list.
 
 If you are doing such tasks and have become a valued developer, an
@@ -170,8 +170,8 @@ existing Media Maintainer can nominate you to the Media Subsystem Maintainers.
 
 The ultimate responsibility for accepting a nominated maintainer is up to
 the subsystem's maintainers. The nominated maintainer must have earned a trust
-relationship with all Media Subsystem Maintainers, as, by being granted patchwork
-access, you will take over part of their maintenance tasks.
+relationship with all Media Subsystem Maintainers, as, by being granted
+Patchwork access, you will take over part of their maintenance tasks.
 
 Media Committers
 ----------------
@@ -191,14 +191,18 @@ The main development tree used by the media subsystem is hosted at
 https://gitlab.freedesktop.org/linux-media/.
 https://linuxtv.org/ hosts news about the subsystem,
 `wiki <https://www.linuxtv.org/wiki/index.php/Main_Page>`_ pages
-and a `patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
+and a `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
 instance where we track patches though their lifetime.
 
-The main tree used by media developers is at:
+The stable tree used by media developers is at:
+
+https://git.linuxtv.org/media.git/
+
+Patches there are initially committed to the media committers tree:
 
 https://gitlab.freedesktop.org/linux-media/media-committers.git
 
-Please note that this tree can be rebased, although only as a last resort.
+Please note that the later can be rebased, although only as a last resort.
 
 .. _Media development workflow:
 
@@ -217,11 +221,11 @@ you can find details about how to subscribe to it and to see its archives at:
 
 Emails with HTML will be automatically rejected by the mail server.
 
-It could be wise to also copy the Media Maintainer(s). You should use
+It could be wise to also copy the relevant Media Maintainer(s). You should use
 ``scripts/get_maintainers.pl`` to identify whom else needs to be copied.
 Please always copy driver's authors and maintainers.
 
-To minimize the chance of merge conflicts for your patch series, and make
+To minimize the chance of merge conflicts for your patch series, and make it
 easier to backport patches to stable Kernels, we recommend that you use the
 following baseline for your patch series:
 
@@ -267,13 +271,14 @@ workflows:
 a. Media Maintainers' workflow: Media Maintainers post the PRs, which are
    handled by the Media Subsystem Maintainers::
 
-     +-------+   +------------+   +------+   +-------+   +----------------------------+
-     |e-mail |-->|picked up by|-->|code  |-->|pull   |-->|Subsystem Maintainers merge |
-     |to LMML|   |patchwork   |   |review|   |request|   |in media-committers.git     |
-     +-------+   +------------+   +------+   +-------+   +----------------------------+
+     +-------+   +------------+   +------+   +-------+   +---------------------+
+     |e-mail |-->|picked up by|-->|code  |-->|pull   |-->|Subsystem Maintainers|
+     |to LMML|   |Patchwork   |   |review|   |request|   |merge in             |
+     |       |   |            |   |      |   |       |   |media-committers.git |
+     +-------+   +------------+   +------+   +-------+   +---------------------+
 
    For this workflow, pull requests are generated by Media Maintainers with
-   patchwork access.  If you do not have patchwork access, then please don't
+   Patchwork access.  If you do not have Patchwork access, then please don't
    submit pull requests, as they will not be processed.
 
 b. Media Committers' workflow: patches are handled by Media Maintainers with
@@ -281,15 +286,14 @@ b. Media Committers' workflow: patches are handled by Media Maintainers with
 
      +-------+   +------------+   +------+   +--------------------------+
      |e-mail |-->|picked up by|-->|code  |-->|Media Committers merge in |
-     |to LMML|   |patchwork   |   |review|   |media-committers.git      |
+     |to LMML|   |Patchwork   |   |review|   |media-committers.git      |
      +-------+   +------------+   +------+   +--------------------------+
 
 When patches are picked up by
-`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
-and when merged at media-committers,
-Media CI bots will check for errors and may provide e-mail feedback about
-patch problems. When this happens, the patch submitter must fix them or
-explain why the errors are false positives.
+`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
+and when merged at media-committers, Media CI bots will check for errors and
+may provide e-mail feedback about patch problems. When this happens, the patch
+submitter must fix them or explain why the errors are false positives.
 
 Patches will only be moved to the next stage in these two workflows if they
 pass on Media CI or if there are false-positives in the Media CI reports.
@@ -327,18 +331,17 @@ server has accepted your patch, by looking at:
    - https://lore.kernel.org/linux-media/
 
 If the patch is there and not at
-`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
-it is likely that your e-mailer
-mangled the patch. Patchwork internally has logic that checks if the
-received e-mail contains a valid patch. Any whitespace and new line
-breakages mangling the patch won't be recognized by
-`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
+`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
+it is likely that your e-mailer mangled the patch. Patchwork internally
+has logic that checks if the received e-mail contains a valid patch.
+Any whitespace and new line breakages mangling the patch won't be recognized by
+`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
 and such a patch will be rejected.
 
 .. [3] It usually takes a few minutes for the patch to arrive, but
-       the e-mail server may be busy, so it may take up a longer time
+       the e-mail server may be busy, so it may take a longer time
        for a patch to be picked by
-       `patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_.
+       `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_.
 
 .. [4] If your email contains HTML, the mailing list server will simply
        drop it, without any further notice.
@@ -349,8 +352,8 @@ Authentication for pull and merge requests
 ++++++++++++++++++++++++++++++++++++++++++
 
 The authenticity of developers submitting pull requests and merge requests
-shall be validated by using PGP signing at some moment.
-See: :ref:`kernel_org_trust_repository`.
+shall be validated by using the Linux Kernel Web of Trust, with PGP signing
+at some moment. See: :ref:`kernel_org_trust_repository`.
 
 With the pull request workflow, pull requests shall use PGP-signed tags.
 
@@ -494,11 +497,11 @@ least, simply wrapping the lines.
 In particular, we accept lines with more than 80 columns:
 
     - on strings, as they shouldn't be broken due to line length limits;
-    - when a function or variable name need to have a big identifier name,
-      which keeps hard to honor the 80 columns limit;
+    - when a function or variable name needs to have a large identifier name,
+      which makes hard to honor the 80 columns limit;
     - on arithmetic expressions, when breaking lines makes them harder to
       read;
-    - when they avoid a line to end with an open parenthesis or an open
+    - when they avoid a line ending with an open parenthesis or an open
       bracket.
 
 Key Cycle Dates
@@ -512,7 +515,7 @@ Review Cadence
 --------------
 
 Provided that your patch has landed in
-`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_, it
+`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_, it
 should be sooner or later handled, so you don't need to re-submit a patch.
 
 Except for important bug fixes, we don't usually add new patches to the
@@ -525,4 +528,4 @@ other developers to publicly add ``Reviewed-by:`` and, more importantly,
 ``Tested-by:`` tags.
 
 Please note that we expect a detailed description for ``Tested-by:``,
-identifying what boards were used at the test and what it was tested.
+identifying what boards were used during the test and what it was tested.
-- 
2.52.0

[PATCH 2/2] docs: media: media-committer: do some editorial changes

[Mauro Carvalho Chehab]

Do some editorial changes to make it look clearer:

  - media-committers tree references corrected from singular to plural;
  - updated commit rights wording and responsibilities;
  - fixed various typographical errors;
  - corrected “mailing list” and “Kernel” references;
  - improved core committer description;
  - updated documentation paths and URLs;
  - added missing “for” and improved sentence flow.

Perhaps the most relevant change is that i removed a word
that was requiring granting Patchwork rights some time before
adding commit rights (we may grant them altogether if makes
sense for us), and I added a 4th note to committer notes
list to let it clear that about what it is expected from a
committer with regards to updating Patchwork.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../driver-api/media/media-committer.rst      | 97 ++++++++++---------
 1 file changed, 51 insertions(+), 46 deletions(-)

diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
index 18cce6e06a2b..c83e94750e57 100644
--- a/Documentation/driver-api/media/media-committer.rst
+++ b/Documentation/driver-api/media/media-committer.rst
@@ -20,8 +20,8 @@ and the Linux Media community.
 
 .. Note::
 
-   1. Patches you authored must have a Signed-off-by, Reviewed-by or Acked-by
-      of another Media Maintainer;
+   1. Patches you authored must have a ``Signed-off-by``, ``Reviewed-by``
+      or ``Acked-by`` from another Media Maintainer;
    2. If a patch introduces a regression, then it is the Media Committer's
       responsibility to correct that as soon as possible. Typically the
       patch is either reverted, or an additional patch is committed to
@@ -29,14 +29,18 @@ and the Linux Media community.
    3. If patches are fixing bugs against already released Kernels, including
       the reverts above mentioned, the Media Committer shall add the needed
       tags. Please see :ref:`Media development workflow` for more details.
+   4. All Media Committers are responsible for maintaining
+      `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
+      updating the state of the patches they review or merge.
+
 
 Becoming a Media Committer
 --------------------------
 
 Existing Media Committers can nominate a Media Maintainer to be granted
-commit rights. The Media Maintainer must already have patchwork access and
-have been in that role for some time, and has demonstrated a good
-understanding of the maintainer's duties and processes.
+commit rights. The Media Maintainer must have patchwork access,
+have been reviewing patches from third parties for some time, and has
+demonstrated a good understanding of the maintainer's duties and processes.
 
 The ultimate responsibility for accepting a nominated committer is up to
 the Media Subsystem Maintainers. The nominated committer must have earned a
@@ -61,8 +65,8 @@ Media Committer's agreement
 Once a nominated committer is accepted by all Media Subsystem Maintainers,
 they will ask if the developer is interested in the nomination and discuss
 what area(s) of the media subsystem the committer will be responsible for.
-Those areas will typically be the same as the areas that are already
-maintained by the nominated committer.
+Those areas will typically be the same as the areas that the nominated
+committer is already maintaining.
 
 When the developer accepts being a committer, the new committer shall
 explicitly accept the Kernel development policies described under its
@@ -77,7 +81,7 @@ following the model below::
 
    ...
 
-   For the purpose of committing patches to the media-committer's tree,
+   For the purpose of committing patches to the media-committers tree,
    I'll be using my user https://gitlab.freedesktop.org/users/<username>.
 
 Followed by a formal declaration of agreement with the Kernel development
@@ -85,7 +89,7 @@ rules::
 
    I agree to follow the Kernel development rules described at:
 
-   https://www.kernel.org/doc/html/latest/driver-api/media/media-committer.rst
+   https://www.kernel.org/doc/html/latest/driver-api/media/media-committers.rst
 
    and to the Linux Kernel development process rules.
 
@@ -97,18 +101,17 @@ rules::
    my commit rights.
 
    I am aware that the Kernel development rules change over time.
-   By doing a new push to media-committer tree, I understand that I agree
+   By doing a new push to media-committers tree, I understand that I agree
    to follow the rules in effect at the time of the commit.
 
-That e-mail shall be signed with a PGP key cross signed by other Kernel and
-media developers. As described at :ref:`media-developers-gpg`, the PGP
-signature, together with the gitlab user security are fundamental components
-that ensure the authenticity of the merge requests that will happen at the
-media-committer.git tree.
+That e-mail shall be signed via the Kernel Web of trust with a PGP key cross
+signed by other Kernel and media developers. As described at
+:ref:`media-developers-gpg`, the PGP signature, together with the gitlab user
+security are fundamental components that ensure the authenticity of the merge
+requests that will happen at the media-committers.git tree.
 
-In case the kernel development process changes, by merging new commits
-to the
-`media-committer tree <https://gitlab.freedesktop.org/linux-media/media-committers>`_,
+In case the kernel development process changes, by merging new commits to the
+`media-committers tree <https://gitlab.freedesktop.org/linux-media/media-committers>`_,
 the Media Committer implicitly declares their agreement with the latest
 version of the documented process including the contents of this file.
 
@@ -118,25 +121,27 @@ notify the Media Subsystem Maintainers about that decision.
 .. note::
 
    1. Changes to the kernel media development process shall be announced in
-      the media-committers mailinglist with a reasonable review period. All
-      committers are automatically subscribed to that mailinglist;
+      the media-committers mailing list with a reasonable review period. All
+      committers are automatically subscribed to that mailing list;
    2. Due to the distributed nature of the Kernel development, it is
       possible that kernel development process changes may end being
-      reviewed/merged at the linux-docs mailing list, specially for the
-      contents under Documentation/process and for trivial typo fixes.
+      reviewed/merged at the Linux Docs and/or at the Linux Kernel mailing
+      lists, especially for the contents under Documentation/process and for
+      trivial typo fixes.
 
 Media Core Committers
 ---------------------
 
-As described in Documentation/driver-api/media/maintainer-entry-profile.rst
+A Media Core Committer is a Media Core Maintainer with commit rights.
+
+As described in Documentation/driver-api/media/maintainer-entry-profile.rst,
 a Media Core Maintainer maintains media core frameworks as well, besides
-just drivers, and so is able to change core files and the media subsystem's
-Kernel API. A Media Core Committer is a Media Core Maintainer with commit
-rights. The extent of the core committer's grants will be detailed by the
+just drivers, and so is allowed to change core files and the media subsystem's
+Kernel API. The extent of the core committer's grants will be detailed by the
 Media Subsystem Maintainers when they nominate a Media Core Committer.
 
 Existing Media Committers may become Media Core Committers and vice versa.
-Such decisions will be taken in consensus between the Media Subsystem
+Such decisions will be taken in consensus among the Media Subsystem
 Maintainers.
 
 Media committers rules
@@ -148,16 +153,16 @@ shall be merged as soon as possible, aiming to be merged at the same Kernel
 cycle the bug is reported.
 
 Media committers shall behave accordingly to the rights granted by
-the Media Subsystem Maintainers, specially with regards of the scope of changes
+the Media Subsystem Maintainers, especially with regards of the scope of changes
 they may apply directly at the media-committers tree. That scope can
-change over time on a mutual agreement between media committers and
-maintainers.
+change over time on a mutual agreement between Media Committers and
+Media Subsystem Maintainers.
 
 The Media Committer workflow is described at :ref:`Media development workflow`.
 
 .. _Maintain Media Status:
 
-Maintaining media maintainer or committer status
+Maintaining Media Maintainer or Committer status
 ------------------------------------------------
 
 A community of maintainers working together to move the Linux Kernel
@@ -165,27 +170,27 @@ forward is essential to creating successful projects that are rewarding
 to work on. If there are problems or disagreements within the community,
 they can usually be solved through healthy discussion and debate.
 
-In the unhappy event that a media maintainer or committer continues to
+In the unhappy event that a Media Maintainer or Committer continues to
 disregard good citizenship (or actively disrupts the project), we may need
 to revoke that person's status. In such cases, if someone suggests the
-revocation with a good reason, then after discussing this among the media
-maintainers, the final decision is taken by the Media Subsystem Maintainers.
-As the decision to become a media maintainer or committer comes from a
-consensus between Media Subsystem Maintainers, a single subsystem maintainer
-not trusting the media maintainer or committer anymore is enough to revoke
-the maintenance/patchwork or commit rights.
+revocation with a good reason, then after discussing this among the Media
+Maintainers, the final decision is taken by the Media Subsystem Maintainers.
 
-A previous committer that had their commit rights revoked can keep
-contributing to the subsystem via the pull request workflow as documented
-at the :ref:`Media development workflow`, unless they were also removed as
-Media Maintainer.
+As the decision to become a Media Maintainer or Committer comes from a
+consensus between Media Subsystem Maintainers, a single Media Subsystem
+Maintainer not trusting the Media Maintainer or Committer anymore is enough
+to revoke their maintenance, Patchwork grants and/or commit rights.
+
+Having commit rights revoked doesn't prevent Media Maintainers to keep
+contributing to the subsystem either via the pull request or via email workflow
+as documented at the :ref:`Media development workflow`.
 
 If a maintainer is inactive for more than a couple of Kernel cycles,
 maintainers will try to reach you via e-mail. If not possible, they may
-revoke your maintainer/patchwork and committer rights and update MAINTAINERS file
-entries accordingly. If you wish to resume contributing later on, then contact
-the Media Subsystem Maintainers to ask if your maintenance/patchwork and
-commit rights can be restored.
+revoke their maintainer/patchwork and committer rights and update MAINTAINERS
+file entries accordingly. If you wish to resume contributing as maintainer
+later on, then contact the Media Subsystem Maintainers to ask if your
+maintenance, Patchwork grants and commit rights can be restored.
 
 References
 ----------
-- 
2.52.0

Re: [PATCH 2/2] docs: media: media-committer: do some editorial changes

[Mauro Carvalho Chehab]

On Wed,  4 Feb 2026 15:37:45 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> Do some editorial changes to make it look clearer:
...
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  .../driver-api/media/media-committer.rst      | 97 ++++++++++---------
>  1 file changed, 51 insertions(+), 46 deletions(-)
...
> @@ -85,7 +89,7 @@ rules::
>  
>     I agree to follow the Kernel development rules described at:
>  
> -   https://www.kernel.org/doc/html/latest/driver-api/media/media-committer.rst
> +   https://www.kernel.org/doc/html/latest/driver-api/media/media-committers.rst
>  
>     and to the Linux Kernel development process rules.

Heh, this change is obviously wrong, except if we rename the rst document
to also be media-committers.rst, which sounds a good idea to me:

- Use "media-committers" for both the .rst file and for the git tree.

So, please rename the file on v8 (or otherwise fix it here)

-- 
Thanks,
Mauro

Re: [PATCH 1/2] docs: media: maintainer-entry-profile: do some editorial reviews

[Hans Verkuil]

Hi Mauro,

Looks good. Just three minor issues (two typos, and one suggestion for a better word).

If there are no objections, then I will just make those changes and fold it into this
patch for v8.

Regards,

	Hans

On 2/4/26 15:37, Mauro Carvalho Chehab wrote:
> Do some editorial improvements to the Media Subsystem Profile
> documentation:
> 
> - Some English fixups and cleanups;
> - Capitalize patchwork;
> - Uncapitalize pull requests, as other occurrences are in lower case;
> - Added bold markups to the 3 types of media maintainers;
> - ensure that the document uses 80 chars per line;
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  .../media/maintainer-entry-profile.rst        | 157 +++++++++---------
>  1 file changed, 80 insertions(+), 77 deletions(-)
> 
> diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> index 0024f85101b7..bb95611f0a84 100644
> --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> @@ -4,7 +4,7 @@ Media Subsystem Profile
>  Overview
>  --------
>  
> -The Linux Media Community (aka: the LinuxTV Community) is formed of
> +The Linux Media Community (aka: the LinuxTV Community) is formed by
>  developers working on Linux Kernel Media Subsystem, together with users
>  who also play an important role in testing the code.
>  
> @@ -27,7 +27,7 @@ tree:
>  .. [1] Device tree bindings are maintained by the
>         OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers
>         (see the MAINTAINERS file). So, changes there must be reviewed
> -       by them before being merged via the media subsystem's development
> +       by them before being merged into the media subsystem's development
>         tree.
>  
>  Both media userspace and Kernel APIs are documented and the documentation
> @@ -38,32 +38,33 @@ corresponding API documentation.
>  Media Maintainers
>  -----------------
>  
> +Media Maintainers are not just people capable of writing code, but they
> +are developers who have demonstrated their ability to collaborate with
> +the team, get the most knowledgeable people to review code, contribute
> +high-quality code, and follow through to fix issues (in code or tests).
> +
>  Due to the size and wide scope of the media subsystem, multiple layers of
>  maintainers are required, each with their own areas of expertise:
>  
> -- Media Driver Maintainer:
> -    Responsible for one or more drivers within the Media Subsystem. You
> +- **Media Driver Maintainer**:
> +    Responsible for one or more drivers within the Media Subsystem. They
>      are listed in the MAINTAINERS file as maintainer for those drivers. Media
>      Driver Maintainers review patches for those drivers, provide feedback if
> -    the patches are not following the subsystem rules, or are not using the
> -    media kernel or userspace APIs correctly, or have poor code quality.
> +    patches do not follow the subsystem rules, or are not using the
> +    media kernel or userspace APIs correctly, or if they have poor code
> +    quality.
>  
> -    If you are the author of the patches, then you work with other Media
> +    If you are the patch author, you work with other Media
>      Maintainers to ensure your patches are reviewed.
>  
> -    Some Media Driver Maintainers have additional responsibilities.  They have
> -    been granted patchwork access and keep
> -    `patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> +    Some Media Driver Maintainers have additional responsibilities. They have
> +    been granted Patchwork access and keep
> +    `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
>      up to date, decide when patches are ready for merging, and create Pull
>      Requests for the Media Subsystem Maintainers to merge.
>  
> -    Such Media Driver Maintainers are not just someone who is capable of creating code,
> -    but someone who has demonstrated their ability to collaborate with the team,
> -    get the most knowledgeable people to review code, contribute high-quality code,
> -    and follow through to fix issues (in code or tests).
> -
> -- Media Core Maintainer:
> -    Media Driver Maintainers with patchwork access who are also responsible for
> +- **Media Core Maintainer**:
> +    Media Driver Maintainers with Patchwork access who are also responsible for
>      one or more media core frameworks.
>  
>      Core framework changes are done via consensus between the relevant Media
> @@ -71,22 +72,21 @@ maintainers are required, each with their own areas of expertise:
>      their Pull Requests if they are signed off by the relevant Media Core
>      Maintainers.
>  
> -- Media Subsystem Maintainers:
> -    Media Core Maintainers who are also responsible for the subsystem as a whole,
> -    with access to the entire subsystem. Responsible for merging Pull Requests
> -    from other Media Maintainers.
> +- **Media Subsystem Maintainers**:
> +    Media Core Maintainers who are also responsible for the subsystem as a
> +    whole, with access to the entire subsystem. Responsible for merging Pull
> +    Requests from other Media Maintainers.
>  
> -    Userspace API/ABI changes are done via consensus between Media Subsystem
> +    Userspace API/ABI changes are made via consensus among Media Subsystem
>      Maintainers\ [2]_. Media Maintainers may include API/ABI changes in
> -    their Pull Requests if they are signed off by the all Media Subsystem
> +    their pull requests if they are signed off by all Media Subsystem
>      Maintainers.
>  
> -All Media Maintainers shall explicitly agree with the Kernel development process
> -as described at Documentation/process/index.rst and to the Kernel
> -development rules inside the Kernel documentation, including its code of
> -conduct.
> +All Media Maintainers shall agree with the Kernel development process as
> +described in Documentation/process/index.rst and with the Kernel development
> +rules in the Kernel documentation, including its code of conduct.
>  
> -Media Maintainers are reachable via the #linux-media IRC channel at OFTC.
> +Media Maintainers are often reachable via the #linux-media IRC channel at OFTC.
>  
>  .. [2] Everything that would break backward compatibility with existing
>         non-kernel code are API/ABI changes. This includes ioctl and sysfs
> @@ -95,8 +95,8 @@ Media Maintainers are reachable via the #linux-media IRC channel at OFTC.
>  Patchwork Access
>  ----------------
>  
> -All Media Maintainers who have been granted patchwork access shall ensure that
> -`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> +All Media Maintainers who have been granted Patchwork access shall ensure that
> +`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
>  will reflect the current status, e.g. patches shall be delegated to the Media
>  Maintainer who is handling them and the patch status shall be updated according
>  to these rules:
> @@ -112,28 +112,28 @@ to these rules:
>    tree (e.g. drm, dmabuf, upstream merge, etc.) but were cross-posted to the
>    linux-media mailing list.
>  
> -If a Media Maintainer decides not to accept a patch, then reply by email to
> -the patch authors, explaining why it is not accepted, and
> -`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_ shall be
> -updated accordingly with either:
> +If Media Maintainers decide not to accept a patch, they should reply to the
> +patch authors by e‑mail, explaining why it is not accepted, and
> +update `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> +accordingly with one of the following statuses:
>  
>  - ``Changes Requested``: if a new revision was requested;
>  - ``Rejected``: if the proposed change is not acceptable at all.
>  
>  .. Note::
>  
> -   Patchwork supports a couple of clients to help semi-automating
> +   Patchwork supports a couple of clients to help semi-automate
>     status updates via its REST interface:
>  
>     https://patchwork.readthedocs.io/en/latest/usage/clients/
>  
> -For those patches that fall in your area of responsibility you alse decide
> -when those patches are ready for merging, and create Pull Requests for the
> -Media Subsystem Maintainers to merge.
> +For patches that fall within their area of responsibility a Media Maintainer
> +also decide when those patches are ready for merging, and create Pull Requests

decide -> decides

> +for the Media Subsystem Maintainers to merge.
>  
> -The most important aspect of becoming a Media Maintainer with patchwork access
> -is that you have demonstrated the ability to give good code reviews. So we are
> -looking for whether or not we think you will be good at doing that.
> +The most important aspect of becoming a Media Maintainer with Patchwork access
> +is that you have demonstrated an ability to give good code reviews. We value
> +your ability to deliver thorough, constructive code reviews.
>  
>  As such, potential maintainers must earn enough credibility and trust from the
>  Linux Media Community. To do that, developers shall be familiar with the open
> @@ -145,7 +145,7 @@ demonstrating your:
>  
>  - commitment to the project;
>  - ability to collaborate with the team and communicate well;
> -- understand of how upstream and the Linux Media Community work
> +- understanding of how upstream and the Linux Media Community work
>    (policies, processes for testing, code review, ...)
>  - reasonable knowledge about:
>  
> @@ -160,9 +160,9 @@ demonstrating your:
>  - ability to judge when a patch might be ready for review and to submit;
>  - ability to write good code (last but certainly not least).
>  
> -Media Driver Maintainers that desire to get patchwork access are encouraged
> +Media Driver Maintainers that desire to get Patchwork access are encouraged
>  to participate at the yearly Linux Media Summit, typically co-located with
> -a Linux related conference. These summits are announced on the linux-media
> +a Linux-related conference. These summits are announced on the linux-media
>  mailing list.
>  
>  If you are doing such tasks and have become a valued developer, an
> @@ -170,8 +170,8 @@ existing Media Maintainer can nominate you to the Media Subsystem Maintainers.
>  
>  The ultimate responsibility for accepting a nominated maintainer is up to
>  the subsystem's maintainers. The nominated maintainer must have earned a trust
> -relationship with all Media Subsystem Maintainers, as, by being granted patchwork
> -access, you will take over part of their maintenance tasks.
> +relationship with all Media Subsystem Maintainers, as, by being granted
> +Patchwork access, you will take over part of their maintenance tasks.
>  
>  Media Committers
>  ----------------
> @@ -191,14 +191,18 @@ The main development tree used by the media subsystem is hosted at
>  https://gitlab.freedesktop.org/linux-media/.
>  https://linuxtv.org/ hosts news about the subsystem,
>  `wiki <https://www.linuxtv.org/wiki/index.php/Main_Page>`_ pages
> -and a `patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> +and a `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
>  instance where we track patches though their lifetime.
>  
> -The main tree used by media developers is at:
> +The stable tree used by media developers is at:
> +
> +https://git.linuxtv.org/media.git/
> +
> +Patches there are initially committed to the media committers tree:
>  
>  https://gitlab.freedesktop.org/linux-media/media-committers.git
>  
> -Please note that this tree can be rebased, although only as a last resort.
> +Please note that the later can be rebased, although only as a last resort.

later -> latter

>  
>  .. _Media development workflow:
>  
> @@ -217,11 +221,11 @@ you can find details about how to subscribe to it and to see its archives at:
>  
>  Emails with HTML will be automatically rejected by the mail server.
>  
> -It could be wise to also copy the Media Maintainer(s). You should use
> +It could be wise to also copy the relevant Media Maintainer(s). You should use
>  ``scripts/get_maintainers.pl`` to identify whom else needs to be copied.
>  Please always copy driver's authors and maintainers.
>  
> -To minimize the chance of merge conflicts for your patch series, and make
> +To minimize the chance of merge conflicts for your patch series, and make it
>  easier to backport patches to stable Kernels, we recommend that you use the
>  following baseline for your patch series:
>  
> @@ -267,13 +271,14 @@ workflows:
>  a. Media Maintainers' workflow: Media Maintainers post the PRs, which are
>     handled by the Media Subsystem Maintainers::
>  
> -     +-------+   +------------+   +------+   +-------+   +----------------------------+
> -     |e-mail |-->|picked up by|-->|code  |-->|pull   |-->|Subsystem Maintainers merge |
> -     |to LMML|   |patchwork   |   |review|   |request|   |in media-committers.git     |
> -     +-------+   +------------+   +------+   +-------+   +----------------------------+
> +     +-------+   +------------+   +------+   +-------+   +---------------------+
> +     |e-mail |-->|picked up by|-->|code  |-->|pull   |-->|Subsystem Maintainers|
> +     |to LMML|   |Patchwork   |   |review|   |request|   |merge in             |
> +     |       |   |            |   |      |   |       |   |media-committers.git |
> +     +-------+   +------------+   +------+   +-------+   +---------------------+
>  
>     For this workflow, pull requests are generated by Media Maintainers with
> -   patchwork access.  If you do not have patchwork access, then please don't
> +   Patchwork access.  If you do not have Patchwork access, then please don't
>     submit pull requests, as they will not be processed.
>  
>  b. Media Committers' workflow: patches are handled by Media Maintainers with
> @@ -281,15 +286,14 @@ b. Media Committers' workflow: patches are handled by Media Maintainers with
>  
>       +-------+   +------------+   +------+   +--------------------------+
>       |e-mail |-->|picked up by|-->|code  |-->|Media Committers merge in |
> -     |to LMML|   |patchwork   |   |review|   |media-committers.git      |
> +     |to LMML|   |Patchwork   |   |review|   |media-committers.git      |
>       +-------+   +------------+   +------+   +--------------------------+
>  
>  When patches are picked up by
> -`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> -and when merged at media-committers,
> -Media CI bots will check for errors and may provide e-mail feedback about
> -patch problems. When this happens, the patch submitter must fix them or
> -explain why the errors are false positives.
> +`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> +and when merged at media-committers, Media CI bots will check for errors and
> +may provide e-mail feedback about patch problems. When this happens, the patch
> +submitter must fix them or explain why the errors are false positives.
>  
>  Patches will only be moved to the next stage in these two workflows if they
>  pass on Media CI or if there are false-positives in the Media CI reports.
> @@ -327,18 +331,17 @@ server has accepted your patch, by looking at:
>     - https://lore.kernel.org/linux-media/
>  
>  If the patch is there and not at
> -`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
> -it is likely that your e-mailer
> -mangled the patch. Patchwork internally has logic that checks if the
> -received e-mail contains a valid patch. Any whitespace and new line
> -breakages mangling the patch won't be recognized by
> -`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
> +`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
> +it is likely that your e-mailer mangled the patch. Patchwork internally
> +has logic that checks if the received e-mail contains a valid patch.
> +Any whitespace and new line breakages mangling the patch won't be recognized by
> +`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
>  and such a patch will be rejected.
>  
>  .. [3] It usually takes a few minutes for the patch to arrive, but
> -       the e-mail server may be busy, so it may take up a longer time
> +       the e-mail server may be busy, so it may take a longer time
>         for a patch to be picked by
> -       `patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_.
> +       `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_.
>  
>  .. [4] If your email contains HTML, the mailing list server will simply
>         drop it, without any further notice.
> @@ -349,8 +352,8 @@ Authentication for pull and merge requests
>  ++++++++++++++++++++++++++++++++++++++++++
>  
>  The authenticity of developers submitting pull requests and merge requests
> -shall be validated by using PGP signing at some moment.
> -See: :ref:`kernel_org_trust_repository`.
> +shall be validated by using the Linux Kernel Web of Trust, with PGP signing
> +at some moment. See: :ref:`kernel_org_trust_repository`.
>  
>  With the pull request workflow, pull requests shall use PGP-signed tags.
>  
> @@ -494,11 +497,11 @@ least, simply wrapping the lines.
>  In particular, we accept lines with more than 80 columns:
>  
>      - on strings, as they shouldn't be broken due to line length limits;
> -    - when a function or variable name need to have a big identifier name,
> -      which keeps hard to honor the 80 columns limit;
> +    - when a function or variable name needs to have a large identifier name,

large -> long ('long' makes much more sense in this context)

> +      which makes hard to honor the 80 columns limit;
>      - on arithmetic expressions, when breaking lines makes them harder to
>        read;
> -    - when they avoid a line to end with an open parenthesis or an open
> +    - when they avoid a line ending with an open parenthesis or an open
>        bracket.
>  
>  Key Cycle Dates
> @@ -512,7 +515,7 @@ Review Cadence
>  --------------
>  
>  Provided that your patch has landed in
> -`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_, it
> +`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_, it
>  should be sooner or later handled, so you don't need to re-submit a patch.
>  
>  Except for important bug fixes, we don't usually add new patches to the
> @@ -525,4 +528,4 @@ other developers to publicly add ``Reviewed-by:`` and, more importantly,
>  ``Tested-by:`` tags.
>  
>  Please note that we expect a detailed description for ``Tested-by:``,
> -identifying what boards were used at the test and what it was tested.
> +identifying what boards were used during the test and what it was tested.

Re: [PATCHv7 1/3] docs: media: update maintainer-entry-profile for multi-committers

[Bryan O'Donoghue]

On 27/01/2026 10:53, Hans Verkuil wrote:
> From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> 
> 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>
> Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>
Reviewed-by: Bryan O'Donoghue <bod@kernel.org>

---
bod

Re: [PATCHv7 2/3] docs: media: document Media Maintainers

[Bryan O'Donoghue]

On 27/01/2026 10:53, Hans Verkuil wrote:
> Document who the Media Maintainers are and what their
> responsibilities are.
> 
> Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>
> ---
>   .../media/maintainer-entry-profile.rst        | 47 +++++++++++++++++--
>   1 file changed, 44 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> index be4728b97759..4f73ee073860 100644
> --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> @@ -346,13 +346,54 @@ With the pull request workflow, pull requests shall use PGP-signed tags.
>   For more details about PGP signing, please read
>   Documentation/process/maintainer-pgp-guide.rst.
>   
> -Subsystem Media Maintainers
> ----------------------------
> +List of Media Maintainers
> +-------------------------
>   
> -The subsystem maintainers are:
> +The Media Maintainers listed here all have patchwork access and can
> +make Pull Requests or have commit rights.
> +
> +The Media Subsystem Maintainers are:
>     - Mauro Carvalho Chehab <mchehab@kernel.org>
>     - Hans Verkuil <hverkuil@kernel.org>
>   
> +The Media Core Maintainers are:
> +  - Sakari Ailus <sakari.ailus@linux.intel.com>
> +
> +    - ISP
> +    - sensor drivers
> +    - v4l2-async and v4l2-fwnode core frameworks
> +    - v4l2-flash-led-class core framework
> +
> +  - Mauro Carvalho Chehab <mchehab@kernel.org>
> +
> +    - DVB
> +
> +  - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> +
> +    - Media controller drivers
> +    - Core media controller framework
> +
> +  - Hans Verkuil <hverkuil@kernel.org>
> +
> +    - V4L2 drivers
> +    - V4L2 and videobuf2 core frameworks
> +    - HDMI CEC drivers
> +    - HDMI CEC core framework
> +
> +  - Sean Young <sean@mess.org>
> +
> +    - Remote Controller (infrared) drivers
> +    - Remote Controller (infrared) core framework
> +
> +The Media Driver Maintainers responsible for specific areas are:
> +  - Nicolas Dufresne <nicolas.dufresne@collabora.com>
> +
> +    - Codec drivers
> +
> +  - Bryan O'Donoghue <bryan.odonoghue@linaro.org>
> +
> +    - Qualcomm drivers
> +
>   Submit Checklist Addendum
>   -------------------------
>   
Reviewed-by: Bryan O'Donoghue <bryan.odonoghue@linaro.org>

Re: [PATCH 2/2] docs: media: media-committer: do some editorial changes

[Hans Verkuil]

Hi Mauro,

For the most part I agree, but I have some suggestions regarding the point 4
you added, since I think it just restates what is already mentioned in
maintainer-entry-profile.rst.

Let me know what you think of my suggestions.

On 2/4/26 15:37, Mauro Carvalho Chehab wrote:
> Do some editorial changes to make it look clearer:
> 
>   - media-committers tree references corrected from singular to plural;
>   - updated commit rights wording and responsibilities;
>   - fixed various typographical errors;
>   - corrected “mailing list” and “Kernel” references;
>   - improved core committer description;
>   - updated documentation paths and URLs;
>   - added missing “for” and improved sentence flow.
> 
> Perhaps the most relevant change is that i removed a word
> that was requiring granting Patchwork rights some time before
> adding commit rights (we may grant them altogether if makes
> sense for us), and I added a 4th note to committer notes
> list to let it clear that about what it is expected from a
> committer with regards to updating Patchwork.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  .../driver-api/media/media-committer.rst      | 97 ++++++++++---------
>  1 file changed, 51 insertions(+), 46 deletions(-)
> 
> diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
> index 18cce6e06a2b..c83e94750e57 100644
> --- a/Documentation/driver-api/media/media-committer.rst
> +++ b/Documentation/driver-api/media/media-committer.rst
> @@ -20,8 +20,8 @@ and the Linux Media community.
>  
>  .. Note::

Re-reading this I don't really think this should be a note at all. This just
lists the additional responsibilities of a media committer, no need to
present this as a 'note'.

>  
> -   1. Patches you authored must have a Signed-off-by, Reviewed-by or Acked-by
> -      of another Media Maintainer;
> +   1. Patches you authored must have a ``Signed-off-by``, ``Reviewed-by``
> +      or ``Acked-by`` from another Media Maintainer;
>     2. If a patch introduces a regression, then it is the Media Committer's
>        responsibility to correct that as soon as possible. Typically the
>        patch is either reverted, or an additional patch is committed to
> @@ -29,14 +29,18 @@ and the Linux Media community.
>     3. If patches are fixing bugs against already released Kernels, including
>        the reverts above mentioned, the Media Committer shall add the needed
>        tags. Please see :ref:`Media development workflow` for more details.
> +   4. All Media Committers are responsible for maintaining
> +      `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
> +      updating the state of the patches they review or merge.
> +

I don't really agree with this. Not that it hurts, but maintaining patchwork
is a job of media maintainers. The only addition for committers is that they
have to update patches in patchwork to 'Accepted' when they have committed
them. That is certainly worth mentioning (including updating the maintainers
profile to clearly state that only committers can set it to Accepted.

So in maintainer-entry-profile.rst in 1.3 I would change the description for
the Accepted state to:

"Accepted: Once a patch is merged in the media-committers tree. Only Media
Maintainers with commit rights can set this state."

And change point 4 to this:

4. After committing a patch, the Media Committer must also update the
   patch status to ``Accepted`` in
   `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_.

>  
>  Becoming a Media Committer
>  --------------------------
>  
>  Existing Media Committers can nominate a Media Maintainer to be granted
> -commit rights. The Media Maintainer must already have patchwork access and
> -have been in that role for some time, and has demonstrated a good
> -understanding of the maintainer's duties and processes.
> +commit rights. The Media Maintainer must have patchwork access,
> +have been reviewing patches from third parties for some time, and has
> +demonstrated a good understanding of the maintainer's duties and processes.
>  
>  The ultimate responsibility for accepting a nominated committer is up to
>  the Media Subsystem Maintainers. The nominated committer must have earned a
> @@ -61,8 +65,8 @@ Media Committer's agreement
>  Once a nominated committer is accepted by all Media Subsystem Maintainers,
>  they will ask if the developer is interested in the nomination and discuss
>  what area(s) of the media subsystem the committer will be responsible for.
> -Those areas will typically be the same as the areas that are already
> -maintained by the nominated committer.
> +Those areas will typically be the same as the areas that the nominated
> +committer is already maintaining.
>  
>  When the developer accepts being a committer, the new committer shall
>  explicitly accept the Kernel development policies described under its
> @@ -77,7 +81,7 @@ following the model below::
>  
>     ...
>  
> -   For the purpose of committing patches to the media-committer's tree,
> +   For the purpose of committing patches to the media-committers tree,
>     I'll be using my user https://gitlab.freedesktop.org/users/<username>.
>  
>  Followed by a formal declaration of agreement with the Kernel development
> @@ -85,7 +89,7 @@ rules::
>  
>     I agree to follow the Kernel development rules described at:
>  
> -   https://www.kernel.org/doc/html/latest/driver-api/media/media-committer.rst
> +   https://www.kernel.org/doc/html/latest/driver-api/media/media-committers.rst

BTW, I agree that this file should be renamed to media-committers.rst. That matches
the name of our git tree as well.

>  
>     and to the Linux Kernel development process rules.
>  
> @@ -97,18 +101,17 @@ rules::
>     my commit rights.
>  
>     I am aware that the Kernel development rules change over time.
> -   By doing a new push to media-committer tree, I understand that I agree
> +   By doing a new push to media-committers tree, I understand that I agree
>     to follow the rules in effect at the time of the commit.
>  
> -That e-mail shall be signed with a PGP key cross signed by other Kernel and
> -media developers. As described at :ref:`media-developers-gpg`, the PGP
> -signature, together with the gitlab user security are fundamental components
> -that ensure the authenticity of the merge requests that will happen at the
> -media-committer.git tree.
> +That e-mail shall be signed via the Kernel Web of trust with a PGP key cross
> +signed by other Kernel and media developers. As described at
> +:ref:`media-developers-gpg`, the PGP signature, together with the gitlab user
> +security are fundamental components that ensure the authenticity of the merge
> +requests that will happen at the media-committers.git tree.
>  
> -In case the kernel development process changes, by merging new commits
> -to the
> -`media-committer tree <https://gitlab.freedesktop.org/linux-media/media-committers>`_,
> +In case the kernel development process changes, by merging new commits to the
> +`media-committers tree <https://gitlab.freedesktop.org/linux-media/media-committers>`_,
>  the Media Committer implicitly declares their agreement with the latest
>  version of the documented process including the contents of this file.
>  
> @@ -118,25 +121,27 @@ notify the Media Subsystem Maintainers about that decision.
>  .. note::
>  
>     1. Changes to the kernel media development process shall be announced in
> -      the media-committers mailinglist with a reasonable review period. All
> -      committers are automatically subscribed to that mailinglist;
> +      the media-committers mailing list with a reasonable review period. All
> +      committers are automatically subscribed to that mailing list;
>     2. Due to the distributed nature of the Kernel development, it is
>        possible that kernel development process changes may end being
> -      reviewed/merged at the linux-docs mailing list, specially for the
> -      contents under Documentation/process and for trivial typo fixes.
> +      reviewed/merged at the Linux Docs and/or at the Linux Kernel mailing
> +      lists, especially for the contents under Documentation/process and for
> +      trivial typo fixes.
>  
>  Media Core Committers
>  ---------------------
>  
> -As described in Documentation/driver-api/media/maintainer-entry-profile.rst
> +A Media Core Committer is a Media Core Maintainer with commit rights.
> +
> +As described in Documentation/driver-api/media/maintainer-entry-profile.rst,
>  a Media Core Maintainer maintains media core frameworks as well, besides
> -just drivers, and so is able to change core files and the media subsystem's
> -Kernel API. A Media Core Committer is a Media Core Maintainer with commit
> -rights. The extent of the core committer's grants will be detailed by the
> +just drivers, and so is allowed to change core files and the media subsystem's
> +Kernel API. The extent of the core committer's grants will be detailed by the
>  Media Subsystem Maintainers when they nominate a Media Core Committer.
>  
>  Existing Media Committers may become Media Core Committers and vice versa.
> -Such decisions will be taken in consensus between the Media Subsystem
> +Such decisions will be taken in consensus among the Media Subsystem
>  Maintainers.
>  
>  Media committers rules
> @@ -148,16 +153,16 @@ shall be merged as soon as possible, aiming to be merged at the same Kernel
>  cycle the bug is reported.
>  
>  Media committers shall behave accordingly to the rights granted by
> -the Media Subsystem Maintainers, specially with regards of the scope of changes
> +the Media Subsystem Maintainers, especially with regards of the scope of changes
>  they may apply directly at the media-committers tree. That scope can
> -change over time on a mutual agreement between media committers and
> -maintainers.
> +change over time on a mutual agreement between Media Committers and
> +Media Subsystem Maintainers.
>  
>  The Media Committer workflow is described at :ref:`Media development workflow`.
>  
>  .. _Maintain Media Status:
>  
> -Maintaining media maintainer or committer status
> +Maintaining Media Maintainer or Committer status
>  ------------------------------------------------
>  
>  A community of maintainers working together to move the Linux Kernel
> @@ -165,27 +170,27 @@ forward is essential to creating successful projects that are rewarding
>  to work on. If there are problems or disagreements within the community,
>  they can usually be solved through healthy discussion and debate.
>  
> -In the unhappy event that a media maintainer or committer continues to
> +In the unhappy event that a Media Maintainer or Committer continues to
>  disregard good citizenship (or actively disrupts the project), we may need
>  to revoke that person's status. In such cases, if someone suggests the
> -revocation with a good reason, then after discussing this among the media
> -maintainers, the final decision is taken by the Media Subsystem Maintainers.
> -As the decision to become a media maintainer or committer comes from a
> -consensus between Media Subsystem Maintainers, a single subsystem maintainer
> -not trusting the media maintainer or committer anymore is enough to revoke
> -the maintenance/patchwork or commit rights.
> +revocation with a good reason, then after discussing this among the Media
> +Maintainers, the final decision is taken by the Media Subsystem Maintainers.
>  
> -A previous committer that had their commit rights revoked can keep
> -contributing to the subsystem via the pull request workflow as documented
> -at the :ref:`Media development workflow`, unless they were also removed as
> -Media Maintainer.
> +As the decision to become a Media Maintainer or Committer comes from a
> +consensus between Media Subsystem Maintainers, a single Media Subsystem
> +Maintainer not trusting the Media Maintainer or Committer anymore is enough
> +to revoke their maintenance, Patchwork grants and/or commit rights.
> +
> +Having commit rights revoked doesn't prevent Media Maintainers to keep
> +contributing to the subsystem either via the pull request or via email workflow
> +as documented at the :ref:`Media development workflow`.
>  
>  If a maintainer is inactive for more than a couple of Kernel cycles,
>  maintainers will try to reach you via e-mail. If not possible, they may
> -revoke your maintainer/patchwork and committer rights and update MAINTAINERS file
> -entries accordingly. If you wish to resume contributing later on, then contact
> -the Media Subsystem Maintainers to ask if your maintenance/patchwork and
> -commit rights can be restored.
> +revoke their maintainer/patchwork and committer rights and update MAINTAINERS
> +file entries accordingly. If you wish to resume contributing as maintainer
> +later on, then contact the Media Subsystem Maintainers to ask if your
> +maintenance, Patchwork grants and commit rights can be restored.
>  
>  References
>  ----------


Regards,

	Hans

Re: [PATCH 2/2] docs: media: media-committer: do some editorial changes

[Mauro Carvalho Chehab]

On Thu, Feb 05, 2026 at 12:52:35PM +0100, Hans Verkuil wrote:
> Hi Mauro,
> 
> For the most part I agree, but I have some suggestions regarding the point 4
> you added, since I think it just restates what is already mentioned in
> maintainer-entry-profile.rst.
> 
> Let me know what you think of my suggestions.
> 
> On 2/4/26 15:37, Mauro Carvalho Chehab wrote:
> > Do some editorial changes to make it look clearer:
> > 
> >   - media-committers tree references corrected from singular to plural;
> >   - updated commit rights wording and responsibilities;
> >   - fixed various typographical errors;
> >   - corrected “mailing list” and “Kernel” references;
> >   - improved core committer description;
> >   - updated documentation paths and URLs;
> >   - added missing “for” and improved sentence flow.
> > 
> > Perhaps the most relevant change is that i removed a word
> > that was requiring granting Patchwork rights some time before
> > adding commit rights (we may grant them altogether if makes
> > sense for us), and I added a 4th note to committer notes
> > list to let it clear that about what it is expected from a
> > committer with regards to updating Patchwork.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  .../driver-api/media/media-committer.rst      | 97 ++++++++++---------
> >  1 file changed, 51 insertions(+), 46 deletions(-)
> > 
> > diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
> > index 18cce6e06a2b..c83e94750e57 100644
> > --- a/Documentation/driver-api/media/media-committer.rst
> > +++ b/Documentation/driver-api/media/media-committer.rst
> > @@ -20,8 +20,8 @@ and the Linux Media community.
> >  
> >  .. Note::
> 
> Re-reading this I don't really think this should be a note at all. This just
> lists the additional responsibilities of a media committer, no need to
> present this as a 'note'.

Agreed.

> >  
> > -   1. Patches you authored must have a Signed-off-by, Reviewed-by or Acked-by
> > -      of another Media Maintainer;
> > +   1. Patches you authored must have a ``Signed-off-by``, ``Reviewed-by``
> > +      or ``Acked-by`` from another Media Maintainer;
> >     2. If a patch introduces a regression, then it is the Media Committer's
> >        responsibility to correct that as soon as possible. Typically the
> >        patch is either reverted, or an additional patch is committed to
> > @@ -29,14 +29,18 @@ and the Linux Media community.
> >     3. If patches are fixing bugs against already released Kernels, including
> >        the reverts above mentioned, the Media Committer shall add the needed
> >        tags. Please see :ref:`Media development workflow` for more details.
> > +   4. All Media Committers are responsible for maintaining
> > +      `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
> > +      updating the state of the patches they review or merge.
> > +
> 
> I don't really agree with this. Not that it hurts, but maintaining patchwork
> is a job of media maintainers.

Not really: "normal" media driver maintainers don't need to do that, and, even
if we write they should, I doubt most would.

In practice, I expect only core maintainers, subsystem maitnainers and a couple
of driver maintainers to actually update it.

I'd like to keep a mention here, as we expect media committers to actually
read this file and understand what it is expected from them. As such,
it doesn't hurt letting something explicit here.

The point is: if a committer forgets to update it, we may end having the
same patch being reviewed by two people at different moments, wasting
precious review time. Worse than that, if a rejected patch was kept
as new on patchwork, another committer may end wrongly merging it.

> The only addition for committers is that they
> have to update patches in patchwork to 'Accepted' when they have committed
> them. That is certainly worth mentioning (including updating the maintainers
> profile to clearly state that only committers can set it to Accepted.

With the "committers hat", yes: most of the time it will be just "Accepted",
but, even so, if they pick a series with duplicated patches, other status
needs to be updated, like "duplicated" and "superseeded". 

> So in maintainer-entry-profile.rst in 1.3 I would change the description for
> the Accepted state to:
> 
> "Accepted: Once a patch is merged in the media-committers tree. Only Media
> Maintainers with commit rights can set this state."

Sounds good.

> And change point 4 to this:
> 
> 4. After committing a patch, the Media Committer must also update the
>    patch status to ``Accepted`` in
>    `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_.

I would avoid restricting it - or if you want to verbose what status
type, those are the ones we currently have on patchwork(*):

	Under Review
	Accepted
	Rejected
	RFC
	Not Applicable
	Changes Requested
	Awaiting Upstream
	Superseded
	Deferred
	Obsoleted	
	TODO
	driver maintainer
	Duplicated

(*) Heh, there are some that we only used for a very short period of time,
    or maybe even never used, but we can't delete status there without
    causing potential issues to the database.

> 
> >  
> >  Becoming a Media Committer
> >  --------------------------
> >  
> >  Existing Media Committers can nominate a Media Maintainer to be granted
> > -commit rights. The Media Maintainer must already have patchwork access and
> > -have been in that role for some time, and has demonstrated a good
> > -understanding of the maintainer's duties and processes.
> > +commit rights. The Media Maintainer must have patchwork access,
> > +have been reviewing patches from third parties for some time, and has
> > +demonstrated a good understanding of the maintainer's duties and processes.
> >  
> >  The ultimate responsibility for accepting a nominated committer is up to
> >  the Media Subsystem Maintainers. The nominated committer must have earned a
> > @@ -61,8 +65,8 @@ Media Committer's agreement
> >  Once a nominated committer is accepted by all Media Subsystem Maintainers,
> >  they will ask if the developer is interested in the nomination and discuss
> >  what area(s) of the media subsystem the committer will be responsible for.
> > -Those areas will typically be the same as the areas that are already
> > -maintained by the nominated committer.
> > +Those areas will typically be the same as the areas that the nominated
> > +committer is already maintaining.
> >  
> >  When the developer accepts being a committer, the new committer shall
> >  explicitly accept the Kernel development policies described under its
> > @@ -77,7 +81,7 @@ following the model below::
> >  
> >     ...
> >  
> > -   For the purpose of committing patches to the media-committer's tree,
> > +   For the purpose of committing patches to the media-committers tree,
> >     I'll be using my user https://gitlab.freedesktop.org/users/<username>.
> >  
> >  Followed by a formal declaration of agreement with the Kernel development
> > @@ -85,7 +89,7 @@ rules::
> >  
> >     I agree to follow the Kernel development rules described at:
> >  
> > -   https://www.kernel.org/doc/html/latest/driver-api/media/media-committer.rst
> > +   https://www.kernel.org/doc/html/latest/driver-api/media/media-committers.rst
> 
> BTW, I agree that this file should be renamed to media-committers.rst. That matches
> the name of our git tree as well.

Good. Please check at the maintainers profile if we don't have a reference with
the singular when submitting v8, as I guess we have.

Regards,
Mauro

Re: [PATCH 1/2] docs: media: maintainer-entry-profile: do some editorial reviews

[Mauro Carvalho Chehab]

On Thu, Feb 05, 2026 at 12:25:39PM +0100, Hans Verkuil wrote:
> Hi Mauro,
> 
> Looks good. Just three minor issues (two typos, and one suggestion for a better word).

Good enough for me.

> 
> If there are no objections, then I will just make those changes and fold it into this
> patch for v8.
> 
> Regards,
> 
> 	Hans

Regards,
Mauro

> 
> On 2/4/26 15:37, Mauro Carvalho Chehab wrote:
> > Do some editorial improvements to the Media Subsystem Profile
> > documentation:
> > 
> > - Some English fixups and cleanups;
> > - Capitalize patchwork;
> > - Uncapitalize pull requests, as other occurrences are in lower case;
> > - Added bold markups to the 3 types of media maintainers;
> > - ensure that the document uses 80 chars per line;
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  .../media/maintainer-entry-profile.rst        | 157 +++++++++---------
> >  1 file changed, 80 insertions(+), 77 deletions(-)
> > 
> > diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > index 0024f85101b7..bb95611f0a84 100644
> > --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> > +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > @@ -4,7 +4,7 @@ Media Subsystem Profile
> >  Overview
> >  --------
> >  
> > -The Linux Media Community (aka: the LinuxTV Community) is formed of
> > +The Linux Media Community (aka: the LinuxTV Community) is formed by
> >  developers working on Linux Kernel Media Subsystem, together with users
> >  who also play an important role in testing the code.
> >  
> > @@ -27,7 +27,7 @@ tree:
> >  .. [1] Device tree bindings are maintained by the
> >         OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers
> >         (see the MAINTAINERS file). So, changes there must be reviewed
> > -       by them before being merged via the media subsystem's development
> > +       by them before being merged into the media subsystem's development
> >         tree.
> >  
> >  Both media userspace and Kernel APIs are documented and the documentation
> > @@ -38,32 +38,33 @@ corresponding API documentation.
> >  Media Maintainers
> >  -----------------
> >  
> > +Media Maintainers are not just people capable of writing code, but they
> > +are developers who have demonstrated their ability to collaborate with
> > +the team, get the most knowledgeable people to review code, contribute
> > +high-quality code, and follow through to fix issues (in code or tests).
> > +
> >  Due to the size and wide scope of the media subsystem, multiple layers of
> >  maintainers are required, each with their own areas of expertise:
> >  
> > -- Media Driver Maintainer:
> > -    Responsible for one or more drivers within the Media Subsystem. You
> > +- **Media Driver Maintainer**:
> > +    Responsible for one or more drivers within the Media Subsystem. They
> >      are listed in the MAINTAINERS file as maintainer for those drivers. Media
> >      Driver Maintainers review patches for those drivers, provide feedback if
> > -    the patches are not following the subsystem rules, or are not using the
> > -    media kernel or userspace APIs correctly, or have poor code quality.
> > +    patches do not follow the subsystem rules, or are not using the
> > +    media kernel or userspace APIs correctly, or if they have poor code
> > +    quality.
> >  
> > -    If you are the author of the patches, then you work with other Media
> > +    If you are the patch author, you work with other Media
> >      Maintainers to ensure your patches are reviewed.
> >  
> > -    Some Media Driver Maintainers have additional responsibilities.  They have
> > -    been granted patchwork access and keep
> > -    `patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> > +    Some Media Driver Maintainers have additional responsibilities. They have
> > +    been granted Patchwork access and keep
> > +    `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> >      up to date, decide when patches are ready for merging, and create Pull
> >      Requests for the Media Subsystem Maintainers to merge.
> >  
> > -    Such Media Driver Maintainers are not just someone who is capable of creating code,
> > -    but someone who has demonstrated their ability to collaborate with the team,
> > -    get the most knowledgeable people to review code, contribute high-quality code,
> > -    and follow through to fix issues (in code or tests).
> > -
> > -- Media Core Maintainer:
> > -    Media Driver Maintainers with patchwork access who are also responsible for
> > +- **Media Core Maintainer**:
> > +    Media Driver Maintainers with Patchwork access who are also responsible for
> >      one or more media core frameworks.
> >  
> >      Core framework changes are done via consensus between the relevant Media
> > @@ -71,22 +72,21 @@ maintainers are required, each with their own areas of expertise:
> >      their Pull Requests if they are signed off by the relevant Media Core
> >      Maintainers.
> >  
> > -- Media Subsystem Maintainers:
> > -    Media Core Maintainers who are also responsible for the subsystem as a whole,
> > -    with access to the entire subsystem. Responsible for merging Pull Requests
> > -    from other Media Maintainers.
> > +- **Media Subsystem Maintainers**:
> > +    Media Core Maintainers who are also responsible for the subsystem as a
> > +    whole, with access to the entire subsystem. Responsible for merging Pull
> > +    Requests from other Media Maintainers.
> >  
> > -    Userspace API/ABI changes are done via consensus between Media Subsystem
> > +    Userspace API/ABI changes are made via consensus among Media Subsystem
> >      Maintainers\ [2]_. Media Maintainers may include API/ABI changes in
> > -    their Pull Requests if they are signed off by the all Media Subsystem
> > +    their pull requests if they are signed off by all Media Subsystem
> >      Maintainers.
> >  
> > -All Media Maintainers shall explicitly agree with the Kernel development process
> > -as described at Documentation/process/index.rst and to the Kernel
> > -development rules inside the Kernel documentation, including its code of
> > -conduct.
> > +All Media Maintainers shall agree with the Kernel development process as
> > +described in Documentation/process/index.rst and with the Kernel development
> > +rules in the Kernel documentation, including its code of conduct.
> >  
> > -Media Maintainers are reachable via the #linux-media IRC channel at OFTC.
> > +Media Maintainers are often reachable via the #linux-media IRC channel at OFTC.
> >  
> >  .. [2] Everything that would break backward compatibility with existing
> >         non-kernel code are API/ABI changes. This includes ioctl and sysfs
> > @@ -95,8 +95,8 @@ Media Maintainers are reachable via the #linux-media IRC channel at OFTC.
> >  Patchwork Access
> >  ----------------
> >  
> > -All Media Maintainers who have been granted patchwork access shall ensure that
> > -`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> > +All Media Maintainers who have been granted Patchwork access shall ensure that
> > +`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> >  will reflect the current status, e.g. patches shall be delegated to the Media
> >  Maintainer who is handling them and the patch status shall be updated according
> >  to these rules:
> > @@ -112,28 +112,28 @@ to these rules:
> >    tree (e.g. drm, dmabuf, upstream merge, etc.) but were cross-posted to the
> >    linux-media mailing list.
> >  
> > -If a Media Maintainer decides not to accept a patch, then reply by email to
> > -the patch authors, explaining why it is not accepted, and
> > -`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_ shall be
> > -updated accordingly with either:
> > +If Media Maintainers decide not to accept a patch, they should reply to the
> > +patch authors by e‑mail, explaining why it is not accepted, and
> > +update `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> > +accordingly with one of the following statuses:
> >  
> >  - ``Changes Requested``: if a new revision was requested;
> >  - ``Rejected``: if the proposed change is not acceptable at all.
> >  
> >  .. Note::
> >  
> > -   Patchwork supports a couple of clients to help semi-automating
> > +   Patchwork supports a couple of clients to help semi-automate
> >     status updates via its REST interface:
> >  
> >     https://patchwork.readthedocs.io/en/latest/usage/clients/
> >  
> > -For those patches that fall in your area of responsibility you alse decide
> > -when those patches are ready for merging, and create Pull Requests for the
> > -Media Subsystem Maintainers to merge.
> > +For patches that fall within their area of responsibility a Media Maintainer
> > +also decide when those patches are ready for merging, and create Pull Requests
> 
> decide -> decides
> 
> > +for the Media Subsystem Maintainers to merge.
> >  
> > -The most important aspect of becoming a Media Maintainer with patchwork access
> > -is that you have demonstrated the ability to give good code reviews. So we are
> > -looking for whether or not we think you will be good at doing that.
> > +The most important aspect of becoming a Media Maintainer with Patchwork access
> > +is that you have demonstrated an ability to give good code reviews. We value
> > +your ability to deliver thorough, constructive code reviews.
> >  
> >  As such, potential maintainers must earn enough credibility and trust from the
> >  Linux Media Community. To do that, developers shall be familiar with the open
> > @@ -145,7 +145,7 @@ demonstrating your:
> >  
> >  - commitment to the project;
> >  - ability to collaborate with the team and communicate well;
> > -- understand of how upstream and the Linux Media Community work
> > +- understanding of how upstream and the Linux Media Community work
> >    (policies, processes for testing, code review, ...)
> >  - reasonable knowledge about:
> >  
> > @@ -160,9 +160,9 @@ demonstrating your:
> >  - ability to judge when a patch might be ready for review and to submit;
> >  - ability to write good code (last but certainly not least).
> >  
> > -Media Driver Maintainers that desire to get patchwork access are encouraged
> > +Media Driver Maintainers that desire to get Patchwork access are encouraged
> >  to participate at the yearly Linux Media Summit, typically co-located with
> > -a Linux related conference. These summits are announced on the linux-media
> > +a Linux-related conference. These summits are announced on the linux-media
> >  mailing list.
> >  
> >  If you are doing such tasks and have become a valued developer, an
> > @@ -170,8 +170,8 @@ existing Media Maintainer can nominate you to the Media Subsystem Maintainers.
> >  
> >  The ultimate responsibility for accepting a nominated maintainer is up to
> >  the subsystem's maintainers. The nominated maintainer must have earned a trust
> > -relationship with all Media Subsystem Maintainers, as, by being granted patchwork
> > -access, you will take over part of their maintenance tasks.
> > +relationship with all Media Subsystem Maintainers, as, by being granted
> > +Patchwork access, you will take over part of their maintenance tasks.
> >  
> >  Media Committers
> >  ----------------
> > @@ -191,14 +191,18 @@ The main development tree used by the media subsystem is hosted at
> >  https://gitlab.freedesktop.org/linux-media/.
> >  https://linuxtv.org/ hosts news about the subsystem,
> >  `wiki <https://www.linuxtv.org/wiki/index.php/Main_Page>`_ pages
> > -and a `patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> > +and a `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> >  instance where we track patches though their lifetime.
> >  
> > -The main tree used by media developers is at:
> > +The stable tree used by media developers is at:
> > +
> > +https://git.linuxtv.org/media.git/
> > +
> > +Patches there are initially committed to the media committers tree:
> >  
> >  https://gitlab.freedesktop.org/linux-media/media-committers.git
> >  
> > -Please note that this tree can be rebased, although only as a last resort.
> > +Please note that the later can be rebased, although only as a last resort.
> 
> later -> latter
> 
> >  
> >  .. _Media development workflow:
> >  
> > @@ -217,11 +221,11 @@ you can find details about how to subscribe to it and to see its archives at:
> >  
> >  Emails with HTML will be automatically rejected by the mail server.
> >  
> > -It could be wise to also copy the Media Maintainer(s). You should use
> > +It could be wise to also copy the relevant Media Maintainer(s). You should use
> >  ``scripts/get_maintainers.pl`` to identify whom else needs to be copied.
> >  Please always copy driver's authors and maintainers.
> >  
> > -To minimize the chance of merge conflicts for your patch series, and make
> > +To minimize the chance of merge conflicts for your patch series, and make it
> >  easier to backport patches to stable Kernels, we recommend that you use the
> >  following baseline for your patch series:
> >  
> > @@ -267,13 +271,14 @@ workflows:
> >  a. Media Maintainers' workflow: Media Maintainers post the PRs, which are
> >     handled by the Media Subsystem Maintainers::
> >  
> > -     +-------+   +------------+   +------+   +-------+   +----------------------------+
> > -     |e-mail |-->|picked up by|-->|code  |-->|pull   |-->|Subsystem Maintainers merge |
> > -     |to LMML|   |patchwork   |   |review|   |request|   |in media-committers.git     |
> > -     +-------+   +------------+   +------+   +-------+   +----------------------------+
> > +     +-------+   +------------+   +------+   +-------+   +---------------------+
> > +     |e-mail |-->|picked up by|-->|code  |-->|pull   |-->|Subsystem Maintainers|
> > +     |to LMML|   |Patchwork   |   |review|   |request|   |merge in             |
> > +     |       |   |            |   |      |   |       |   |media-committers.git |
> > +     +-------+   +------------+   +------+   +-------+   +---------------------+
> >  
> >     For this workflow, pull requests are generated by Media Maintainers with
> > -   patchwork access.  If you do not have patchwork access, then please don't
> > +   Patchwork access.  If you do not have Patchwork access, then please don't
> >     submit pull requests, as they will not be processed.
> >  
> >  b. Media Committers' workflow: patches are handled by Media Maintainers with
> > @@ -281,15 +286,14 @@ b. Media Committers' workflow: patches are handled by Media Maintainers with
> >  
> >       +-------+   +------------+   +------+   +--------------------------+
> >       |e-mail |-->|picked up by|-->|code  |-->|Media Committers merge in |
> > -     |to LMML|   |patchwork   |   |review|   |media-committers.git      |
> > +     |to LMML|   |Patchwork   |   |review|   |media-committers.git      |
> >       +-------+   +------------+   +------+   +--------------------------+
> >  
> >  When patches are picked up by
> > -`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> > -and when merged at media-committers,
> > -Media CI bots will check for errors and may provide e-mail feedback about
> > -patch problems. When this happens, the patch submitter must fix them or
> > -explain why the errors are false positives.
> > +`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
> > +and when merged at media-committers, Media CI bots will check for errors and
> > +may provide e-mail feedback about patch problems. When this happens, the patch
> > +submitter must fix them or explain why the errors are false positives.
> >  
> >  Patches will only be moved to the next stage in these two workflows if they
> >  pass on Media CI or if there are false-positives in the Media CI reports.
> > @@ -327,18 +331,17 @@ server has accepted your patch, by looking at:
> >     - https://lore.kernel.org/linux-media/
> >  
> >  If the patch is there and not at
> > -`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
> > -it is likely that your e-mailer
> > -mangled the patch. Patchwork internally has logic that checks if the
> > -received e-mail contains a valid patch. Any whitespace and new line
> > -breakages mangling the patch won't be recognized by
> > -`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
> > +`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
> > +it is likely that your e-mailer mangled the patch. Patchwork internally
> > +has logic that checks if the received e-mail contains a valid patch.
> > +Any whitespace and new line breakages mangling the patch won't be recognized by
> > +`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
> >  and such a patch will be rejected.
> >  
> >  .. [3] It usually takes a few minutes for the patch to arrive, but
> > -       the e-mail server may be busy, so it may take up a longer time
> > +       the e-mail server may be busy, so it may take a longer time
> >         for a patch to be picked by
> > -       `patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_.
> > +       `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_.
> >  
> >  .. [4] If your email contains HTML, the mailing list server will simply
> >         drop it, without any further notice.
> > @@ -349,8 +352,8 @@ Authentication for pull and merge requests
> >  ++++++++++++++++++++++++++++++++++++++++++
> >  
> >  The authenticity of developers submitting pull requests and merge requests
> > -shall be validated by using PGP signing at some moment.
> > -See: :ref:`kernel_org_trust_repository`.
> > +shall be validated by using the Linux Kernel Web of Trust, with PGP signing
> > +at some moment. See: :ref:`kernel_org_trust_repository`.
> >  
> >  With the pull request workflow, pull requests shall use PGP-signed tags.
> >  
> > @@ -494,11 +497,11 @@ least, simply wrapping the lines.
> >  In particular, we accept lines with more than 80 columns:
> >  
> >      - on strings, as they shouldn't be broken due to line length limits;
> > -    - when a function or variable name need to have a big identifier name,
> > -      which keeps hard to honor the 80 columns limit;
> > +    - when a function or variable name needs to have a large identifier name,
> 
> large -> long ('long' makes much more sense in this context)
> 
> > +      which makes hard to honor the 80 columns limit;
> >      - on arithmetic expressions, when breaking lines makes them harder to
> >        read;
> > -    - when they avoid a line to end with an open parenthesis or an open
> > +    - when they avoid a line ending with an open parenthesis or an open
> >        bracket.
> >  
> >  Key Cycle Dates
> > @@ -512,7 +515,7 @@ Review Cadence
> >  --------------
> >  
> >  Provided that your patch has landed in
> > -`patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_, it
> > +`Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_, it
> >  should be sooner or later handled, so you don't need to re-submit a patch.
> >  
> >  Except for important bug fixes, we don't usually add new patches to the
> > @@ -525,4 +528,4 @@ other developers to publicly add ``Reviewed-by:`` and, more importantly,
> >  ``Tested-by:`` tags.
> >  
> >  Please note that we expect a detailed description for ``Tested-by:``,
> > -identifying what boards were used at the test and what it was tested.
> > +identifying what boards were used during the test and what it was tested.
> 

-- 
Thanks,
Mauro

Re: [PATCH 2/2] docs: media: media-committer: do some editorial changes

[Hans Verkuil]

On 2/5/26 14:51, Mauro Carvalho Chehab wrote:
> On Thu, Feb 05, 2026 at 12:52:35PM +0100, Hans Verkuil wrote:
>> Hi Mauro,
>>
>> For the most part I agree, but I have some suggestions regarding the point 4
>> you added, since I think it just restates what is already mentioned in
>> maintainer-entry-profile.rst.
>>
>> Let me know what you think of my suggestions.
>>
>> On 2/4/26 15:37, Mauro Carvalho Chehab wrote:
>>> Do some editorial changes to make it look clearer:
>>>
>>>   - media-committers tree references corrected from singular to plural;
>>>   - updated commit rights wording and responsibilities;
>>>   - fixed various typographical errors;
>>>   - corrected “mailing list” and “Kernel” references;
>>>   - improved core committer description;
>>>   - updated documentation paths and URLs;
>>>   - added missing “for” and improved sentence flow.
>>>
>>> Perhaps the most relevant change is that i removed a word
>>> that was requiring granting Patchwork rights some time before
>>> adding commit rights (we may grant them altogether if makes
>>> sense for us), and I added a 4th note to committer notes
>>> list to let it clear that about what it is expected from a
>>> committer with regards to updating Patchwork.
>>>
>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>> ---
>>>  .../driver-api/media/media-committer.rst      | 97 ++++++++++---------
>>>  1 file changed, 51 insertions(+), 46 deletions(-)
>>>
>>> diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
>>> index 18cce6e06a2b..c83e94750e57 100644
>>> --- a/Documentation/driver-api/media/media-committer.rst
>>> +++ b/Documentation/driver-api/media/media-committer.rst
>>> @@ -20,8 +20,8 @@ and the Linux Media community.
>>>  
>>>  .. Note::
>>
>> Re-reading this I don't really think this should be a note at all. This just
>> lists the additional responsibilities of a media committer, no need to
>> present this as a 'note'.
> 
> Agreed.
> 
>>>  
>>> -   1. Patches you authored must have a Signed-off-by, Reviewed-by or Acked-by
>>> -      of another Media Maintainer;
>>> +   1. Patches you authored must have a ``Signed-off-by``, ``Reviewed-by``
>>> +      or ``Acked-by`` from another Media Maintainer;
>>>     2. If a patch introduces a regression, then it is the Media Committer's
>>>        responsibility to correct that as soon as possible. Typically the
>>>        patch is either reverted, or an additional patch is committed to
>>> @@ -29,14 +29,18 @@ and the Linux Media community.
>>>     3. If patches are fixing bugs against already released Kernels, including
>>>        the reverts above mentioned, the Media Committer shall add the needed
>>>        tags. Please see :ref:`Media development workflow` for more details.
>>> +   4. All Media Committers are responsible for maintaining
>>> +      `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_,
>>> +      updating the state of the patches they review or merge.
>>> +
>>
>> I don't really agree with this. Not that it hurts, but maintaining patchwork
>> is a job of media maintainers.
> 
> Not really: "normal" media driver maintainers don't need to do that, and, even
> if we write they should, I doubt most would.

This applies to maintainers with patchwork rights. If you have patchwork access,
then I expect them to keep it up to date for those areas that they maintain.

> 
> In practice, I expect only core maintainers, subsystem maitnainers and a couple
> of driver maintainers to actually update it.

I.e., those with patchwork access.

> 
> I'd like to keep a mention here, as we expect media committers to actually
> read this file and understand what it is expected from them. As such,
> it doesn't hurt letting something explicit here.
> 
> The point is: if a committer forgets to update it, we may end having the
> same patch being reviewed by two people at different moments, wasting
> precious review time. Worse than that, if a rejected patch was kept
> as new on patchwork, another committer may end wrongly merging it.
> 
>> The only addition for committers is that they
>> have to update patches in patchwork to 'Accepted' when they have committed
>> them. That is certainly worth mentioning (including updating the maintainers
>> profile to clearly state that only committers can set it to Accepted.
> 
> With the "committers hat", yes: most of the time it will be just "Accepted",
> but, even so, if they pick a series with duplicated patches, other status
> needs to be updated, like "duplicated" and "superseeded". 
> 
>> So in maintainer-entry-profile.rst in 1.3 I would change the description for
>> the Accepted state to:
>>
>> "Accepted: Once a patch is merged in the media-committers tree. Only Media
>> Maintainers with commit rights can set this state."
> 
> Sounds good.
> 
>> And change point 4 to this:
>>
>> 4. After committing a patch, the Media Committer must also update the
>>    patch status to ``Accepted`` in
>>    `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_.
> 
> I would avoid restricting it - or if you want to verbose what status
> type, those are the ones we currently have on patchwork(*):

I'll just keep your point 4. In the end it doesn't hurt.

Regards,

	Hans

> 
> 	Under Review
> 	Accepted
> 	Rejected
> 	RFC
> 	Not Applicable
> 	Changes Requested
> 	Awaiting Upstream
> 	Superseded
> 	Deferred
> 	Obsoleted	
> 	TODO
> 	driver maintainer
> 	Duplicated
> 
> (*) Heh, there are some that we only used for a very short period of time,
>     or maybe even never used, but we can't delete status there without
>     causing potential issues to the database.
> 
>>
>>>  
>>>  Becoming a Media Committer
>>>  --------------------------
>>>  
>>>  Existing Media Committers can nominate a Media Maintainer to be granted
>>> -commit rights. The Media Maintainer must already have patchwork access and
>>> -have been in that role for some time, and has demonstrated a good
>>> -understanding of the maintainer's duties and processes.
>>> +commit rights. The Media Maintainer must have patchwork access,
>>> +have been reviewing patches from third parties for some time, and has
>>> +demonstrated a good understanding of the maintainer's duties and processes.
>>>  
>>>  The ultimate responsibility for accepting a nominated committer is up to
>>>  the Media Subsystem Maintainers. The nominated committer must have earned a
>>> @@ -61,8 +65,8 @@ Media Committer's agreement
>>>  Once a nominated committer is accepted by all Media Subsystem Maintainers,
>>>  they will ask if the developer is interested in the nomination and discuss
>>>  what area(s) of the media subsystem the committer will be responsible for.
>>> -Those areas will typically be the same as the areas that are already
>>> -maintained by the nominated committer.
>>> +Those areas will typically be the same as the areas that the nominated
>>> +committer is already maintaining.
>>>  
>>>  When the developer accepts being a committer, the new committer shall
>>>  explicitly accept the Kernel development policies described under its
>>> @@ -77,7 +81,7 @@ following the model below::
>>>  
>>>     ...
>>>  
>>> -   For the purpose of committing patches to the media-committer's tree,
>>> +   For the purpose of committing patches to the media-committers tree,
>>>     I'll be using my user https://gitlab.freedesktop.org/users/<username>.
>>>  
>>>  Followed by a formal declaration of agreement with the Kernel development
>>> @@ -85,7 +89,7 @@ rules::
>>>  
>>>     I agree to follow the Kernel development rules described at:
>>>  
>>> -   https://www.kernel.org/doc/html/latest/driver-api/media/media-committer.rst
>>> +   https://www.kernel.org/doc/html/latest/driver-api/media/media-committers.rst
>>
>> BTW, I agree that this file should be renamed to media-committers.rst. That matches
>> the name of our git tree as well.
> 
> Good. Please check at the maintainers profile if we don't have a reference with
> the singular when submitting v8, as I guess we have.
> 
> Regards,
> Mauro

Re: [PATCHv7 2/3] docs: media: document Media Maintainers

[Nicolas Dufresne]

[-- Attachment #1: Type: text/plain, Size: 2762 bytes --]

Le mardi 27 janvier 2026 à 11:53 +0100, Hans Verkuil a écrit :
> Document who the Media Maintainers are and what their
> responsibilities are.
> 
> Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>
> ---
>  .../media/maintainer-entry-profile.rst        | 47 +++++++++++++++++--
>  1 file changed, 44 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> index be4728b97759..4f73ee073860 100644
> --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> @@ -346,13 +346,54 @@ With the pull request workflow, pull requests shall use PGP-signed tags.
>  For more details about PGP signing, please read
>  Documentation/process/maintainer-pgp-guide.rst.
>  
> -Subsystem Media Maintainers
> ----------------------------
> +List of Media Maintainers
> +-------------------------
>  
> -The subsystem maintainers are:
> +The Media Maintainers listed here all have patchwork access and can
> +make Pull Requests or have commit rights.
> +
> +The Media Subsystem Maintainers are:
>    - Mauro Carvalho Chehab <mchehab@kernel.org>
>    - Hans Verkuil <hverkuil@kernel.org>
>  
> +The Media Core Maintainers are:
> +  - Sakari Ailus <sakari.ailus@linux.intel.com>
> +
> +    - ISP
> +    - sensor drivers
> +    - v4l2-async and v4l2-fwnode core frameworks
> +    - v4l2-flash-led-class core framework
> +
> +  - Mauro Carvalho Chehab <mchehab@kernel.org>
> +
> +    - DVB
> +
> +  - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> +
> +    - Media controller drivers
> +    - Core media controller framework
> +
> +  - Hans Verkuil <hverkuil@kernel.org>
> +
> +    - V4L2 drivers
> +    - V4L2 and videobuf2 core frameworks
> +    - HDMI CEC drivers
> +    - HDMI CEC core framework
> +
> +  - Sean Young <sean@mess.org>
> +
> +    - Remote Controller (infrared) drivers
> +    - Remote Controller (infrared) core framework
> +
> +The Media Driver Maintainers responsible for specific areas are:
> +  - Nicolas Dufresne <nicolas.dufresne@collabora.com>
> +
> +    - Codec drivers

I also took care of M2M color converters lately, while trying to delegate when
it makes sense (such as DWL100 delegated to Laurent). So we may (or may not)
add:

       - M2M driver not otherwise delegated

Reviewed-by: Nicolas Dufresne <nicolas.dufresne@collabora.com>

> +
> +  - Bryan O'Donoghue <bryan.odonoghue@linaro.org>
> +
> +    - Qualcomm drivers
> +
>  Submit Checklist Addendum
>  -------------------------
>  

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCHv7 2/3] docs: media: document Media Maintainers

[Laurent Pinchart]

On Thu, Feb 05, 2026 at 09:24:26AM -0500, Nicolas Dufresne wrote:
> Le mardi 27 janvier 2026 à 11:53 +0100, Hans Verkuil a écrit :
> > Document who the Media Maintainers are and what their
> > responsibilities are.
> > 
> > Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>
> > ---
> >  .../media/maintainer-entry-profile.rst        | 47 +++++++++++++++++--
> >  1 file changed, 44 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > index be4728b97759..4f73ee073860 100644
> > --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> > +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > @@ -346,13 +346,54 @@ With the pull request workflow, pull requests shall use PGP-signed tags.
> >  For more details about PGP signing, please read
> >  Documentation/process/maintainer-pgp-guide.rst.
> >  
> > -Subsystem Media Maintainers
> > ----------------------------
> > +List of Media Maintainers
> > +-------------------------
> >  
> > -The subsystem maintainers are:
> > +The Media Maintainers listed here all have patchwork access and can
> > +make Pull Requests or have commit rights.
> > +
> > +The Media Subsystem Maintainers are:
> >    - Mauro Carvalho Chehab <mchehab@kernel.org>
> >    - Hans Verkuil <hverkuil@kernel.org>
> >  
> > +The Media Core Maintainers are:
> > +  - Sakari Ailus <sakari.ailus@linux.intel.com>
> > +
> > +    - ISP
> > +    - sensor drivers
> > +    - v4l2-async and v4l2-fwnode core frameworks
> > +    - v4l2-flash-led-class core framework
> > +
> > +  - Mauro Carvalho Chehab <mchehab@kernel.org>
> > +
> > +    - DVB
> > +
> > +  - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > +
> > +    - Media controller drivers
> > +    - Core media controller framework

You could list me for ISPs as well, Sakari and I handle the together.

I'm not alone there of course, it's a team effort and Dan and Jacopo are
also active in developing and reviewing multiple ISP drivers. Not that
we necessarily want to list them in this document (and I don't know if
they would be interested), but I want publicly credit them in this mail
for the work they do.

> > +
> > +  - Hans Verkuil <hverkuil@kernel.org>
> > +
> > +    - V4L2 drivers
> > +    - V4L2 and videobuf2 core frameworks
> > +    - HDMI CEC drivers
> > +    - HDMI CEC core framework
> > +
> > +  - Sean Young <sean@mess.org>
> > +
> > +    - Remote Controller (infrared) drivers
> > +    - Remote Controller (infrared) core framework
> > +
> > +The Media Driver Maintainers responsible for specific areas are:
> > +  - Nicolas Dufresne <nicolas.dufresne@collabora.com>
> > +
> > +    - Codec drivers
> 
> I also took care of M2M color converters lately, while trying to delegate when
> it makes sense (such as DWL100 delegated to Laurent). So we may (or may not)
> add:
> 
>        - M2M driver not otherwise delegated
> 
> Reviewed-by: Nicolas Dufresne <nicolas.dufresne@collabora.com>
> 
> > +
> > +  - Bryan O'Donoghue <bryan.odonoghue@linaro.org>
> > +
> > +    - Qualcomm drivers
> > +
> >  Submit Checklist Addendum
> >  -------------------------
> >  

-- 
Regards,

Laurent Pinchart

Re: [PATCHv7 1/3] docs: media: update maintainer-entry-profile for multi-committers

[kernel test robot]

Hi Hans,

kernel test robot noticed the following build warnings:

[auto build test WARNING on lwn/docs-next]
[also build test WARNING on linuxtv-media-pending/master media-tree/master linus/master v6.19-rc8 next-20260205]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Hans-Verkuil/docs-media-update-maintainer-entry-profile-for-multi-committers/20260205-024420
base:   git://git.lwn.net/linux.git docs-next
patch link:    https://lore.kernel.org/r/4478ae7ad952117a76b648ee2db7f8f92775ddf7.1769511207.git.hverkuil%2Bcisco%40kernel.org
patch subject: [PATCHv7 1/3] docs: media: update maintainer-entry-profile for multi-committers
compiler: clang version 20.1.8 (https://github.com/llvm/llvm-project 87f0227cb60147a26a1eeb4fb06e3b505e9c7261)
docutils: docutils (Docutils 0.21.2, Python 3.13.5, on linux)
reproduce: (https://download.01.org/0day-ci/archive/20260205/202602051948.uPjQl80E-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202602051948.uPjQl80E-lkp@intel.com/

All warnings (new ones prefixed by >>):

   Documentation/userspace-api/landlock:453: ./include/uapi/linux/landlock.h:45: ERROR: Unknown target name: "network flags". [docutils]
   Documentation/userspace-api/landlock:453: ./include/uapi/linux/landlock.h:50: ERROR: Unknown target name: "scope flags". [docutils]
   Documentation/userspace-api/landlock:453: ./include/uapi/linux/landlock.h:24: ERROR: Unknown target name: "filesystem flags". [docutils]
   Documentation/userspace-api/landlock:462: ./include/uapi/linux/landlock.h:153: ERROR: Unknown target name: "filesystem flags". [docutils]
   Documentation/userspace-api/landlock:462: ./include/uapi/linux/landlock.h:176: ERROR: Unknown target name: "network flags". [docutils]
>> Documentation/driver-api/media/maintainer-entry-profile.rst:340: WARNING: undefined label: 'kernel_org_trust_repository' [ref.ref]


vim +/kernel_org_trust_repository +340 Documentation/driver-api/media/maintainer-entry-profile.rst

   339	
 > 340	The authenticity of developers submitting pull requests and merge requests
   341	shall be validated by using PGP signing at some moment.
   342	See: :ref:`kernel_org_trust_repository`.
   343	

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

Re: [PATCHv7 2/3] docs: media: document Media Maintainers

[Jacopo Mondi]

Hi Laurent

On Thu, Feb 05, 2026 at 06:59:12PM +0200, Laurent Pinchart wrote:
> On Thu, Feb 05, 2026 at 09:24:26AM -0500, Nicolas Dufresne wrote:
> > Le mardi 27 janvier 2026 à 11:53 +0100, Hans Verkuil a écrit :
> > > Document who the Media Maintainers are and what their
> > > responsibilities are.
> > >
> > > Signed-off-by: Hans Verkuil <hverkuil+cisco@kernel.org>
> > > ---
> > >  .../media/maintainer-entry-profile.rst        | 47 +++++++++++++++++--
> > >  1 file changed, 44 insertions(+), 3 deletions(-)
> > >
> > > diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > > index be4728b97759..4f73ee073860 100644
> > > --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> > > +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > > @@ -346,13 +346,54 @@ With the pull request workflow, pull requests shall use PGP-signed tags.
> > >  For more details about PGP signing, please read
> > >  Documentation/process/maintainer-pgp-guide.rst.
> > >  
> > > -Subsystem Media Maintainers
> > > ----------------------------
> > > +List of Media Maintainers
> > > +-------------------------
> > >  
> > > -The subsystem maintainers are:
> > > +The Media Maintainers listed here all have patchwork access and can
> > > +make Pull Requests or have commit rights.
> > > +
> > > +The Media Subsystem Maintainers are:
> > >    - Mauro Carvalho Chehab <mchehab@kernel.org>
> > >    - Hans Verkuil <hverkuil@kernel.org>
> > >  
> > > +The Media Core Maintainers are:
> > > +  - Sakari Ailus <sakari.ailus@linux.intel.com>
> > > +
> > > +    - ISP
> > > +    - sensor drivers
> > > +    - v4l2-async and v4l2-fwnode core frameworks
> > > +    - v4l2-flash-led-class core framework
> > > +
> > > +  - Mauro Carvalho Chehab <mchehab@kernel.org>
> > > +
> > > +    - DVB
> > > +
> > > +  - Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > > +
> > > +    - Media controller drivers
> > > +    - Core media controller framework
>
> You could list me for ISPs as well, Sakari and I handle the together.
>
> I'm not alone there of course, it's a team effort and Dan and Jacopo are
> also active in developing and reviewing multiple ISP drivers. Not that
> we necessarily want to list them in this document (and I don't know if
> they would be interested), but I want publicly credit them in this mail
> for the work they do.
>

Thanks for pointing it out.

I have sent some pull request in the past and when it makes sense I
intend to do so for the drivers (or framework components) I take care
of.

As long as I can continue doing it, there's no need to list my name
here until we don't get to a model where more people can have commit
rights, which is still something I hope we can get to in a reasonable
time.

In any case, I'm certainly interested in partecipating in any effort
that could make the subsystem a little more agile.

Thanks
  j

> > > +
> > > +  - Hans Verkuil <hverkuil@kernel.org>
> > > +
> > > +    - V4L2 drivers
> > > +    - V4L2 and videobuf2 core frameworks
> > > +    - HDMI CEC drivers
> > > +    - HDMI CEC core framework
> > > +
> > > +  - Sean Young <sean@mess.org>
> > > +
> > > +    - Remote Controller (infrared) drivers
> > > +    - Remote Controller (infrared) core framework
> > > +
> > > +The Media Driver Maintainers responsible for specific areas are:
> > > +  - Nicolas Dufresne <nicolas.dufresne@collabora.com>
> > > +
> > > +    - Codec drivers
> >
> > I also took care of M2M color converters lately, while trying to delegate when
> > it makes sense (such as DWL100 delegated to Laurent). So we may (or may not)
> > add:
> >
> >        - M2M driver not otherwise delegated
> >
> > Reviewed-by: Nicolas Dufresne <nicolas.dufresne@collabora.com>
> >
> > > +
> > > +  - Bryan O'Donoghue <bryan.odonoghue@linaro.org>
> > > +
> > > +    - Qualcomm drivers
> > > +
> > >  Submit Checklist Addendum
> > >  -------------------------
> > >  
>
> --
> Regards,
>
> Laurent Pinchart
>