[PATCH v4 0/5]Document the new media-committer's model

[PATCH v4 0/5]Document the new media-committer's model

[Mauro Carvalho Chehab]

The media subsystem used to have a multi-commiter's model in the
past, but things didn't go well on that time, and we had to move to
a centralized model.

As the community has evolved, and as there are now new policies in
place like CoC, let's experiment with a multi-committers again.

The model we're using was inspired by the DRM multi-committers
model. Yet, media subsystem is different on several aspects, so the
model is not exactly the same.

The implementation will be in phases. For this phase, the goal is that 
all committers will be people listed at MAINTAINERS.

On this series:

patch 1 adds a reference for PGP kernel keychain, in preparation for
links to it;

patch 2 fix two issues at the media MAINTAINERS file (S: and P:) tags;

patch 3: updates the  media maintainer's entry profile and adds the
workflow that will be used with the new model;

patch 4: adds a new document focused at the new maintainers
process. Its target is for developers that will be granted with
commit rights at the new media-maintainers.git tree. It also
contains a reference tag addition to kernel.org PGP chain
at process/maintainer-pgp-guide.rst.

patch 5: make documents cleared about maintainership duties.

---
v4:
- patches 1 and 2 were split from other patches;
- minor editorial changes as proposed by Hans, Sakari and Ricardo.

v3:
- added patch 3;
- addressed nits pointed by Ricardo during his review;
- did minor editorial changes to improve Sphinx html output.

v2: I tried to address most of the suggestions where there was an agreement
from Laurent's review and further comments. As there were several changes,
on separate threads, I could have missed something.

Mauro Carvalho Chehab (5):
  docs: maintainer-pgp-guide.rst: add a reference for kernel.org sign
  MAINTAINERS: fix a couple issues at media input infrastructure
  docs: media: update maintainer-entry-profile for multi-committers
  docs: media: document media multi-committers rules and process
  docs: media: profile: make it clearer about maintainership duties

 Documentation/driver-api/media/index.rst      |   1 +
 .../media/maintainer-entry-profile.rst        | 252 ++++++++++++----
 .../driver-api/media/media-committer.rst      | 280 ++++++++++++++++++
 .../process/maintainer-pgp-guide.rst          |   2 +
 MAINTAINERS                                   |   3 +-
 5 files changed, 486 insertions(+), 52 deletions(-)
 create mode 100644 Documentation/driver-api/media/media-committer.rst

-- 
2.47.1

[PATCH v4 3/5] docs: media: update maintainer-entry-profile for multi-committers

[Mauro Carvalho Chehab]

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>
Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
---
 .../media/maintainer-entry-profile.rst        | 241 ++++++++++++++----
 1 file changed, 189 insertions(+), 52 deletions(-)

diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
index ffc712a5f632..101f6df6374f 100644
--- a/Documentation/driver-api/media/maintainer-entry-profile.rst
+++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
@@ -4,11 +4,12 @@ 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) covers support for a
+variety of devices: stream capture, analog and digital TV streams, cameras,
+remote controllers, HDMI CEC and media pipeline control.
 
-It covers, mainly, the contents of those directories:
+They consist of developers who work with the Linux Kernel media subsystem,
+which covers, mainly, the contents of those directories:
 
   - drivers/media
   - drivers/staging/media
@@ -27,19 +28,158 @@ 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 files.
 
-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
+Due to the size and wide scope of the media subsystem, the media's
+maintainership model is to have committers that have a broad knowledge of
+a specific aspect of the subsystem. It is the committers' 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.
 
-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).
+Media committers
+----------------
+
+In the media subsystem, there are experienced developers who can push
+patches directly to the development tree. These developers are called
+Media committers and are divided into the following categories:
+
+- Committers:
+    contributors for one or more drivers within the media subsystem.
+    They can push changes to the tree that do not affect the core or ABI.
+
+- Core committers:
+    responsible for part of the media core. They are typically
+    responsible for one or more drivers within the media subsystem, but, besides
+    that, they can also merge patches that change the code common to multiple
+    drivers, including the kernel internal API.
+
+- Subsystem maintainers:
+    responsible for the subsystem as a whole, with access to the
+    entire subsystem.
+
+    API/ABI changes are done via consensus between subsystem maintainers\ [2]_.
+
+    Only subsystem maintainers push changes that affect the userspace
+    API/ABI. Committers may push ABI/API changes on their commits if they
+    have approvals from subsystem maintainers.
+
+All media committers 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.
+
+.. [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.
+
+Media development tree
+----------------------
+
+The main development tree used by the media subsystem is hosted at LinuxTV.org,
+where we also maintain news about the subsystem, wiki pages and a patchwork
+instance where we track patches though their lifetime.
+
+The main tree used by media developers is at:
+
+https://git.linuxtv.org/media.git/
+
+.. _Media development workflow:
+
+Media development workflow
+++++++++++++++++++++++++++
+
+All changes for the media subsystem must 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 committer(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 media.git ``next`` branch;
+
+2. Bug fixes for the current mainline release:
+
+   - baseline shall be the latest mainline release or media.git ``fixes``
+     if changes depend on a fix already merged;
+
+3. Bug fixes for the next mainline release:
+
+   - baseline shall be a prepatch release (-rcX) or media.git ``fixes``
+     if changes depend on a fix already merged. It is also
+     fine to use media.git ``next`` as baseline for such patches if such
+     patches apply cleanly on ``fixes``.
+
+.. 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. Pull request workflow: patches are handled by subsystem maintainers::
+
+     +-------+   +---------+   +-------+   +-----------------------+   +---------+
+     |e-mail |-->|patchwork|-->|pull   |-->|maintainers merge      |-->|media.git|
+     |to LMML|   |picks it |   |request|   |in media-committers.git|   +---------+
+     +-------+   +---------+   +-------+   +-----------------------+
+
+   For this workflow, pull requests can be generated by committers,
+   former committers, subsystem maintainers or by trusted long-time
+   contributors. If you are not in such group, please don't submit
+   pull requests, as they will not be processed.
+
+b. Committers' workflow: patches are handled by media committers::
+
+     +-------+   +---------+   +--------------------+   +-----------+   +---------+
+     |e-mail |-->|patchwork|-->|committers merge at |-->|maintainers|-->|media.git|
+     |to LMML|   |picks it |   |media-committers.git|   |approval   |   +---------+
+     +-------+   +---------+   +--------------------+   +-----------+
+
+On both workflows, all patches shall be properly reviewed at
+linux-media@vger.kernel.org (LMML) before being merged at media-committers.git.
+
+When patches are picked by patchwork and when merged at media-committers,
+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 those two workflows if they
+pass on CI or if there are false-positives in the CI reports.
+
+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 +187,49 @@ 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, 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, thus such
+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 to a few hours
+       for a patch to be picked by patchwork.
+
+.. [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 sign, please read
+Documentation/process/maintainer-pgp-guide.rst.
 
-- HDMI CEC:
-    Hans Verkuil <hverkuil@xs4all.nl>
+Subsystem 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@xs4all.nl>
-
-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> and
+  - Hans Verkuil <hverkuil@xs4all.nl>
 
 Submit Checklist Addendum
 -------------------------
@@ -106,18 +244,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 compilance 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 +269,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
 +++++++++++++++++++++
 
@@ -199,7 +336,7 @@ 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.47.1

[PATCH v4 4/5] docs: media: document media multi-committers rules and process

[Mauro Carvalho Chehab]

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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
---
 Documentation/driver-api/media/index.rst      |   1 +
 .../media/maintainer-entry-profile.rst        |   8 +
 .../driver-api/media/media-committer.rst      | 280 ++++++++++++++++++
 3 files changed, 289 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 101f6df6374f..fa28059f7b3f 100644
--- a/Documentation/driver-api/media/maintainer-entry-profile.rst
+++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
@@ -69,6 +69,9 @@ as described at Documentation/process/index.rst and to the Kernel
 development rules inside the Kernel documentation, including its code of
 conduct.
 
+More details about media commiters' roles and responsibilities can be
+found here: Documentation/driver-api/media/media-committer.rst.
+
 .. [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.
@@ -221,6 +224,11 @@ 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 sign, please read
 Documentation/process/maintainer-pgp-guide.rst.
 
diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
new file mode 100644
index 000000000000..3d0987a8a93b
--- /dev/null
+++ b/Documentation/driver-api/media/media-committer.rst
@@ -0,0 +1,280 @@
+Media committers
+================
+
+Who is a media committer?
+-------------------------
+
+A media committer is a developer 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.
+
+It is a media committer's duty to ensure that their entries in the MAINTAINERS
+file are kept up-to-date, and that submitted patches for files for which
+they are listed as maintainers are timely reviewed on the mailing list,
+ideally not waiting in patchwork as ``New`` for more than one Kernel merge
+cycle, and, if accepted, applying them at the media committer's 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[1].
+
+As such, a media committer is 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).
+
+.. Note::
+
+   1. 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;
+   2. 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.
+
+[1] The Linux Media Community, also called LinuxTV Community, has its primary
+    site at https://linuxtv.org.
+
+    Media committers and developers are reachable via the #linux-media
+    IRC channel at OFTC.
+
+Becoming a media committer
+--------------------------
+
+The most important aspect of volunteering to be a committer 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 committers 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.
+
+So, 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).
+
+Developers that desire to become committers are encouraged to participate
+at the yearly Linux Media Summit, typically co-located with a Linux related
+conference.
+
+If you are doing such tasks and have become a valued developer, an
+existing committer can nominate you to the media subsystem maintainers.
+
+The ultimate responsibility for accepting a nominated committer is up to
+the subsystem's maintainers. The committers must earn a trust relationship
+with all subsystem maintainers, as, by granting you commit rights, they will
+be a part of their maintenance tasks.
+
+Due to that, to become a committer or a core committer, a consensus between
+all subsystem maintainers is required, as they all need to trust a developer
+well enough to be delegated the responsibility to maintain part of the code
+and to properly review patches from third parties, in a timely manner and
+keeping the status of the reviewed code at https://patchwork.linuxtv.org
+updated.
+
+.. 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 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.
+
+Once 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 on 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
+
+   I intend to actively develop the XYZ driver, send fixes to drivers
+   that I can test, optionally reviewing patches and merging trivial
+   fixes in other areas of the 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 hereby declare that I agree with 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 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 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
+   with 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 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.
+
+Core committers
+---------------
+
+As described in Documentation/driver-api/media/maintainer-entry-profile.rst
+a committer may be granted with additional rights to also be able to
+change a core file and/or media subsystem's Kernel API. The extent of
+the core committer's grants will be detailed by the subsystem maintainers
+when they nominate a core committer.
+
+Existing committers may become core committers and vice versa. Such
+decisions will be taken in consensus between the subsystem maintainers.
+
+Media committers rules
+----------------------
+
+Media committers shall do their best efforts to avoid merged 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 subsystem maintainers, specially with regards of the scope of changes
+they may apply directly at the media-committers tree. Such scope can
+change over time on a mutual agreement between media committers and
+maintainers.
+
+As described at :ref:`Media development workflow`, there are workflows.
+For the committers' workflow, the following rules apply:
+
+- Each merged patch shall pass CI tests;
+
+- Media committers shall request reviews from other committers 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 subsystem maintainers as needed.
+
+Patches that do not fall under the committer's workflow criteria will follow
+the pull request workflow as described at :ref:`Media development workflow`.
+
+Only a subsystem maintainer can override such rules.
+
+All media committers shall ensure that patchwork will reflect the current
+status, e.g. patches shall be delegated to the media committer 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 the committer decides not to merge it, then reply by email to patch
+authors, explaining why it is not merged, and patchwork shall be updated
+accordingly with either:
+
+- ``Changes Requested``: if a new revision was requested;
+- ``Rejected``: if the proposed change won't be merged upstream.
+
+.. 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/
+
+Maintaining media committer status
+----------------------------------
+
+A community of committers 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 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 committers,
+the final decision is taken by the subsystem maintainers. As the decision
+to become a media committer comes from a consensus between subsystem
+maintainers, a single subsystem maintainer not trusting the media committer
+anymore is enough to revoke the commit rights.
+
+If a committer 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 committer rights and update MAINTAINERS file entries
+accordingly. If you wish to resume contributing later on, then contact
+the subsystem maintainers to ask if your commit rights can be restored.
+
+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`.
+
+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.47.1

[PATCH v4 5/5] docs: media: profile: make it clearer about maintainership duties

[Mauro Carvalho Chehab]

During the review of the media committer's profile, it was noticed
that the responsibility for timely review patches was not clear:
such review is expected that all developers listed at MAINTAINERS
with the "M:" tag (e.g. "maintainers" on its broad sense).

This is orthogonal of being a media committer or not. Such duty
is implied at:

	Documentation/admin-guide/reporting-issues.rst

and at the MAINTAINERS header, when it says that even when the
status is "odd fixes", the patches will flow in.

So, let make it explicit at the maintainer-entry-profile that
maintainers need to do timely reviews.

Also, while right now our focus is on granting committer rights to
maintainers, the media-committer model may evolve in the future to
accept other committers that don't have such duties.

So, make it clear at the media-committer.rst that the duties
related to reviewing patches from others are for the drivers
they are maintainers as well.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/driver-api/media/maintainer-entry-profile.rst | 5 +++++
 Documentation/driver-api/media/media-committer.rst          | 6 +++---
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
index fa28059f7b3f..87b71f89b1df 100644
--- a/Documentation/driver-api/media/maintainer-entry-profile.rst
+++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
@@ -173,6 +173,11 @@ b. Committers' workflow: patches are handled by media committers::
 On both workflows, all patches shall be properly reviewed at
 linux-media@vger.kernel.org (LMML) before being merged at media-committers.git.
 
+Such patches will be reviewed timely by the maintainers and reviewers as
+listed in the MAINTAINERS file. The subsystem maintainers will follow one of
+the above workflows, e. g. they will either send a pull request or merge
+patches directly at the media-committers tree.
+
 When patches are picked by patchwork and when merged at media-committers,
 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
diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
index 3d0987a8a93b..0bc038a0fdcc 100644
--- a/Documentation/driver-api/media/media-committer.rst
+++ b/Documentation/driver-api/media/media-committer.rst
@@ -90,9 +90,9 @@ be a part of their maintenance tasks.
 Due to that, to become a committer or a core committer, a consensus between
 all subsystem maintainers is required, as they all need to trust a developer
 well enough to be delegated the responsibility to maintain part of the code
-and to properly review patches from third parties, in a timely manner and
-keeping the status of the reviewed code at https://patchwork.linuxtv.org
-updated.
+and to properly review patches from third parties for the drivers that they
+maintain in a timely manner and keeping the status of the patches at
+https://patchwork.linuxtv.org updated.
 
 .. Note::
 
-- 
2.47.1

Re: [PATCH v4 3/5] docs: media: update maintainer-entry-profile for multi-committers

[Laurent Pinchart]

Hi Mauro,

Thank you for the patch.

On Tue, Dec 03, 2024 at 10:35:47AM +0100, Mauro Carvalho Chehab wrote:
> 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>
> Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
> Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> ---
>  .../media/maintainer-entry-profile.rst        | 241 ++++++++++++++----
>  1 file changed, 189 insertions(+), 52 deletions(-)
> 
> diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> index ffc712a5f632..101f6df6374f 100644
> --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> @@ -4,11 +4,12 @@ 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) covers support for a

I think this paragraph really talks about the media subsystem, not the
community. I wouldn't change it.

> +variety of devices: stream capture, analog and digital TV streams, cameras,
> +remote controllers, HDMI CEC and media pipeline control.
>  
> -It covers, mainly, the contents of those directories:
> +They consist of developers who work with the Linux Kernel media subsystem,
> +which covers, mainly, the contents of those directories:

Same here.

>  
>    - drivers/media
>    - drivers/staging/media
> @@ -27,19 +28,158 @@ 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 files.
>  
> -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
> +Due to the size and wide scope of the media subsystem, the media's
> +maintainership model is to have committers that have a broad knowledge of
> +a specific aspect of the subsystem. It is the committers' task to
> +review the patches, providing feedback to users if the patches are

We discussed that reviews are not a committer's duty, but come from
being a driver maintainer, as indicated by the MAINTAINERS file. Is the
mention of "review" here a leftover from previous versions ?

>  following the subsystem rules and are properly using the media kernel and
>  userspace APIs.
>  
> -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).
> +Media committers
> +----------------
> +
> +In the media subsystem, there are experienced developers who can push
> +patches directly to the development tree. These developers are called
> +Media committers and are divided into the following categories:
> +
> +- Committers:
> +    contributors for one or more drivers within the media subsystem.
> +    They can push changes to the tree that do not affect the core or ABI.

a/ABI/ userspace ABI/

> +
> +- Core committers:
> +    responsible for part of the media core. They are typically

This paragraph can be reflowed to 80 columns.

> +    responsible for one or more drivers within the media subsystem, but, besides
> +    that, they can also merge patches that change the code common to multiple

s/the code/code/

> +    drivers, including the kernel internal API.
> +
> +- Subsystem maintainers:
> +    responsible for the subsystem as a whole, with access to the
> +    entire subsystem.

You can reflow this too.

> +
> +    API/ABI changes are done via consensus between subsystem maintainers\ [2]_.
> +
> +    Only subsystem maintainers push changes that affect the userspace
> +    API/ABI. Committers may push ABI/API changes on their commits if they

Is the second mention of "ABI/API" here referring to the in-kernel API
or the userspace API ? If it's the latter, the second sentence
contradicts the first one.

> +    have approvals from subsystem maintainers.
> +
> +All media committers 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.
> +
> +.. [2] Everything that would break backward compatibility with existing
> +       non-kernel code are API/ABI changes. This includes ioctl and sysfs

More than that, backward compatibility can't be broken, that's a kernel
policy. I would drop this note.

> +       interfaces, v4l2 controls, and their behaviors.

s/v4l2/V4L2/

> +
> +Media development tree
> +----------------------
> +
> +The main development tree used by the media subsystem is hosted at LinuxTV.org,
> +where we also maintain news about the subsystem, wiki pages and a patchwork
> +instance where we track patches though their lifetime.
> +
> +The main tree used by media developers is at:
> +
> +https://git.linuxtv.org/media.git/
> +
> +.. _Media development workflow:
> +
> +Media development workflow
> +++++++++++++++++++++++++++
> +
> +All changes for the media subsystem must 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 committer(s). You should use

It's more than wise, let's make it strongly adviced:

Patches should be CC'ed to the appropriate maintainers.

> +``scripts/get_maintainers.pl`` to identify whom else needs to be copied.

s/else //

> +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 media.git ``next`` branch;
> +
> +2. Bug fixes for the current mainline release:
> +
> +   - baseline shall be the latest mainline release or media.git ``fixes``
> +     if changes depend on a fix already merged;
> +
> +3. Bug fixes for the next mainline release:
> +
> +   - baseline shall be a prepatch release (-rcX) or media.git ``fixes``
> +     if changes depend on a fix already merged. It is also
> +     fine to use media.git ``next`` as baseline for such patches if such
> +     patches apply cleanly on ``fixes``.

Why is it fine to use the next branch ? That branch will already contain
lots of changes for the next release. Applying cleanly to fixes is not
a strong enough criteria, fixes must be tested on the fixes branch. I'd
drop the second sentence.

> +
> +.. 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

s/were fixing/fix/

> +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.

This duplicates the first paragraph of this section.

> +
> +Once a patch is submitted, it may follow either one of the following
> +workflows:
> +
> +a. Pull request workflow: patches are handled by subsystem maintainers::
> +
> +     +-------+   +---------+   +-------+   +-----------------------+   +---------+
> +     |e-mail |-->|patchwork|-->|pull   |-->|maintainers merge      |-->|media.git|
> +     |to LMML|   |picks it |   |request|   |in media-committers.git|   +---------+
> +     +-------+   +---------+   +-------+   +-----------------------+
> +
> +   For this workflow, pull requests can be generated by committers,
> +   former committers, subsystem maintainers or by trusted long-time
> +   contributors. If you are not in such group, please don't submit
> +   pull requests, as they will not be processed.

I don't see why we wouldn't process them, but I won't fight on this.

> +
> +b. Committers' workflow: patches are handled by media committers::
> +
> +     +-------+   +---------+   +--------------------+   +-----------+   +---------+
> +     |e-mail |-->|patchwork|-->|committers merge at |-->|maintainers|-->|media.git|
> +     |to LMML|   |picks it |   |media-committers.git|   |approval   |   +---------+
> +     +-------+   +---------+   +--------------------+   +-----------+
> +
> +On both workflows, all patches shall be properly reviewed at
> +linux-media@vger.kernel.org (LMML) before being merged at media-committers.git.
> +
> +When patches are picked by patchwork and when merged at media-committers,
> +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 those two workflows if they
> +pass on CI or if there are false-positives in the CI reports.

"or if all CI issues are false positives"

> +
> +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 +187,49 @@ 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, 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, thus such
> +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 to a few hours
> +       for a patch to be picked by patchwork.
> +
> +.. [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

"Merge request", as opposed to "pull request", usually refers to merge
request submitted on git forges such as github or gitlab. As far as I
know, this is not being discussed as a change to the workflow, and isn't
listed anywhere in our documentation. Do we need to include it here,
can't we talk about pull requests only ?

> +++++++++++++++++++++++++++++++++++++++++++
>  
> -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

I think you mean either "the identity of developers" or "the
authenticity of pull requests".

> +shall be validated by using PGP signing at some moment.

"at the same moment" as what ?

> +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 sign, please read
> +Documentation/process/maintainer-pgp-guide.rst.
>  
> -- HDMI CEC:
> -    Hans Verkuil <hverkuil@xs4all.nl>
> +Subsystem 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@xs4all.nl>
> -
> -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> and
> +  - Hans Verkuil <hverkuil@xs4all.nl>

Nitpicking, I think you can drop the indentation before the list markers. I'd also
insert a blank line just before the list, to make it more readable.

Not nitpicking, https://lore.kernel.org/all/e7a4c286-13ae-4025-b765-ee7055476cf1@xs4all.nl/
should be included in this series.

>  
>  Submit Checklist Addendum
>  -------------------------
> @@ -106,18 +244,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 compilance 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 +269,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
>  +++++++++++++++++++++
>  
> @@ -199,7 +336,7 @@ 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:``,
> 

-- 
Regards,

Laurent Pinchart

Re: [PATCH v4 4/5] docs: media: document media multi-committers rules and process

[Laurent Pinchart]

Hi Mauro,

Thank you for the patch.

On Tue, Dec 03, 2024 at 10:35:48AM +0100, Mauro Carvalho Chehab wrote:
> 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.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
> Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> ---
>  Documentation/driver-api/media/index.rst      |   1 +
>  .../media/maintainer-entry-profile.rst        |   8 +
>  .../driver-api/media/media-committer.rst      | 280 ++++++++++++++++++
>  3 files changed, 289 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 101f6df6374f..fa28059f7b3f 100644
> --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> @@ -69,6 +69,9 @@ as described at Documentation/process/index.rst and to the Kernel
>  development rules inside the Kernel documentation, including its code of
>  conduct.
>  
> +More details about media commiters' roles and responsibilities can be
> +found here: Documentation/driver-api/media/media-committer.rst.
> +
>  .. [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.
> @@ -221,6 +224,11 @@ 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 sign, please read
>  Documentation/process/maintainer-pgp-guide.rst.
>  
> diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
> new file mode 100644
> index 000000000000..3d0987a8a93b
> --- /dev/null
> +++ b/Documentation/driver-api/media/media-committer.rst
> @@ -0,0 +1,280 @@
> +Media committers
> +================
> +
> +Who is a media committer?
> +-------------------------
> +
> +A media committer is a developer 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.

This is a much better definition than in v1, I do like this.

> +
> +It is a media committer's duty to ensure that their entries in the MAINTAINERS
> +file are kept up-to-date, and that submitted patches for files for which
> +they are listed as maintainers are timely reviewed on the mailing list,
> +ideally not waiting in patchwork as ``New`` for more than one Kernel merge
> +cycle, and, if accepted, applying them at the media committer's tree.

This is not a committer's duty. This is related to maintainers, not
committers, and doesn't belong to this document.

> +
> +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

Responsibility, yes, but not as described. The committer's
responsibility is to adhere to the process we define, to minimize the
risk of breakages. It's a committer's responsibility to not push patches
that have not received consensus, and to not bypass CI. It isn't a
committer's responsibility to "advance the Linux media subsystem
development" (especially given that there are often very opposite views
in the community about what this means in practice).

> +is also based on a trust relationship among other committers, maintainers
> +and the Linux Media community[1].
> +
> +As such, a media committer is 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).
> +
> +.. Note::
> +
> +   1. 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;
> +   2. if patches are fixing bugs against already released Kernels, including
> +      the reverts above mentioned, the media committer shall add the needed

s/above mentioned/mentioned above/

> +      tags. Please see :ref:`Media development workflow` for more details.
> +
> +[1] The Linux Media Community, also called LinuxTV Community, has its primary
> +    site at https://linuxtv.org.
> +
> +    Media committers and developers are reachable via the #linux-media
> +    IRC channel at OFTC.

s/at/on/

> +
> +Becoming a media committer
> +--------------------------
> +
> +The most important aspect of volunteering to be a committer is that you have
> +demonstrated the ability to give good code reviews. So we are looking for

Again, that's not what a committer is about. Committer, as the name
strongly implies, is about committing patches.

> +whether or not we think you will be good at doing that.
> +
> +As such, potential committers 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.
> +
> +So, in addition to actually making the code changes, you are basically
> +demonstrating your:
> +
> +- commitment to the project;

What does that mean ?

> +- 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).
> +
> +Developers that desire to become committers are encouraged to participate

s/that/who/

> +at the yearly Linux Media Summit, typically co-located with a Linux related
> +conference.
> +
> +If you are doing such tasks and have become a valued developer, an
> +existing committer can nominate you to the media subsystem maintainers.

All of this sounds so horrible from a community building point of view.
As a newcomer, reading this document, I would be really tempted to run
away from a community that seems very unwelcoming (not to use stronger
words).

> +
> +The ultimate responsibility for accepting a nominated committer is up to
> +the subsystem's maintainers. The committers must earn a trust relationship
> +with all subsystem maintainers, as, by granting you commit rights, they will
> +be a part of their maintenance tasks.

I don't understand the last part of the sentence.

> +
> +Due to that, to become a committer or a core committer, a consensus between
> +all subsystem maintainers is required, as they all need to trust a developer
> +well enough to be delegated the responsibility to maintain part of the code
> +and to properly review patches from third parties, in a timely manner and
> +keeping the status of the reviewed code at https://patchwork.linuxtv.org
> +updated.
> +
> +.. Note::
> +
> +   In order to preserve/protect the developers that could have their commit

s/protect/protect the privacy of/
s/that/who/

> +   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.

Unless you plan a system that puts gag orders in place, people who get
their commit rights denied or removed against their will will be vocal
about it.  The privacy of maintainers is a pipe dream here. A more
transparent process would likely benefit everybody.

> +
> +.. _media-committer-agreement:
> +
> +Media committer's agreement
> +---------------------------
> +
> +Once a nominated committer is accepted by all 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.

Being "responsible for an area" of the subsystem is maintainership
duties, it's not about committers.

> +
> +Once 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 on 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
> +
> +   I intend to actively develop the XYZ driver, send fixes to drivers
> +   that I can test, optionally reviewing patches and merging trivial
> +   fixes in other areas of the 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 hereby declare that I agree with the Kernel development rules described at:

Dropping "hereby " would make it sound a bit less like a forced
confession obtained by torture.

> +
> +   https://www.kernel.org/doc/html/latest/driver-api/media/media-committer.rst
> +
> +   and to the Linux Kernel development process rules.
> +
> +   I agree to 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 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
> +   with 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 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;

Make this more than a note, it's fundamental to agreeing implicitly to
process changes as listed above.

> +   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

s/specially/especially/

> +      contents under Documentation/process and for trivial typo fixes.
> +
> +Core committers
> +---------------
> +
> +As described in Documentation/driver-api/media/maintainer-entry-profile.rst
> +a committer may be granted with additional rights to also be able to
> +change a core file and/or media subsystem's Kernel API. The extent of
> +the core committer's grants will be detailed by the subsystem maintainers
> +when they nominate a core committer.
> +
> +Existing committers may become core committers and vice versa. Such
> +decisions will be taken in consensus between the subsystem maintainers.
> +
> +Media committers rules
> +----------------------
> +
> +Media committers shall do their best efforts to avoid merged patches that

s/merged/merging/

> +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 subsystem maintainers, specially with regards of the scope of changes
> +they may apply directly at the media-committers tree. Such scope can
> +change over time on a mutual agreement between media committers and
> +maintainers.
> +
> +As described at :ref:`Media development workflow`, there are workflows.
> +For the committers' workflow, the following rules apply:
> +
> +- Each merged patch shall pass CI tests;
> +
> +- Media committers shall request reviews from other committers 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 subsystem maintainers as needed.
> +
> +Patches that do not fall under the committer's workflow criteria will follow
> +the pull request workflow as described at :ref:`Media development workflow`.
> +
> +Only a subsystem maintainer can override such rules.
> +
> +All media committers shall ensure that patchwork will reflect the current
> +status, e.g. patches shall be delegated to the media committer 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.

Not something to address here, but I've always found it confusing that
patches that are accepted but not merged in your tree yet are supposed
to be marked as "Under review". "Accepted" would be a more natural state
of them, and we could introduce a "Merged" state for patches that are
merged.

> +- ``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.

- ``Not Applicable``: Used for patch series that are not meant to be
  merged through the media.git tree. This is mostly used for patches
  that are cross-posted to the linux-media mailing list and meant to be
  merged through another tree (e.g. DRM, dmabuf, device tree sources,
  ...).

> +
> +If the committer decides not to merge it, then reply by email to patch
> +authors, explaining why it is not merged, and patchwork shall be updated
> +accordingly with either:
> +
> +- ``Changes Requested``: if a new revision was requested;
> +- ``Rejected``: if the proposed change won't be merged upstream.
> +
> +.. 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/
> +
> +Maintaining media committer status
> +----------------------------------
> +
> +A community of committers 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 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 committers,
> +the final decision is taken by the subsystem maintainers. As the decision
> +to become a media committer comes from a consensus between subsystem
> +maintainers, a single subsystem maintainer not trusting the media committer
> +anymore is enough to revoke the commit rights.
> +
> +If a committer 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 committer rights and update MAINTAINERS file entries
> +accordingly. If you wish to resume contributing later on, then contact
> +the subsystem maintainers to ask if your commit rights can be restored.
> +
> +A previous committer that had their commit rights revoked can keep

s/that/who/

> +contributing to the subsystem via the pull request workflow as documented
> +at the :ref:`Media development workflow`.
> +
> +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/>`_.
> +

-- 
Regards,

Laurent Pinchart

Re: [PATCH v4 3/5] docs: media: update maintainer-entry-profile for multi-committers

[Hans Verkuil]

On 12/3/24 10:35, Mauro Carvalho Chehab wrote:
> 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>
> Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
> Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> ---
>  .../media/maintainer-entry-profile.rst        | 241 ++++++++++++++----
>  1 file changed, 189 insertions(+), 52 deletions(-)
> 
> diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> index ffc712a5f632..101f6df6374f 100644
> --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> @@ -4,11 +4,12 @@ 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) covers support for a
> +variety of devices: stream capture, analog and digital TV streams, cameras,
> +remote controllers, HDMI CEC and media pipeline control.
>  
> -It covers, mainly, the contents of those directories:
> +They consist of developers who work with the Linux Kernel media subsystem,
> +which covers, mainly, the contents of those directories:
>  
>    - drivers/media
>    - drivers/staging/media
> @@ -27,19 +28,158 @@ 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 files.
>  
> -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
> +Due to the size and wide scope of the media subsystem, the media's
> +maintainership model is to have committers that have a broad knowledge of
> +a specific aspect of the subsystem. It is the committers' 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.
>  
> -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).
> +Media committers
> +----------------
> +
> +In the media subsystem, there are experienced developers who can push
> +patches directly to the development tree. These developers are called
> +Media committers and are divided into the following categories:
> +
> +- Committers:
> +    contributors for one or more drivers within the media subsystem.
> +    They can push changes to the tree that do not affect the core or ABI.
> +
> +- Core committers:
> +    responsible for part of the media core. They are typically
> +    responsible for one or more drivers within the media subsystem, but, besides
> +    that, they can also merge patches that change the code common to multiple
> +    drivers, including the kernel internal API.
> +
> +- Subsystem maintainers:
> +    responsible for the subsystem as a whole, with access to the
> +    entire subsystem.
> +
> +    API/ABI changes are done via consensus between subsystem maintainers\ [2]_.
> +
> +    Only subsystem maintainers push changes that affect the userspace
> +    API/ABI. Committers may push ABI/API changes on their commits if they
> +    have approvals from subsystem maintainers.
> +
> +All media committers 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.
> +
> +.. [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.
> +
> +Media development tree
> +----------------------
> +
> +The main development tree used by the media subsystem is hosted at LinuxTV.org,
> +where we also maintain news about the subsystem, wiki pages and a patchwork
> +instance where we track patches though their lifetime.
> +
> +The main tree used by media developers is at:
> +
> +https://git.linuxtv.org/media.git/
> +
> +.. _Media development workflow:
> +
> +Media development workflow
> +++++++++++++++++++++++++++
> +
> +All changes for the media subsystem must 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 committer(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 media.git ``next`` branch;
> +
> +2. Bug fixes for the current mainline release:
> +
> +   - baseline shall be the latest mainline release or media.git ``fixes``
> +     if changes depend on a fix already merged;
> +
> +3. Bug fixes for the next mainline release:
> +
> +   - baseline shall be a prepatch release (-rcX) or media.git ``fixes``
> +     if changes depend on a fix already merged. It is also
> +     fine to use media.git ``next`` as baseline for such patches if such
> +     patches apply cleanly on ``fixes``.

Much better, thank you!

> +
> +.. 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. Pull request workflow: patches are handled by subsystem maintainers::
> +
> +     +-------+   +---------+   +-------+   +-----------------------+   +---------+
> +     |e-mail |-->|patchwork|-->|pull   |-->|maintainers merge      |-->|media.git|
> +     |to LMML|   |picks it |   |request|   |in media-committers.git|   +---------+
> +     +-------+   +---------+   +-------+   +-----------------------+
> +
> +   For this workflow, pull requests can be generated by committers,
> +   former committers, subsystem maintainers or by trusted long-time
> +   contributors. If you are not in such group, please don't submit
> +   pull requests, as they will not be processed.
> +
> +b. Committers' workflow: patches are handled by media committers::
> +
> +     +-------+   +---------+   +--------------------+   +-----------+   +---------+
> +     |e-mail |-->|patchwork|-->|committers merge at |-->|maintainers|-->|media.git|
> +     |to LMML|   |picks it |   |media-committers.git|   |approval   |   +---------+
> +     +-------+   +---------+   +--------------------+   +-----------+
> +
> +On both workflows, all patches shall be properly reviewed at
> +linux-media@vger.kernel.org (LMML) before being merged at media-committers.git.
> +
> +When patches are picked by patchwork and when merged at media-committers,
> +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 those two workflows if they
> +pass on CI or if there are false-positives in the CI reports.
> +
> +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 +187,49 @@ 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, 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, thus such
> +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 to a few hours
> +       for a patch to be picked by patchwork.
> +
> +.. [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.

"at some moment" is rather vague, but I think that as we try out the procedure
and get practical feedback, then this can be improved.

> +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 sign, please read

sign -> signing

> +Documentation/process/maintainer-pgp-guide.rst.
>  
> -- HDMI CEC:
> -    Hans Verkuil <hverkuil@xs4all.nl>
> +Subsystem 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@xs4all.nl>
> -
> -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> and
> +  - Hans Verkuil <hverkuil@xs4all.nl>
>  
>  Submit Checklist Addendum
>  -------------------------
> @@ -106,18 +244,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 compilance 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 +269,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
>  +++++++++++++++++++++
>  
> @@ -199,7 +336,7 @@ 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:``,

Looks good to me!

Regards,

	Hans

Re: [PATCH v4 4/5] docs: media: document media multi-committers rules and process

[Hans Verkuil]

On 12/3/24 10:35, Mauro Carvalho Chehab wrote:
> 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.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
> Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> ---
>  Documentation/driver-api/media/index.rst      |   1 +
>  .../media/maintainer-entry-profile.rst        |   8 +
>  .../driver-api/media/media-committer.rst      | 280 ++++++++++++++++++
>  3 files changed, 289 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 101f6df6374f..fa28059f7b3f 100644
> --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> @@ -69,6 +69,9 @@ as described at Documentation/process/index.rst and to the Kernel
>  development rules inside the Kernel documentation, including its code of
>  conduct.
>  
> +More details about media commiters' roles and responsibilities can be

commiters -> committers

> +found here: Documentation/driver-api/media/media-committer.rst.
> +
>  .. [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.
> @@ -221,6 +224,11 @@ 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 sign, please read
>  Documentation/process/maintainer-pgp-guide.rst.
>  
> diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
> new file mode 100644
> index 000000000000..3d0987a8a93b
> --- /dev/null
> +++ b/Documentation/driver-api/media/media-committer.rst
> @@ -0,0 +1,280 @@
> +Media committers
> +================
> +
> +Who is a media committer?
> +-------------------------
> +
> +A media committer is a developer 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.
> +
> +It is a media committer's duty to ensure that their entries in the MAINTAINERS
> +file are kept up-to-date, and that submitted patches for files for which
> +they are listed as maintainers are timely reviewed on the mailing list,
> +ideally not waiting in patchwork as ``New`` for more than one Kernel merge
> +cycle, and, if accepted, applying them at the media committer's 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[1].
> +
> +As such, a media committer is 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).
> +
> +.. Note::
> +
> +   1. 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;
> +   2. 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.
> +
> +[1] The Linux Media Community, also called LinuxTV Community, has its primary
> +    site at https://linuxtv.org.
> +
> +    Media committers and developers are reachable via the #linux-media
> +    IRC channel at OFTC.

I think this paragraph is new, since I can't remember seeing it before.

I'm not sure about this. First of all, the main communication is through
the linux-media mailinglist, so I would mention that rather than the IRC
channel. I also think it is better to point to linuxtv.org for the IRC
information (if we want that) since that is easier to keep up to date
with the IRC details than this document.

> +
> +Becoming a media committer
> +--------------------------
> +
> +The most important aspect of volunteering to be a committer 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 committers 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.
> +
> +So, 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).
> +
> +Developers that desire to become committers are encouraged to participate
> +at the yearly Linux Media Summit, typically co-located with a Linux related
> +conference.
> +
> +If you are doing such tasks and have become a valued developer, an
> +existing committer can nominate you to the media subsystem maintainers.
> +
> +The ultimate responsibility for accepting a nominated committer is up to
> +the subsystem's maintainers. The committers must earn a trust relationship
> +with all subsystem maintainers, as, by granting you commit rights, they will
> +be a part of their maintenance tasks.
> +
> +Due to that, to become a committer or a core committer, a consensus between
> +all subsystem maintainers is required, as they all need to trust a developer
> +well enough to be delegated the responsibility to maintain part of the code
> +and to properly review patches from third parties, in a timely manner and
> +keeping the status of the reviewed code at https://patchwork.linuxtv.org
> +updated.
> +
> +.. 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 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.
> +
> +Once 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 on 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
> +
> +   I intend to actively develop the XYZ driver, send fixes to drivers
> +   that I can test, optionally reviewing patches and merging trivial
> +   fixes in other areas of the 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 hereby declare that I agree with 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 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 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
> +   with 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 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.
> +
> +Core committers
> +---------------
> +
> +As described in Documentation/driver-api/media/maintainer-entry-profile.rst
> +a committer may be granted with additional rights to also be able to
> +change a core file and/or media subsystem's Kernel API. The extent of
> +the core committer's grants will be detailed by the subsystem maintainers
> +when they nominate a core committer.

I think this last sentence should be dropped. First of all, this isn't enforceable
by CI tests, and secondly, core changes need to be acked by at least one other core
committer anyway. It might be that that core committer wants to become (co-)maintainer
of a core framework, but that's something that goes into the MAINTAINERS file and has
nothing to do with the commit rights.

Also, it's good if core committers become active in core frameworks that they are
not familiar with if there is a need. The more people learn about how they work,
the better.

And if the core committer rights are abused, then we can always revoke those rights and
revert the changes.

> +
> +Existing committers may become core committers and vice versa. Such
> +decisions will be taken in consensus between the subsystem maintainers.
> +
> +Media committers rules
> +----------------------
> +
> +Media committers shall do their best efforts to avoid merged 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 subsystem maintainers, specially with regards of the scope of changes
> +they may apply directly at the media-committers tree. Such scope can
> +change over time on a mutual agreement between media committers and
> +maintainers.
> +
> +As described at :ref:`Media development workflow`, there are workflows.
> +For the committers' workflow, the following rules apply:
> +
> +- Each merged patch shall pass CI tests;
> +
> +- Media committers shall request reviews from other committers 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 subsystem maintainers as needed.
> +
> +Patches that do not fall under the committer's workflow criteria will follow
> +the pull request workflow as described at :ref:`Media development workflow`.
> +
> +Only a subsystem maintainer can override such rules.
> +
> +All media committers shall ensure that patchwork will reflect the current
> +status, e.g. patches shall be delegated to the media committer 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 the committer decides not to merge it, then reply by email to patch
> +authors, explaining why it is not merged, and patchwork shall be updated
> +accordingly with either:
> +
> +- ``Changes Requested``: if a new revision was requested;
> +- ``Rejected``: if the proposed change won't be merged upstream.
> +
> +.. 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/
> +
> +Maintaining media committer status
> +----------------------------------
> +
> +A community of committers 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 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 committers,
> +the final decision is taken by the subsystem maintainers. As the decision
> +to become a media committer comes from a consensus between subsystem
> +maintainers, a single subsystem maintainer not trusting the media committer
> +anymore is enough to revoke the commit rights.
> +
> +If a committer 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 committer rights and update MAINTAINERS file entries
> +accordingly. If you wish to resume contributing later on, then contact
> +the subsystem maintainers to ask if your commit rights can be restored.
> +
> +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`.
> +
> +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/>`_.
> +

Regards,

	Hans

Re: [PATCH v4 5/5] docs: media: profile: make it clearer about maintainership duties

[Hans Verkuil]

On 12/3/24 10:35, Mauro Carvalho Chehab wrote:
> During the review of the media committer's profile, it was noticed
> that the responsibility for timely review patches was not clear:
> such review is expected that all developers listed at MAINTAINERS
> with the "M:" tag (e.g. "maintainers" on its broad sense).
> 
> This is orthogonal of being a media committer or not. Such duty
> is implied at:
> 
> 	Documentation/admin-guide/reporting-issues.rst
> 
> and at the MAINTAINERS header, when it says that even when the
> status is "odd fixes", the patches will flow in.
> 
> So, let make it explicit at the maintainer-entry-profile that
> maintainers need to do timely reviews.
> 
> Also, while right now our focus is on granting committer rights to
> maintainers, the media-committer model may evolve in the future to
> accept other committers that don't have such duties.
> 
> So, make it clear at the media-committer.rst that the duties
> related to reviewing patches from others are for the drivers
> they are maintainers as well.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/driver-api/media/maintainer-entry-profile.rst | 5 +++++
>  Documentation/driver-api/media/media-committer.rst          | 6 +++---
>  2 files changed, 8 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> index fa28059f7b3f..87b71f89b1df 100644
> --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> @@ -173,6 +173,11 @@ b. Committers' workflow: patches are handled by media committers::
>  On both workflows, all patches shall be properly reviewed at
>  linux-media@vger.kernel.org (LMML) before being merged at media-committers.git.
>  
> +Such patches will be reviewed timely by the maintainers and reviewers as
> +listed in the MAINTAINERS file. The subsystem maintainers will follow one of
> +the above workflows, e. g. they will either send a pull request or merge
> +patches directly at the media-committers tree.
> +
>  When patches are picked by patchwork and when merged at media-committers,
>  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
> diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
> index 3d0987a8a93b..0bc038a0fdcc 100644
> --- a/Documentation/driver-api/media/media-committer.rst
> +++ b/Documentation/driver-api/media/media-committer.rst
> @@ -90,9 +90,9 @@ be a part of their maintenance tasks.
>  Due to that, to become a committer or a core committer, a consensus between
>  all subsystem maintainers is required, as they all need to trust a developer
>  well enough to be delegated the responsibility to maintain part of the code
> -and to properly review patches from third parties, in a timely manner and
> -keeping the status of the reviewed code at https://patchwork.linuxtv.org
> -updated.
> +and to properly review patches from third parties for the drivers that they
> +maintain in a timely manner and keeping the status of the patches at
> +https://patchwork.linuxtv.org updated.
>  
>  .. Note::
>  

Looks OK to me, but I thought this was supposed to be folded into the 3/5 and 4/5 patches?

Regards,

	Hans

Re: [PATCH v4 5/5] docs: media: profile: make it clearer about maintainership duties

[Mauro Carvalho Chehab]

Em Wed, 4 Dec 2024 13:11:45 +0100
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 12/3/24 10:35, Mauro Carvalho Chehab wrote:
> > During the review of the media committer's profile, it was noticed
> > that the responsibility for timely review patches was not clear:
> > such review is expected that all developers listed at MAINTAINERS
> > with the "M:" tag (e.g. "maintainers" on its broad sense).
> > 
> > This is orthogonal of being a media committer or not. Such duty
> > is implied at:
> > 
> > 	Documentation/admin-guide/reporting-issues.rst
> > 
> > and at the MAINTAINERS header, when it says that even when the
> > status is "odd fixes", the patches will flow in.
> > 
> > So, let make it explicit at the maintainer-entry-profile that
> > maintainers need to do timely reviews.
> > 
> > Also, while right now our focus is on granting committer rights to
> > maintainers, the media-committer model may evolve in the future to
> > accept other committers that don't have such duties.
> > 
> > So, make it clear at the media-committer.rst that the duties
> > related to reviewing patches from others are for the drivers
> > they are maintainers as well.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  Documentation/driver-api/media/maintainer-entry-profile.rst | 5 +++++
> >  Documentation/driver-api/media/media-committer.rst          | 6 +++---
> >  2 files changed, 8 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > index fa28059f7b3f..87b71f89b1df 100644
> > --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> > +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > @@ -173,6 +173,11 @@ b. Committers' workflow: patches are handled by media committers::
> >  On both workflows, all patches shall be properly reviewed at
> >  linux-media@vger.kernel.org (LMML) before being merged at media-committers.git.
> >  
> > +Such patches will be reviewed timely by the maintainers and reviewers as
> > +listed in the MAINTAINERS file. The subsystem maintainers will follow one of
> > +the above workflows, e. g. they will either send a pull request or merge
> > +patches directly at the media-committers tree.
> > +
> >  When patches are picked by patchwork and when merged at media-committers,
> >  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
> > diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
> > index 3d0987a8a93b..0bc038a0fdcc 100644
> > --- a/Documentation/driver-api/media/media-committer.rst
> > +++ b/Documentation/driver-api/media/media-committer.rst
> > @@ -90,9 +90,9 @@ be a part of their maintenance tasks.
> >  Due to that, to become a committer or a core committer, a consensus between
> >  all subsystem maintainers is required, as they all need to trust a developer
> >  well enough to be delegated the responsibility to maintain part of the code
> > -and to properly review patches from third parties, in a timely manner and
> > -keeping the status of the reviewed code at https://patchwork.linuxtv.org
> > -updated.
> > +and to properly review patches from third parties for the drivers that they
> > +maintain in a timely manner and keeping the status of the patches at
> > +https://patchwork.linuxtv.org updated.
> >  
> >  .. Note::
> >    
> 
> Looks OK to me, but I thought this was supposed to be folded into the 3/5 and 4/5 patches?

I'll fold it once you and Ricardo gives the same review/Sob as marked on 3/5 and 4/5.


Thanks,
Mauro

Re: [PATCH v4 5/5] docs: media: profile: make it clearer about maintainership duties

[Ricardo Ribalda Delgado]

On Wed, Dec 4, 2024 at 2:16 PM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Em Wed, 4 Dec 2024 13:11:45 +0100
> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
>
> > On 12/3/24 10:35, Mauro Carvalho Chehab wrote:
> > > During the review of the media committer's profile, it was noticed
> > > that the responsibility for timely review patches was not clear:
> > > such review is expected that all developers listed at MAINTAINERS
> > > with the "M:" tag (e.g. "maintainers" on its broad sense).
> > >
> > > This is orthogonal of being a media committer or not. Such duty
> > > is implied at:
> > >
> > >     Documentation/admin-guide/reporting-issues.rst
> > >
> > > and at the MAINTAINERS header, when it says that even when the
> > > status is "odd fixes", the patches will flow in.
> > >
> > > So, let make it explicit at the maintainer-entry-profile that
> > > maintainers need to do timely reviews.
> > >
> > > Also, while right now our focus is on granting committer rights to
> > > maintainers, the media-committer model may evolve in the future to
> > > accept other committers that don't have such duties.
> > >
> > > So, make it clear at the media-committer.rst that the duties
> > > related to reviewing patches from others are for the drivers
> > > they are maintainers as well.
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> > > ---
> > >  Documentation/driver-api/media/maintainer-entry-profile.rst | 5 +++++
> > >  Documentation/driver-api/media/media-committer.rst          | 6 +++---
> > >  2 files changed, 8 insertions(+), 3 deletions(-)
> > >
> > > diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > > index fa28059f7b3f..87b71f89b1df 100644
> > > --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> > > +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > > @@ -173,6 +173,11 @@ b. Committers' workflow: patches are handled by media committers::
> > >  On both workflows, all patches shall be properly reviewed at
> > >  linux-media@vger.kernel.org (LMML) before being merged at media-committers.git.
> > >
> > > +Such patches will be reviewed timely by the maintainers and reviewers as
> > > +listed in the MAINTAINERS file. The subsystem maintainers will follow one of
> > > +the above workflows, e. g. they will either send a pull request or merge
> > > +patches directly at the media-committers tree.
> > > +
> > >  When patches are picked by patchwork and when merged at media-committers,
> > >  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
> > > diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
> > > index 3d0987a8a93b..0bc038a0fdcc 100644
> > > --- a/Documentation/driver-api/media/media-committer.rst
> > > +++ b/Documentation/driver-api/media/media-committer.rst
> > > @@ -90,9 +90,9 @@ be a part of their maintenance tasks.
> > >  Due to that, to become a committer or a core committer, a consensus between
> > >  all subsystem maintainers is required, as they all need to trust a developer
> > >  well enough to be delegated the responsibility to maintain part of the code
> > > -and to properly review patches from third parties, in a timely manner and
> > > -keeping the status of the reviewed code at https://patchwork.linuxtv.org
> > > -updated.
> > > +and to properly review patches from third parties for the drivers that they
> > > +maintain in a timely manner and keeping the status of the patches at
> > > +https://patchwork.linuxtv.org updated.
> > >
> > >  .. Note::
> > >
> >
> > Looks OK to me, but I thought this was supposed to be folded into the 3/5 and 4/5 patches?
>
> I'll fold it once you and Ricardo gives the same review/Sob as marked on 3/5 and 4/5.
>
>
> Thanks,
> Mauro
>


-- 
Ricardo Ribalda

Re: [PATCH v4 5/5] docs: media: profile: make it clearer about maintainership duties

[Hans Verkuil]

On 12/4/24 13:51, Mauro Carvalho Chehab wrote:
> Em Wed, 4 Dec 2024 13:11:45 +0100
> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> 
>> On 12/3/24 10:35, Mauro Carvalho Chehab wrote:
>>> During the review of the media committer's profile, it was noticed
>>> that the responsibility for timely review patches was not clear:
>>> such review is expected that all developers listed at MAINTAINERS
>>> with the "M:" tag (e.g. "maintainers" on its broad sense).
>>>
>>> This is orthogonal of being a media committer or not. Such duty
>>> is implied at:
>>>
>>> 	Documentation/admin-guide/reporting-issues.rst
>>>
>>> and at the MAINTAINERS header, when it says that even when the
>>> status is "odd fixes", the patches will flow in.
>>>
>>> So, let make it explicit at the maintainer-entry-profile that
>>> maintainers need to do timely reviews.
>>>
>>> Also, while right now our focus is on granting committer rights to
>>> maintainers, the media-committer model may evolve in the future to
>>> accept other committers that don't have such duties.
>>>
>>> So, make it clear at the media-committer.rst that the duties
>>> related to reviewing patches from others are for the drivers
>>> they are maintainers as well.
>>>
>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>>> ---
>>>  Documentation/driver-api/media/maintainer-entry-profile.rst | 5 +++++
>>>  Documentation/driver-api/media/media-committer.rst          | 6 +++---
>>>  2 files changed, 8 insertions(+), 3 deletions(-)
>>>
>>> diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
>>> index fa28059f7b3f..87b71f89b1df 100644
>>> --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
>>> +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
>>> @@ -173,6 +173,11 @@ b. Committers' workflow: patches are handled by media committers::
>>>  On both workflows, all patches shall be properly reviewed at
>>>  linux-media@vger.kernel.org (LMML) before being merged at media-committers.git.
>>>  
>>> +Such patches will be reviewed timely by the maintainers and reviewers as
>>> +listed in the MAINTAINERS file. The subsystem maintainers will follow one of
>>> +the above workflows, e. g. they will either send a pull request or merge
>>> +patches directly at the media-committers tree.
>>> +
>>>  When patches are picked by patchwork and when merged at media-committers,
>>>  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
>>> diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
>>> index 3d0987a8a93b..0bc038a0fdcc 100644
>>> --- a/Documentation/driver-api/media/media-committer.rst
>>> +++ b/Documentation/driver-api/media/media-committer.rst
>>> @@ -90,9 +90,9 @@ be a part of their maintenance tasks.
>>>  Due to that, to become a committer or a core committer, a consensus between
>>>  all subsystem maintainers is required, as they all need to trust a developer
>>>  well enough to be delegated the responsibility to maintain part of the code
>>> -and to properly review patches from third parties, in a timely manner and
>>> -keeping the status of the reviewed code at https://patchwork.linuxtv.org
>>> -updated.
>>> +and to properly review patches from third parties for the drivers that they
>>> +maintain in a timely manner and keeping the status of the patches at
>>> +https://patchwork.linuxtv.org updated.
>>>  
>>>  .. Note::
>>>    
>>
>> Looks OK to me, but I thought this was supposed to be folded into the 3/5 and 4/5 patches?

For the record:

Reviewed-by: Hans Verkuil <hverkuil@xs4all.nl>

You can also add that for patches 1 and 2 (I found them in lore.kernel.org).

Regards,

	Hans

> 
> I'll fold it once you and Ricardo gives the same review/Sob as marked on 3/5 and 4/5.
> 
> 
> Thanks,
> Mauro

[PATCH v4 1/5] docs: maintainer-pgp-guide.rst: add a reference for kernel.org sign

[Mauro Carvalho Chehab]

The media profile documentation will point to kernel.org sign.
Add a link to it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---

Patch resent, as linux-media was not on its Cc list.


 Documentation/process/maintainer-pgp-guide.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst
index f5277993b195..795ef8d89271 100644
--- a/Documentation/process/maintainer-pgp-guide.rst
+++ b/Documentation/process/maintainer-pgp-guide.rst
@@ -903,6 +903,8 @@ the new default in GnuPG v2). To set it, add (or modify) the
 
     trust-model tofu+pgp
 
+.. _kernel_org_trust_repository:
+
 Using the kernel.org web of trust repository
 --------------------------------------------
 
-- 
2.47.1

[PATCH v4 2/5] MAINTAINERS: fix a couple issues at media input infrastructure

[Mauro Carvalho Chehab]

The media input infrastructure is missing a record for our maintainer's
entry profile. Also, patchwork link is wrong.

Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---

Patch resent, as linux-media was not on its Cc list.


 MAINTAINERS | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index 1e930c7a58b1..264c0caec2df 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14510,8 +14510,9 @@ MEDIA INPUT INFRASTRUCTURE (V4L/DVB)
 M:	Mauro Carvalho Chehab <mchehab@kernel.org>
 L:	linux-media@vger.kernel.org
 S:	Maintained
+P:	Documentation/driver-api/media/maintainer-entry-profile.rst
 W:	https://linuxtv.org
-Q:	http://patchwork.kernel.org/project/linux-media/list/
+Q:	https://patchwork.linuxtv.org/project/linux-media/list/
 T:	git git://linuxtv.org/media.git
 F:	Documentation/admin-guide/media/
 F:	Documentation/devicetree/bindings/media/
-- 
2.47.1

[PATCH v4 2/5] MAINTAINERS: fix a couple issues at media input infrastructure

[Mauro Carvalho Chehab]

The media input infrastructure is missing a record for our maintainer's
entry profile. Also, patchwork link is wrong.

Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---

Patch resent a second time, as reference msg ID got wrong.

 MAINTAINERS | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index 1e930c7a58b1..264c0caec2df 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14510,8 +14510,9 @@ MEDIA INPUT INFRASTRUCTURE (V4L/DVB)
 M:	Mauro Carvalho Chehab <mchehab@kernel.org>
 L:	linux-media@vger.kernel.org
 S:	Maintained
+P:	Documentation/driver-api/media/maintainer-entry-profile.rst
 W:	https://linuxtv.org
-Q:	http://patchwork.kernel.org/project/linux-media/list/
+Q:	https://patchwork.linuxtv.org/project/linux-media/list/
 T:	git git://linuxtv.org/media.git
 F:	Documentation/admin-guide/media/
 F:	Documentation/devicetree/bindings/media/
-- 
2.47.1

Re: [PATCH v4 4/5] docs: media: document media multi-committers rules and process

[Hans Verkuil]

On 03/12/2024 13:29, Laurent Pinchart wrote:
> Hi Mauro,
> 
> Thank you for the patch.
> 
> On Tue, Dec 03, 2024 at 10:35:48AM +0100, Mauro Carvalho Chehab wrote:
>> 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.
>>
>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>> Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
>> Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
>> ---
>>  Documentation/driver-api/media/index.rst      |   1 +
>>  .../media/maintainer-entry-profile.rst        |   8 +
>>  .../driver-api/media/media-committer.rst      | 280 ++++++++++++++++++
>>  3 files changed, 289 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 101f6df6374f..fa28059f7b3f 100644
>> --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
>> +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
>> @@ -69,6 +69,9 @@ as described at Documentation/process/index.rst and to the Kernel
>>  development rules inside the Kernel documentation, including its code of
>>  conduct.
>>  
>> +More details about media commiters' roles and responsibilities can be
>> +found here: Documentation/driver-api/media/media-committer.rst.
>> +
>>  .. [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.
>> @@ -221,6 +224,11 @@ 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 sign, please read
>>  Documentation/process/maintainer-pgp-guide.rst.
>>  
>> diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
>> new file mode 100644
>> index 000000000000..3d0987a8a93b
>> --- /dev/null
>> +++ b/Documentation/driver-api/media/media-committer.rst
>> @@ -0,0 +1,280 @@
>> +Media committers
>> +================
>> +
>> +Who is a media committer?
>> +-------------------------
>> +
>> +A media committer is a developer 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.
> 
> This is a much better definition than in v1, I do like this.
> 
>> +
>> +It is a media committer's duty to ensure that their entries in the MAINTAINERS
>> +file are kept up-to-date, and that submitted patches for files for which
>> +they are listed as maintainers are timely reviewed on the mailing list,
>> +ideally not waiting in patchwork as ``New`` for more than one Kernel merge
>> +cycle, and, if accepted, applying them at the media committer's tree.
> 
> This is not a committer's duty. This is related to maintainers, not
> committers, and doesn't belong to this document.

True. This really belongs to the previous patch, that's where we talk about
the maintainer's duties and expectations.

> 
>> +
>> +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
> 
> Responsibility, yes, but not as described. The committer's
> responsibility is to adhere to the process we define, to minimize the
> risk of breakages. It's a committer's responsibility to not push patches
> that have not received consensus, and to not bypass CI. It isn't a
> committer's responsibility to "advance the Linux media subsystem
> development" (especially given that there are often very opposite views
> in the community about what this means in practice).

I think we can just drop the "and want to advance its development" part.
It's too vague in any case.

> 
>> +is also based on a trust relationship among other committers, maintainers
>> +and the Linux Media community[1].
>> +
>> +As such, a media committer is 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).
>> +
>> +.. Note::
>> +
>> +   1. 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;
>> +   2. if patches are fixing bugs against already released Kernels, including
>> +      the reverts above mentioned, the media committer shall add the needed
> 
> s/above mentioned/mentioned above/
> 
>> +      tags. Please see :ref:`Media development workflow` for more details.
>> +
>> +[1] The Linux Media Community, also called LinuxTV Community, has its primary
>> +    site at https://linuxtv.org.
>> +
>> +    Media committers and developers are reachable via the #linux-media
>> +    IRC channel at OFTC.
> 
> s/at/on/
> 
>> +
>> +Becoming a media committer
>> +--------------------------
>> +
>> +The most important aspect of volunteering to be a committer is that you have
>> +demonstrated the ability to give good code reviews. So we are looking for
> 
> Again, that's not what a committer is about. Committer, as the name
> strongly implies, is about committing patches.

I disagree with that. Reviewing patches is very much part of a committer's life.
You cannot just commit patches from someone else without looking at them.
If you can't do a good code review, then you shouldn't be given commit rights.
It just wouldn't work.

> 
>> +whether or not we think you will be good at doing that.
>> +
>> +As such, potential committers 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.
>> +
>> +So, in addition to actually making the code changes, you are basically
>> +demonstrating your:
>> +
>> +- commitment to the project;
> 
> What does that mean ?

I think this comes down to being able and willing to put in the time.
How about this:

- commitment to the project, i.e. being able and willing to put in the
time required;

> 
>> +- 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).
>> +
>> +Developers that desire to become committers are encouraged to participate
> 
> s/that/who/
> 
>> +at the yearly Linux Media Summit, typically co-located with a Linux related
>> +conference.
>> +
>> +If you are doing such tasks and have become a valued developer, an
>> +existing committer can nominate you to the media subsystem maintainers.
> 
> All of this sounds so horrible from a community building point of view.
> As a newcomer, reading this document, I would be really tempted to run
> away from a community that seems very unwelcoming (not to use stronger
> words).

I know, but right now we are just trying to get something in so we can kick off
the multi-committer process.

> 
>> +
>> +The ultimate responsibility for accepting a nominated committer is up to
>> +the subsystem's maintainers. The committers must earn a trust relationship
>> +with all subsystem maintainers, as, by granting you commit rights, they will
>> +be a part of their maintenance tasks.
> 
> I don't understand the last part of the sentence.

Now that you mention it, it is not very clear.

> 
>> +
>> +Due to that, to become a committer or a core committer, a consensus between
>> +all subsystem maintainers is required, as they all need to trust a developer
>> +well enough to be delegated the responsibility to maintain part of the code
>> +and to properly review patches from third parties, in a timely manner and
>> +keeping the status of the reviewed code at https://patchwork.linuxtv.org
>> +updated.
>> +
>> +.. Note::
>> +
>> +   In order to preserve/protect the developers that could have their commit
> 
> s/protect/protect the privacy of/
> s/that/who/
> 
>> +   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.
> 
> Unless you plan a system that puts gag orders in place, people who get
> their commit rights denied or removed against their will will be vocal
> about it.  The privacy of maintainers is a pipe dream here. A more
> transparent process would likely benefit everybody.

That's why it says 'as much as possible'. I don't think you should discuss
such things in the open by default. There is no 'best way' here: it depends
very much on the details of what is discussed and who is involved. And that
includes cultural and personality differences.

And please note that maintainers might also want to have their privacy protected.
It is painful to have to say 'no' to someone, and we're human too.

> 
>> +
>> +.. _media-committer-agreement:
>> +
>> +Media committer's agreement
>> +---------------------------
>> +
>> +Once a nominated committer is accepted by all 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.
> 
> Being "responsible for an area" of the subsystem is maintainership
> duties, it's not about committers.

No, it's about which area of the media subsystem the committer will handle
patches/PRs. E.g. Sebastian is responsible for codecs, you for media controller
and ISPs, Sakari for sensors, etc. A committer might be maintainer as well for
some/all parts, but that's separate (stored in the MAINTAINERS file).

> 
>> +
>> +Once 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 on 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
>> +
>> +   I intend to actively develop the XYZ driver, send fixes to drivers
>> +   that I can test, optionally reviewing patches and merging trivial
>> +   fixes in other areas of the 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 hereby declare that I agree with the Kernel development rules described at:
> 
> Dropping "hereby " ...

I would just drop the "I hereby declare that " part. It is probably a copy-and-paste
from somewhere, but it is overly formal.

> 
>> +
>> +   https://www.kernel.org/doc/html/latest/driver-api/media/media-committer.rst
>> +
>> +   and to the Linux Kernel development process rules.
>> +
>> +   I agree to 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 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
>> +   with 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 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;
> 
> Make this more than a note, it's fundamental to agreeing implicitly to
> process changes as listed above.
> 
>> +   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
> 
> s/specially/especially/
> 
>> +      contents under Documentation/process and for trivial typo fixes.

I agree, these can just be paragraphs rather than notes.

>> +
>> +Core committers
>> +---------------
>> +
>> +As described in Documentation/driver-api/media/maintainer-entry-profile.rst
>> +a committer may be granted with additional rights to also be able to
>> +change a core file and/or media subsystem's Kernel API. The extent of
>> +the core committer's grants will be detailed by the subsystem maintainers
>> +when they nominate a core committer.
>> +
>> +Existing committers may become core committers and vice versa. Such
>> +decisions will be taken in consensus between the subsystem maintainers.
>> +
>> +Media committers rules
>> +----------------------
>> +
>> +Media committers shall do their best efforts to avoid merged patches that
> 
> s/merged/merging/
> 
>> +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 subsystem maintainers, specially with regards of the scope of changes
>> +they may apply directly at the media-committers tree. Such scope can
>> +change over time on a mutual agreement between media committers and
>> +maintainers.
>> +
>> +As described at :ref:`Media development workflow`, there are workflows.
>> +For the committers' workflow, the following rules apply:
>> +
>> +- Each merged patch shall pass CI tests;
>> +
>> +- Media committers shall request reviews from other committers 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 subsystem maintainers as needed.
>> +
>> +Patches that do not fall under the committer's workflow criteria will follow
>> +the pull request workflow as described at :ref:`Media development workflow`.
>> +
>> +Only a subsystem maintainer can override such rules.
>> +
>> +All media committers shall ensure that patchwork will reflect the current
>> +status, e.g. patches shall be delegated to the media committer 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.

multi-committer -> media-committers

> 
> Not something to address here, but I've always found it confusing that
> patches that are accepted but not merged in your tree yet are supposed
> to be marked as "Under review". "Accepted" would be a more natural state
> of them, and we could introduce a "Merged" state for patches that are
> merged.

Sorry, I don't follow this. Probably because I am not sure what tree you
refer to with 'in your 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.
> 
> - ``Not Applicable``: Used for patch series that are not meant to be
>   merged through the media.git tree. This is mostly used for patches
>   that are cross-posted to the linux-media mailing list and meant to be
>   merged through another tree (e.g. DRM, dmabuf, device tree sources,
>   ...).

OK

> 
>> +
>> +If the committer decides not to merge it, then reply by email to patch
>> +authors, explaining why it is not merged, and patchwork shall be updated
>> +accordingly with either:
>> +
>> +- ``Changes Requested``: if a new revision was requested;
>> +- ``Rejected``: if the proposed change won't be merged upstream.
>> +
>> +.. 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/
>> +
>> +Maintaining media committer status
>> +----------------------------------
>> +
>> +A community of committers 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 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 committers,
>> +the final decision is taken by the subsystem maintainers. As the decision
>> +to become a media committer comes from a consensus between subsystem
>> +maintainers, a single subsystem maintainer not trusting the media committer
>> +anymore is enough to revoke the commit rights.
>> +
>> +If a committer 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 committer rights and update MAINTAINERS file entries
>> +accordingly. If you wish to resume contributing later on, then contact
>> +the subsystem maintainers to ask if your commit rights can be restored.
>> +
>> +A previous committer that had their commit rights revoked can keep
> 
> s/that/who/
> 
>> +contributing to the subsystem via the pull request workflow as documented
>> +at the :ref:`Media development workflow`.
>> +
>> +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/>`_.
>> +
> 

Regards,

	Hans

Re: [PATCH v4 4/5] docs: media: document media multi-committers rules and process

[Laurent Pinchart]

On Tue, Dec 03, 2024 at 02:29:10PM +0200, Laurent Pinchart wrote:
> On Tue, Dec 03, 2024 at 10:35:48AM +0100, Mauro Carvalho Chehab wrote:
> > 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.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
> > Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> > ---
> >  Documentation/driver-api/media/index.rst      |   1 +
> >  .../media/maintainer-entry-profile.rst        |   8 +
> >  .../driver-api/media/media-committer.rst      | 280 ++++++++++++++++++
> >  3 files changed, 289 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 101f6df6374f..fa28059f7b3f 100644
> > --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> > +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > @@ -69,6 +69,9 @@ as described at Documentation/process/index.rst and to the Kernel
> >  development rules inside the Kernel documentation, including its code of
> >  conduct.
> >  
> > +More details about media commiters' roles and responsibilities can be
> > +found here: Documentation/driver-api/media/media-committer.rst.
> > +
> >  .. [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.
> > @@ -221,6 +224,11 @@ 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 sign, please read
> >  Documentation/process/maintainer-pgp-guide.rst.
> >  
> > diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst
> > new file mode 100644
> > index 000000000000..3d0987a8a93b
> > --- /dev/null
> > +++ b/Documentation/driver-api/media/media-committer.rst
> > @@ -0,0 +1,280 @@
> > +Media committers
> > +================
> > +
> > +Who is a media committer?
> > +-------------------------
> > +
> > +A media committer is a developer 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.
> 
> This is a much better definition than in v1, I do like this.
> 
> > +
> > +It is a media committer's duty to ensure that their entries in the MAINTAINERS
> > +file are kept up-to-date, and that submitted patches for files for which
> > +they are listed as maintainers are timely reviewed on the mailing list,
> > +ideally not waiting in patchwork as ``New`` for more than one Kernel merge
> > +cycle, and, if accepted, applying them at the media committer's tree.
> 
> This is not a committer's duty. This is related to maintainers, not
> committers, and doesn't belong to this document.
> 
> > +
> > +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
> 
> Responsibility, yes, but not as described. The committer's
> responsibility is to adhere to the process we define, to minimize the
> risk of breakages. It's a committer's responsibility to not push patches
> that have not received consensus, and to not bypass CI. It isn't a
> committer's responsibility to "advance the Linux media subsystem
> development" (especially given that there are often very opposite views
> in the community about what this means in practice).
> 
> > +is also based on a trust relationship among other committers, maintainers
> > +and the Linux Media community[1].
> > +
> > +As such, a media committer is 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).
> > +
> > +.. Note::
> > +
> > +   1. 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;
> > +   2. if patches are fixing bugs against already released Kernels, including
> > +      the reverts above mentioned, the media committer shall add the needed
> 
> s/above mentioned/mentioned above/
> 
> > +      tags. Please see :ref:`Media development workflow` for more details.
> > +
> > +[1] The Linux Media Community, also called LinuxTV Community, has its primary
> > +    site at https://linuxtv.org.
> > +
> > +    Media committers and developers are reachable via the #linux-media
> > +    IRC channel at OFTC.
> 
> s/at/on/
> 
> > +
> > +Becoming a media committer
> > +--------------------------
> > +
> > +The most important aspect of volunteering to be a committer is that you have
> > +demonstrated the ability to give good code reviews. So we are looking for
> 
> Again, that's not what a committer is about. Committer, as the name
> strongly implies, is about committing patches.
> 
> > +whether or not we think you will be good at doing that.
> > +
> > +As such, potential committers 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.
> > +
> > +So, in addition to actually making the code changes, you are basically
> > +demonstrating your:
> > +
> > +- commitment to the project;
> 
> What does that mean ?
> 
> > +- 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).
> > +
> > +Developers that desire to become committers are encouraged to participate
> 
> s/that/who/
> 
> > +at the yearly Linux Media Summit, typically co-located with a Linux related
> > +conference.
> > +
> > +If you are doing such tasks and have become a valued developer, an
> > +existing committer can nominate you to the media subsystem maintainers.
> 
> All of this sounds so horrible from a community building point of view.
> As a newcomer, reading this document, I would be really tempted to run
> away from a community that seems very unwelcoming (not to use stronger
> words).
> 
> > +
> > +The ultimate responsibility for accepting a nominated committer is up to
> > +the subsystem's maintainers. The committers must earn a trust relationship
> > +with all subsystem maintainers, as, by granting you commit rights, they will
> > +be a part of their maintenance tasks.
> 
> I don't understand the last part of the sentence.
> 
> > +
> > +Due to that, to become a committer or a core committer, a consensus between
> > +all subsystem maintainers is required, as they all need to trust a developer
> > +well enough to be delegated the responsibility to maintain part of the code
> > +and to properly review patches from third parties, in a timely manner and
> > +keeping the status of the reviewed code at https://patchwork.linuxtv.org
> > +updated.
> > +
> > +.. Note::
> > +
> > +   In order to preserve/protect the developers that could have their commit
> 
> s/protect/protect the privacy of/
> s/that/who/
> 
> > +   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.
> 
> Unless you plan a system that puts gag orders in place, people who get
> their commit rights denied or removed against their will will be vocal
> about it.  The privacy of maintainers is a pipe dream here. A more
> transparent process would likely benefit everybody.
> 
> > +
> > +.. _media-committer-agreement:
> > +
> > +Media committer's agreement
> > +---------------------------
> > +
> > +Once a nominated committer is accepted by all 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.
> 
> Being "responsible for an area" of the subsystem is maintainership
> duties, it's not about committers.
> 
> > +
> > +Once 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 on 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
> > +
> > +   I intend to actively develop the XYZ driver, send fixes to drivers
> > +   that I can test, optionally reviewing patches and merging trivial
> > +   fixes in other areas of the 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 hereby declare that I agree with the Kernel development rules described at:
> 
> Dropping "hereby " would make it sound a bit less like a forced
> confession obtained by torture.

It has been brought to may attention that the use of this particular
wording may have hurt or shocked someone.

I'd like to clarify that this was not in any way intended to be taken
literally. The point behind this comment still stands, what I wanted to
convey is that the proposed formal declaration sounds to me very cold
and borderline offending. The wording I choose to convey this was not
meant as a tit-for-tat offense escalation, and I'm sorry if has hurt or
shocked anyone.

> > +
> > +   https://www.kernel.org/doc/html/latest/driver-api/media/media-committer.rst
> > +
> > +   and to the Linux Kernel development process rules.
> > +
> > +   I agree to 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 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
> > +   with 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 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;
> 
> Make this more than a note, it's fundamental to agreeing implicitly to
> process changes as listed above.
> 
> > +   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
> 
> s/specially/especially/
> 
> > +      contents under Documentation/process and for trivial typo fixes.
> > +
> > +Core committers
> > +---------------
> > +
> > +As described in Documentation/driver-api/media/maintainer-entry-profile.rst
> > +a committer may be granted with additional rights to also be able to
> > +change a core file and/or media subsystem's Kernel API. The extent of
> > +the core committer's grants will be detailed by the subsystem maintainers
> > +when they nominate a core committer.
> > +
> > +Existing committers may become core committers and vice versa. Such
> > +decisions will be taken in consensus between the subsystem maintainers.
> > +
> > +Media committers rules
> > +----------------------
> > +
> > +Media committers shall do their best efforts to avoid merged patches that
> 
> s/merged/merging/
> 
> > +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 subsystem maintainers, specially with regards of the scope of changes
> > +they may apply directly at the media-committers tree. Such scope can
> > +change over time on a mutual agreement between media committers and
> > +maintainers.
> > +
> > +As described at :ref:`Media development workflow`, there are workflows.
> > +For the committers' workflow, the following rules apply:
> > +
> > +- Each merged patch shall pass CI tests;
> > +
> > +- Media committers shall request reviews from other committers 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 subsystem maintainers as needed.
> > +
> > +Patches that do not fall under the committer's workflow criteria will follow
> > +the pull request workflow as described at :ref:`Media development workflow`.
> > +
> > +Only a subsystem maintainer can override such rules.
> > +
> > +All media committers shall ensure that patchwork will reflect the current
> > +status, e.g. patches shall be delegated to the media committer 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.
> 
> Not something to address here, but I've always found it confusing that
> patches that are accepted but not merged in your tree yet are supposed
> to be marked as "Under review". "Accepted" would be a more natural state
> of them, and we could introduce a "Merged" state for patches that are
> merged.
> 
> > +- ``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.
> 
> - ``Not Applicable``: Used for patch series that are not meant to be
>   merged through the media.git tree. This is mostly used for patches
>   that are cross-posted to the linux-media mailing list and meant to be
>   merged through another tree (e.g. DRM, dmabuf, device tree sources,
>   ...).
> 
> > +
> > +If the committer decides not to merge it, then reply by email to patch
> > +authors, explaining why it is not merged, and patchwork shall be updated
> > +accordingly with either:
> > +
> > +- ``Changes Requested``: if a new revision was requested;
> > +- ``Rejected``: if the proposed change won't be merged upstream.
> > +
> > +.. 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/
> > +
> > +Maintaining media committer status
> > +----------------------------------
> > +
> > +A community of committers 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 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 committers,
> > +the final decision is taken by the subsystem maintainers. As the decision
> > +to become a media committer comes from a consensus between subsystem
> > +maintainers, a single subsystem maintainer not trusting the media committer
> > +anymore is enough to revoke the commit rights.
> > +
> > +If a committer 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 committer rights and update MAINTAINERS file entries
> > +accordingly. If you wish to resume contributing later on, then contact
> > +the subsystem maintainers to ask if your commit rights can be restored.
> > +
> > +A previous committer that had their commit rights revoked can keep
> 
> s/that/who/
> 
> > +contributing to the subsystem via the pull request workflow as documented
> > +at the :ref:`Media development workflow`.
> > +
> > +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/>`_.
> > +

-- 
Regards,

Laurent Pinchart

Re: [PATCH v4 4/5] docs: media: document media multi-committers rules and process

[Hans Verkuil]

On 05/12/2024 13:36, Hans Verkuil wrote:
> On 03/12/2024 13:29, Laurent Pinchart wrote:
>>
>>> +
>>> +Once 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 on 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
>>> +
>>> +   I intend to actively develop the XYZ driver, send fixes to drivers
>>> +   that I can test, optionally reviewing patches and merging trivial
>>> +   fixes in other areas of the 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 hereby declare that I agree with the Kernel development rules described at:
>>
>> Dropping "hereby " ...
> 
> I would just drop the "I hereby declare that " part. It is probably a copy-and-paste
> from somewhere, but it is overly formal.
> 
>>
>>> +
>>> +   https://www.kernel.org/doc/html/latest/driver-api/media/media-committer.rst
>>> +
>>> +   and to the Linux Kernel development process rules.
>>> +
>>> +   I agree to 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 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
>>> +   with the rules in effect at the time of the commit.

After looking at https://developercertificate.org/, I would propose to rewrite
this along these lines:

---------------------------------------------------------------------------
By becoming media committer, I certify that:

(a) I agree to 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.

(b) I agree to the Code of Conduct as documented in:

	https://www.kernel.org/doc/html/latest/process/code-of-conduct.rst

(c) I am aware that the Kernel development rules change over time.
    By doing a new push to the media-committer tree, I understand that I agree
    with the rules in effect at the time of the commit.
---------------------------------------------------------------------------

I assume that the people who wrote the Developer's Certificate of Origin knew what
they were doing.

Regards,

	Hans

Re: [PATCH v4 3/5] docs: media: update maintainer-entry-profile for multi-committers

[Sakari Ailus]

Hi Mauro,

This seems pretty good, there are some comments mostly on technicalities
below.

On Tue, Dec 03, 2024 at 10:35:47AM +0100, Mauro Carvalho Chehab wrote:
> 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>
> Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
> Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> ---
>  .../media/maintainer-entry-profile.rst        | 241 ++++++++++++++----
>  1 file changed, 189 insertions(+), 52 deletions(-)
> 
> diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> index ffc712a5f632..101f6df6374f 100644
> --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> @@ -4,11 +4,12 @@ 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) covers support for a
> +variety of devices: stream capture, analog and digital TV streams, cameras,
> +remote controllers, HDMI CEC and media pipeline control.

I'd make a difference here between the Media tree and the Linux Media
community. The drivers in the Media tree support these devices whereas the
community generally works on this codebase.

>  
> -It covers, mainly, the contents of those directories:
> +They consist of developers who work with the Linux Kernel media subsystem,
> +which covers, mainly, the contents of those directories:

If you want to refer to the community here, I'd use that word.

>  
>    - drivers/media
>    - drivers/staging/media
> @@ -27,19 +28,158 @@ 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 files.

I'd drop " files" as the documentation is split between C source code files
and ReST nowadays.

>  
> -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
> +Due to the size and wide scope of the media subsystem, the media's
> +maintainership model is to have committers that have a broad knowledge of

Maintainership or maintenance?

s/is to have/recognises/ ?

> +a specific aspect of the subsystem. It is the committers' 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.
>  
> -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).
> +Media committers
> +----------------
> +
> +In the media subsystem, there are experienced developers who can push
> +patches directly to the development tree. These developers are called
> +Media committers and are divided into the following categories:
> +
> +- Committers:
> +    contributors for one or more drivers within the media subsystem.
> +    They can push changes to the tree that do not affect the core or ABI.

Question to Ricardo -- sorry if I already have asked this: can this be
enforced?

> +
> +- Core committers:
> +    responsible for part of the media core. They are typically
> +    responsible for one or more drivers within the media subsystem, but, besides
> +    that, they can also merge patches that change the code common to multiple
> +    drivers, including the kernel internal API.

This doesn't say clearly whether e.g. the V4L2 or MC frameworks are
included or not. I think they should be and this should be mentioned. Same
for videobuf2.

> +
> +- Subsystem maintainers:
> +    responsible for the subsystem as a whole, with access to the
> +    entire subsystem.
> +
> +    API/ABI changes are done via consensus between subsystem maintainers\ [2]_.
> +
> +    Only subsystem maintainers push changes that affect the userspace
> +    API/ABI. Committers may push ABI/API changes on their commits if they
> +    have approvals from subsystem maintainers.
> +
> +All media committers 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.

Is there a need to mention this? Aren't people generally expected to
follow the process anyway?

> +
> +.. [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.
> +
> +Media development tree
> +----------------------
> +
> +The main development tree used by the media subsystem is hosted at LinuxTV.org,
> +where we also maintain news about the subsystem, wiki pages and a patchwork
> +instance where we track patches though their lifetime.
> +
> +The main tree used by media developers is at:
> +
> +https://git.linuxtv.org/media.git/
> +
> +.. _Media development workflow:
> +
> +Media development workflow
> +++++++++++++++++++++++++++
> +
> +All changes for the media subsystem must be sent first as e-mails to the

s/must/shall/ ?

> +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 committer(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 media.git ``next`` branch;
> +
> +2. Bug fixes for the current mainline release:
> +
> +   - baseline shall be the latest mainline release or media.git ``fixes``
> +     if changes depend on a fix already merged;
> +
> +3. Bug fixes for the next mainline release:
> +
> +   - baseline shall be a prepatch release (-rcX) or media.git ``fixes``
> +     if changes depend on a fix already merged. It is also
> +     fine to use media.git ``next`` as baseline for such patches if such
> +     patches apply cleanly on ``fixes``.
> +
> +.. 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. Pull request workflow: patches are handled by subsystem maintainers::
> +
> +     +-------+   +---------+   +-------+   +-----------------------+   +---------+
> +     |e-mail |-->|patchwork|-->|pull   |-->|maintainers merge      |-->|media.git|
> +     |to LMML|   |picks it |   |request|   |in media-committers.git|   +---------+
> +     +-------+   +---------+   +-------+   +-----------------------+
> +
> +   For this workflow, pull requests can be generated by committers,
> +   former committers, subsystem maintainers or by trusted long-time
> +   contributors. If you are not in such group, please don't submit
> +   pull requests, as they will not be processed.
> +
> +b. Committers' workflow: patches are handled by media committers::
> +
> +     +-------+   +---------+   +--------------------+   +-----------+   +---------+
> +     |e-mail |-->|patchwork|-->|committers merge at |-->|maintainers|-->|media.git|
> +     |to LMML|   |picks it |   |media-committers.git|   |approval   |   +---------+
> +     +-------+   +---------+   +--------------------+   +-----------+
> +
> +On both workflows, all patches shall be properly reviewed at
> +linux-media@vger.kernel.org (LMML) before being merged at media-committers.git.
> +
> +When patches are picked by patchwork and when merged at media-committers,
> +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

I'd remove the latter comma.

> +explain why the errors are false positives.
> +
> +Patches will only be moved to the next stage in those two workflows if they
> +pass on CI or if there are false-positives in the CI reports.
> +
> +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 +187,49 @@ 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, 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, thus such
> +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 to a few hours
> +       for a patch to be picked by patchwork.

I'd just refer to "longer" in the latter case; there are no fixed time
limits anyway.

> +
> +.. [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 sign, please read
> +Documentation/process/maintainer-pgp-guide.rst.
>  
> -- HDMI CEC:
> -    Hans Verkuil <hverkuil@xs4all.nl>
> +Subsystem 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@xs4all.nl>
> -
> -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> and
> +  - Hans Verkuil <hverkuil@xs4all.nl>
>  
>  Submit Checklist Addendum
>  -------------------------
> @@ -106,18 +244,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 compilance 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 +269,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
>  +++++++++++++++++++++
>  
> @@ -199,7 +336,7 @@ 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:``,

-- 
Kind regards,

Sakari Ailus

Re: [PATCH v4 4/5] docs: media: document media multi-committers rules and process

[Sakari Ailus]

Hi Mauro, Hans,

On Tue, Dec 03, 2024 at 10:35:48AM +0100, Mauro Carvalho Chehab wrote:
> 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.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
> Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>

Overall it looks like the review comments are fine tuning with probably
little effect in practice right now. Do you think you could re-spin the
series, taking the discussion into account?

-- 
Kind regards,

Sakari Ailus

Re: [PATCH v4 3/5] docs: media: update maintainer-entry-profile for multi-committers

[Mauro Carvalho Chehab]

Em Thu, 21 Aug 2025 12:26:18 +0000
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro,
> 
> This seems pretty good, there are some comments mostly on technicalities
> below.
> 
> On Tue, Dec 03, 2024 at 10:35:47AM +0100, Mauro Carvalho Chehab wrote:
> > 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>
> > Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
> > Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> > ---
> >  .../media/maintainer-entry-profile.rst        | 241 ++++++++++++++----
> >  1 file changed, 189 insertions(+), 52 deletions(-)
> > 
> > diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > index ffc712a5f632..101f6df6374f 100644
> > --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> > +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > @@ -4,11 +4,12 @@ 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) covers support for a
> > +variety of devices: stream capture, analog and digital TV streams, cameras,
> > +remote controllers, HDMI CEC and media pipeline control.  
> 
> I'd make a difference here between the Media tree and the Linux Media
> community. The drivers in the Media tree support these devices whereas the
> community generally works on this codebase.
> 
> >  
> > -It covers, mainly, the contents of those directories:
> > +They consist of developers who work with the Linux Kernel media subsystem,
> > +which covers, mainly, the contents of those directories:  
> 
> If you want to refer to the community here, I'd use that word.

What about this:

<text>
The Linux Media Community (aka: the LinuxTV Community) consist of developers 
who work with the Linux Kernel media subsystem, together with users who
benefit from such develoment and help testing the developed code.

They work on the top of the Media tree, which has code to support a    
variety of devices: stream capture, analog and digital TV streams, cameras,
remote controllers, HDMI CEC and media pipeline control.

The Media tree is mainly responsible to be the main source of the
code under development with the contents of those directories:

  - drivers/media
  - drivers/staging/media
  - Documentation/admin-guide/media
  - Documentation/driver-api/media
  - Documentation/userspace-api/media
  - Documentation/devicetree/bindings/media/\ [1]_
  - include/media
</text>

> 
> >  
> >    - drivers/media
> >    - drivers/staging/media
> > @@ -27,19 +28,158 @@ 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 files.  
> 
> I'd drop " files" as the documentation is split between C source code files
> and ReST nowadays.

OK.

> > -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
> > +Due to the size and wide scope of the media subsystem, the media's
> > +maintainership model is to have committers that have a broad knowledge of  
> 
> Maintainership or maintenance?
> 
> s/is to have/recognises/ ?

OK.
 
> > +a specific aspect of the subsystem. It is the committers' 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.
> >  
> > -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).
> > +Media committers
> > +----------------
> > +
> > +In the media subsystem, there are experienced developers who can push
> > +patches directly to the development tree. These developers are called
> > +Media committers and are divided into the following categories:
> > +
> > +- Committers:
> > +    contributors for one or more drivers within the media subsystem.
> > +    They can push changes to the tree that do not affect the core or ABI.  
> 
> Question to Ricardo -- sorry if I already have asked this: can this be
> enforced?
> 
> > +
> > +- Core committers:
> > +    responsible for part of the media core. They are typically
> > +    responsible for one or more drivers within the media subsystem, but, besides
> > +    that, they can also merge patches that change the code common to multiple
> > +    drivers, including the kernel internal API.  
> 
> This doesn't say clearly whether e.g. the V4L2 or MC frameworks are
> included or not. I think they should be and this should be mentioned. Same
> for videobuf2.

The problem of specifying what the core via frameworks, vb2, etc is that
this would require constant maintainance. Core is everything that is not
inside a driver for an specific driver.

We called this here as "the code common to multiple drivers". For me it
is clear, but if you have a better generic term, I'm all ears.

> 
> > +
> > +- Subsystem maintainers:
> > +    responsible for the subsystem as a whole, with access to the
> > +    entire subsystem.
> > +
> > +    API/ABI changes are done via consensus between subsystem maintainers\ [2]_.
> > +
> > +    Only subsystem maintainers push changes that affect the userspace
> > +    API/ABI. Committers may push ABI/API changes on their commits if they
> > +    have approvals from subsystem maintainers.
> > +
> > +All media committers 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.  
> 
> Is there a need to mention this? Aren't people generally expected to
> follow the process anyway?

There's a big difference between "generally expected" and "have to agree".
The goal here is really to prevent having bad committers as we had in the
past on our previous multicommiters model before we moved to git. If this
ever have again, by having an explicit agreement, one cannot deny he/she
didn't know the rules.

> > +
> > +.. [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.
> > +
> > +Media development tree
> > +----------------------
> > +
> > +The main development tree used by the media subsystem is hosted at LinuxTV.org,
> > +where we also maintain news about the subsystem, wiki pages and a patchwork
> > +instance where we track patches though their lifetime.
> > +
> > +The main tree used by media developers is at:
> > +
> > +https://git.linuxtv.org/media.git/
> > +
> > +.. _Media development workflow:
> > +
> > +Media development workflow
> > +++++++++++++++++++++++++++
> > +
> > +All changes for the media subsystem must be sent first as e-mails to the  
> 
> s/must/shall/ ?

OK.

> > +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 committer(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 media.git ``next`` branch;
> > +
> > +2. Bug fixes for the current mainline release:
> > +
> > +   - baseline shall be the latest mainline release or media.git ``fixes``
> > +     if changes depend on a fix already merged;
> > +
> > +3. Bug fixes for the next mainline release:
> > +
> > +   - baseline shall be a prepatch release (-rcX) or media.git ``fixes``
> > +     if changes depend on a fix already merged. It is also
> > +     fine to use media.git ``next`` as baseline for such patches if such
> > +     patches apply cleanly on ``fixes``.
> > +
> > +.. 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. Pull request workflow: patches are handled by subsystem maintainers::
> > +
> > +     +-------+   +---------+   +-------+   +-----------------------+   +---------+
> > +     |e-mail |-->|patchwork|-->|pull   |-->|maintainers merge      |-->|media.git|
> > +     |to LMML|   |picks it |   |request|   |in media-committers.git|   +---------+
> > +     +-------+   +---------+   +-------+   +-----------------------+
> > +
> > +   For this workflow, pull requests can be generated by committers,
> > +   former committers, subsystem maintainers or by trusted long-time
> > +   contributors. If you are not in such group, please don't submit
> > +   pull requests, as they will not be processed.
> > +
> > +b. Committers' workflow: patches are handled by media committers::
> > +
> > +     +-------+   +---------+   +--------------------+   +-----------+   +---------+
> > +     |e-mail |-->|patchwork|-->|committers merge at |-->|maintainers|-->|media.git|
> > +     |to LMML|   |picks it |   |media-committers.git|   |approval   |   +---------+
> > +     +-------+   +---------+   +--------------------+   +-----------+
> > +
> > +On both workflows, all patches shall be properly reviewed at
> > +linux-media@vger.kernel.org (LMML) before being merged at media-committers.git.
> > +
> > +When patches are picked by patchwork and when merged at media-committers,
> > +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  
> 
> I'd remove the latter comma.

OK.

> 
> > +explain why the errors are false positives.
> > +
> > +Patches will only be moved to the next stage in those two workflows if they
> > +pass on CI or if there are false-positives in the CI reports.
> > +
> > +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 +187,49 @@ 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, 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, thus such
> > +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 to a few hours
> > +       for a patch to be picked by patchwork.  
> 
> I'd just refer to "longer" in the latter case; there are no fixed time
> limits anyway.
> 

OK.

> > +
> > +.. [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 sign, please read
> > +Documentation/process/maintainer-pgp-guide.rst.
> >  
> > -- HDMI CEC:
> > -    Hans Verkuil <hverkuil@xs4all.nl>
> > +Subsystem 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@xs4all.nl>
> > -
> > -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> and
> > +  - Hans Verkuil <hverkuil@xs4all.nl>
> >  
> >  Submit Checklist Addendum
> >  -------------------------
> > @@ -106,18 +244,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 compilance 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 +269,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
> >  +++++++++++++++++++++
> >  
> > @@ -199,7 +336,7 @@ 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:``,  
> 

Thanks,
Mauro

Re: [PATCH v4 4/5] docs: media: document media multi-committers rules and process

[Mauro Carvalho Chehab]

Em Thu, 21 Aug 2025 13:08:19 +0000
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro, Hans,
> 
> On Tue, Dec 03, 2024 at 10:35:48AM +0100, Mauro Carvalho Chehab wrote:
> > 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.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
> > Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>  
> 
> Overall it looks like the review comments are fine tuning with probably
> little effect in practice right now. Do you think you could re-spin the
> series, taking the discussion into account?

I'll be re-sending the series now with your changes to 3/5. People
may comment on the top of it in a polite way without violating the
CoC.

Thanks,
Mauro

Re: [PATCH v4 3/5] docs: media: update maintainer-entry-profile for multi-committers

[Sakari Ailus]

Hi Mauro,

On Fri, Aug 22, 2025 at 10:23:46AM +0200, Mauro Carvalho Chehab wrote:
> Em Thu, 21 Aug 2025 12:26:18 +0000
> Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> 
> > Hi Mauro,
> > 
> > This seems pretty good, there are some comments mostly on technicalities
> > below.
> > 
> > On Tue, Dec 03, 2024 at 10:35:47AM +0100, Mauro Carvalho Chehab wrote:
> > > 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>
> > > Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
> > > Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> > > ---
> > >  .../media/maintainer-entry-profile.rst        | 241 ++++++++++++++----
> > >  1 file changed, 189 insertions(+), 52 deletions(-)
> > > 
> > > diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > > index ffc712a5f632..101f6df6374f 100644
> > > --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> > > +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > > @@ -4,11 +4,12 @@ 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) covers support for a
> > > +variety of devices: stream capture, analog and digital TV streams, cameras,
> > > +remote controllers, HDMI CEC and media pipeline control.  
> > 
> > I'd make a difference here between the Media tree and the Linux Media
> > community. The drivers in the Media tree support these devices whereas the
> > community generally works on this codebase.
> > 
> > >  
> > > -It covers, mainly, the contents of those directories:
> > > +They consist of developers who work with the Linux Kernel media subsystem,
> > > +which covers, mainly, the contents of those directories:  
> > 
> > If you want to refer to the community here, I'd use that word.
> 
> What about this:
> 
> <text>
> The Linux Media Community (aka: the LinuxTV Community) consist of developers 
> who work with the Linux Kernel media subsystem, together with users who
> benefit from such develoment and help testing the developed code.

How about, with slight modifications:

The Linux Media Community (aka: the LinuxTV Community) is formed of
developers working on Linux Kernel Media Subsystem, together with users.

> 
> They work on the top of the Media tree, which has code to support a    
> variety of devices: stream capture, analog and digital TV streams, cameras,
> remote controllers, HDMI CEC and media pipeline control.
> 
> The Media tree is mainly responsible to be the main source of the
> code under development with the contents of those directories:
> 
>   - drivers/media
>   - drivers/staging/media
>   - Documentation/admin-guide/media
>   - Documentation/driver-api/media
>   - Documentation/userspace-api/media
>   - Documentation/devicetree/bindings/media/\ [1]_
>   - include/media
> </text>
> 
> > 
> > >  
> > >    - drivers/media
> > >    - drivers/staging/media
> > > @@ -27,19 +28,158 @@ 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 files.  
> > 
> > I'd drop " files" as the documentation is split between C source code files
> > and ReST nowadays.
> 
> OK.
> 
> > > -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
> > > +Due to the size and wide scope of the media subsystem, the media's
> > > +maintainership model is to have committers that have a broad knowledge of  
> > 
> > Maintainership or maintenance?
> > 
> > s/is to have/recognises/ ?
> 
> OK.
>  
> > > +a specific aspect of the subsystem. It is the committers' 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.
> > >  
> > > -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).
> > > +Media committers
> > > +----------------
> > > +
> > > +In the media subsystem, there are experienced developers who can push
> > > +patches directly to the development tree. These developers are called
> > > +Media committers and are divided into the following categories:
> > > +
> > > +- Committers:
> > > +    contributors for one or more drivers within the media subsystem.
> > > +    They can push changes to the tree that do not affect the core or ABI.  
> > 
> > Question to Ricardo -- sorry if I already have asked this: can this be
> > enforced?
> > 
> > > +
> > > +- Core committers:
> > > +    responsible for part of the media core. They are typically
> > > +    responsible for one or more drivers within the media subsystem, but, besides
> > > +    that, they can also merge patches that change the code common to multiple
> > > +    drivers, including the kernel internal API.  
> > 
> > This doesn't say clearly whether e.g. the V4L2 or MC frameworks are
> > included or not. I think they should be and this should be mentioned. Same
> > for videobuf2.
> 
> The problem of specifying what the core via frameworks, vb2, etc is that
> this would require constant maintainance. Core is everything that is not
> inside a driver for an specific driver.
> 
> We called this here as "the code common to multiple drivers". For me it
> is clear, but if you have a better generic term, I'm all ears.

How about:

- Core committers:
    responsible for part of the Media Core, including V4L2, Media
    controller, Videobuf2, CEC and DVB frameworks. They are typically
    responsible for one or more drivers within the Media Subsystem, but,
    besides that, they can also merge patches that change the code common
    to multiple drivers, including the kernel internal API.

I think we should define Media Subsystem, Media Core and possibly Media
Community in the glossary but I'd do that after merging this set.

> 
> > 
> > > +
> > > +- Subsystem maintainers:
> > > +    responsible for the subsystem as a whole, with access to the
> > > +    entire subsystem.
> > > +
> > > +    API/ABI changes are done via consensus between subsystem maintainers\ [2]_.
> > > +
> > > +    Only subsystem maintainers push changes that affect the userspace
> > > +    API/ABI. Committers may push ABI/API changes on their commits if they
> > > +    have approvals from subsystem maintainers.
> > > +
> > > +All media committers 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.  
> > 
> > Is there a need to mention this? Aren't people generally expected to
> > follow the process anyway?
> 
> There's a big difference between "generally expected" and "have to agree".
> The goal here is really to prevent having bad committers as we had in the
> past on our previous multicommiters model before we moved to git. If this
> ever have again, by having an explicit agreement, one cannot deny he/she
> didn't know the rules.

Fair enough. Either way, enforment is discretionary so I think this is
fine -- mistakes tend to happen, to everybody, at least in some extent.

> 
> > > +
> > > +.. [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.
> > > +
> > > +Media development tree
> > > +----------------------
> > > +
> > > +The main development tree used by the media subsystem is hosted at LinuxTV.org,
> > > +where we also maintain news about the subsystem, wiki pages and a patchwork
> > > +instance where we track patches though their lifetime.
> > > +
> > > +The main tree used by media developers is at:
> > > +
> > > +https://git.linuxtv.org/media.git/
> > > +
> > > +.. _Media development workflow:
> > > +
> > > +Media development workflow
> > > +++++++++++++++++++++++++++
> > > +
> > > +All changes for the media subsystem must be sent first as e-mails to the  
> > 
> > s/must/shall/ ?
> 
> OK.
> 
> > > +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 committer(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 media.git ``next`` branch;
> > > +
> > > +2. Bug fixes for the current mainline release:
> > > +
> > > +   - baseline shall be the latest mainline release or media.git ``fixes``
> > > +     if changes depend on a fix already merged;
> > > +
> > > +3. Bug fixes for the next mainline release:
> > > +
> > > +   - baseline shall be a prepatch release (-rcX) or media.git ``fixes``
> > > +     if changes depend on a fix already merged. It is also
> > > +     fine to use media.git ``next`` as baseline for such patches if such
> > > +     patches apply cleanly on ``fixes``.
> > > +
> > > +.. 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. Pull request workflow: patches are handled by subsystem maintainers::
> > > +
> > > +     +-------+   +---------+   +-------+   +-----------------------+   +---------+
> > > +     |e-mail |-->|patchwork|-->|pull   |-->|maintainers merge      |-->|media.git|
> > > +     |to LMML|   |picks it |   |request|   |in media-committers.git|   +---------+
> > > +     +-------+   +---------+   +-------+   +-----------------------+
> > > +
> > > +   For this workflow, pull requests can be generated by committers,
> > > +   former committers, subsystem maintainers or by trusted long-time
> > > +   contributors. If you are not in such group, please don't submit
> > > +   pull requests, as they will not be processed.
> > > +
> > > +b. Committers' workflow: patches are handled by media committers::
> > > +
> > > +     +-------+   +---------+   +--------------------+   +-----------+   +---------+
> > > +     |e-mail |-->|patchwork|-->|committers merge at |-->|maintainers|-->|media.git|
> > > +     |to LMML|   |picks it |   |media-committers.git|   |approval   |   +---------+
> > > +     +-------+   +---------+   +--------------------+   +-----------+
> > > +
> > > +On both workflows, all patches shall be properly reviewed at
> > > +linux-media@vger.kernel.org (LMML) before being merged at media-committers.git.
> > > +
> > > +When patches are picked by patchwork and when merged at media-committers,
> > > +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  
> > 
> > I'd remove the latter comma.
> 
> OK.
> 
> > 
> > > +explain why the errors are false positives.
> > > +
> > > +Patches will only be moved to the next stage in those two workflows if they
> > > +pass on CI or if there are false-positives in the CI reports.
> > > +
> > > +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 +187,49 @@ 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, 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, thus such
> > > +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 to a few hours
> > > +       for a patch to be picked by patchwork.  
> > 
> > I'd just refer to "longer" in the latter case; there are no fixed time
> > limits anyway.
> > 
> 
> OK.
> 
> > > +
> > > +.. [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 sign, please read
> > > +Documentation/process/maintainer-pgp-guide.rst.
> > >  
> > > -- HDMI CEC:
> > > -    Hans Verkuil <hverkuil@xs4all.nl>
> > > +Subsystem 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@xs4all.nl>
> > > -
> > > -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> and
> > > +  - Hans Verkuil <hverkuil@xs4all.nl>
> > >  
> > >  Submit Checklist Addendum
> > >  -------------------------
> > > @@ -106,18 +244,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 compilance 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 +269,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
> > >  +++++++++++++++++++++
> > >  
> > > @@ -199,7 +336,7 @@ 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:``,  
> > 

-- 
Regards,

Sakari Ailus

Re: [PATCH v4 3/5] docs: media: update maintainer-entry-profile for multi-committers

[Mauro Carvalho Chehab]

Em Fri, 22 Aug 2025 08:59:29 +0000
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro,
> 
> On Fri, Aug 22, 2025 at 10:23:46AM +0200, Mauro Carvalho Chehab wrote:
> > Em Thu, 21 Aug 2025 12:26:18 +0000
> > Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> >   
> > > Hi Mauro,
> > > 
> > > This seems pretty good, there are some comments mostly on technicalities
> > > below.
> > > 
> > > On Tue, Dec 03, 2024 at 10:35:47AM +0100, Mauro Carvalho Chehab wrote:  
> > > > 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>
> > > > Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
> > > > Reviewed-by: Ricardo Ribalda <ribalda@chromium.org>
> > > > ---
> > > >  .../media/maintainer-entry-profile.rst        | 241 ++++++++++++++----
> > > >  1 file changed, 189 insertions(+), 52 deletions(-)
> > > > 
> > > > diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > > > index ffc712a5f632..101f6df6374f 100644
> > > > --- a/Documentation/driver-api/media/maintainer-entry-profile.rst
> > > > +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
> > > > @@ -4,11 +4,12 @@ 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) covers support for a
> > > > +variety of devices: stream capture, analog and digital TV streams, cameras,
> > > > +remote controllers, HDMI CEC and media pipeline control.    
> > > 
> > > I'd make a difference here between the Media tree and the Linux Media
> > > community. The drivers in the Media tree support these devices whereas the
> > > community generally works on this codebase.
> > >   
> > > >  
> > > > -It covers, mainly, the contents of those directories:
> > > > +They consist of developers who work with the Linux Kernel media subsystem,
> > > > +which covers, mainly, the contents of those directories:    
> > > 
> > > If you want to refer to the community here, I'd use that word.  
> > 
> > What about this:
> > 
> > <text>
> > The Linux Media Community (aka: the LinuxTV Community) consist of developers 
> > who work with the Linux Kernel media subsystem, together with users who
> > benefit from such develoment and help testing the developed code.  
> 
> How about, with slight modifications:
> 
> The Linux Media Community (aka: the LinuxTV Community) is formed of
> developers working on Linux Kernel Media Subsystem, together with users.

Works for me, although I prefer keep mentioning about the important
role that users play on help testing drivers.

> 
> > 
> > They work on the top of the Media tree, which has code to support a    
> > variety of devices: stream capture, analog and digital TV streams, cameras,
> > remote controllers, HDMI CEC and media pipeline control.
> > 
> > The Media tree is mainly responsible to be the main source of the
> > code under development with the contents of those directories:
> > 
> >   - drivers/media
> >   - drivers/staging/media
> >   - Documentation/admin-guide/media
> >   - Documentation/driver-api/media
> >   - Documentation/userspace-api/media
> >   - Documentation/devicetree/bindings/media/\ [1]_
> >   - include/media
> > </text>
> >   
> > >   
> > > >  
> > > >    - drivers/media
> > > >    - drivers/staging/media
> > > > @@ -27,19 +28,158 @@ 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 files.    
> > > 
> > > I'd drop " files" as the documentation is split between C source code files
> > > and ReST nowadays.  
> > 
> > OK.
> >   
> > > > -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
> > > > +Due to the size and wide scope of the media subsystem, the media's
> > > > +maintainership model is to have committers that have a broad knowledge of    
> > > 
> > > Maintainership or maintenance?
> > > 
> > > s/is to have/recognises/ ?  
> > 
> > OK.
> >    
> > > > +a specific aspect of the subsystem. It is the committers' 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.
> > > >  
> > > > -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).
> > > > +Media committers
> > > > +----------------
> > > > +
> > > > +In the media subsystem, there are experienced developers who can push
> > > > +patches directly to the development tree. These developers are called
> > > > +Media committers and are divided into the following categories:
> > > > +
> > > > +- Committers:
> > > > +    contributors for one or more drivers within the media subsystem.
> > > > +    They can push changes to the tree that do not affect the core or ABI.    
> > > 
> > > Question to Ricardo -- sorry if I already have asked this: can this be
> > > enforced?
> > >   
> > > > +
> > > > +- Core committers:
> > > > +    responsible for part of the media core. They are typically
> > > > +    responsible for one or more drivers within the media subsystem, but, besides
> > > > +    that, they can also merge patches that change the code common to multiple
> > > > +    drivers, including the kernel internal API.    
> > > 
> > > This doesn't say clearly whether e.g. the V4L2 or MC frameworks are
> > > included or not. I think they should be and this should be mentioned. Same
> > > for videobuf2.  
> > 
> > The problem of specifying what the core via frameworks, vb2, etc is that
> > this would require constant maintainance. Core is everything that is not
> > inside a driver for an specific driver.
> > 
> > We called this here as "the code common to multiple drivers". For me it
> > is clear, but if you have a better generic term, I'm all ears.  
> 
> How about:
> 
> - Core committers:
>     responsible for part of the Media Core, including V4L2, Media
>     controller, Videobuf2, CEC and DVB frameworks. They are typically
>     responsible for one or more drivers within the Media Subsystem, but,
>     besides that, they can also merge patches that change the code common
>     to multiple drivers, including the kernel internal API.
> 
> I think we should define Media Subsystem, Media Core and possibly Media
> Community in the glossary but I'd do that after merging this set.

You forgot remote controllers there ;-)

Btw, that's exactly my point: when we enumerate things, we tend to forget
about something, and, when new stuff gets add, we need to remember to
add here.

> 
> >   
> > >   
> > > > +
> > > > +- Subsystem maintainers:
> > > > +    responsible for the subsystem as a whole, with access to the
> > > > +    entire subsystem.
> > > > +
> > > > +    API/ABI changes are done via consensus between subsystem maintainers\ [2]_.
> > > > +
> > > > +    Only subsystem maintainers push changes that affect the userspace
> > > > +    API/ABI. Committers may push ABI/API changes on their commits if they
> > > > +    have approvals from subsystem maintainers.
> > > > +
> > > > +All media committers 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.    
> > > 
> > > Is there a need to mention this? Aren't people generally expected to
> > > follow the process anyway?  
> > 
> > There's a big difference between "generally expected" and "have to agree".
> > The goal here is really to prevent having bad committers as we had in the
> > past on our previous multicommiters model before we moved to git. If this
> > ever have again, by having an explicit agreement, one cannot deny he/she
> > didn't know the rules.  
> 
> Fair enough. Either way, enforment is discretionary so I think this is
> fine -- mistakes tend to happen, to everybody, at least in some extent.

Yeah, mistakes can happen. What we want to cover is intentional misbehavior.

> > > > +
> > > > +.. [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.
> > > > +
> > > > +Media development tree
> > > > +----------------------
> > > > +
> > > > +The main development tree used by the media subsystem is hosted at LinuxTV.org,
> > > > +where we also maintain news about the subsystem, wiki pages and a patchwork
> > > > +instance where we track patches though their lifetime.
> > > > +
> > > > +The main tree used by media developers is at:
> > > > +
> > > > +https://git.linuxtv.org/media.git/
> > > > +
> > > > +.. _Media development workflow:
> > > > +
> > > > +Media development workflow
> > > > +++++++++++++++++++++++++++
> > > > +
> > > > +All changes for the media subsystem must be sent first as e-mails to the    
> > > 
> > > s/must/shall/ ?  
> > 
> > OK.
> >   
> > > > +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 committer(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 media.git ``next`` branch;
> > > > +
> > > > +2. Bug fixes for the current mainline release:
> > > > +
> > > > +   - baseline shall be the latest mainline release or media.git ``fixes``
> > > > +     if changes depend on a fix already merged;
> > > > +
> > > > +3. Bug fixes for the next mainline release:
> > > > +
> > > > +   - baseline shall be a prepatch release (-rcX) or media.git ``fixes``
> > > > +     if changes depend on a fix already merged. It is also
> > > > +     fine to use media.git ``next`` as baseline for such patches if such
> > > > +     patches apply cleanly on ``fixes``.
> > > > +
> > > > +.. 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. Pull request workflow: patches are handled by subsystem maintainers::
> > > > +
> > > > +     +-------+   +---------+   +-------+   +-----------------------+   +---------+
> > > > +     |e-mail |-->|patchwork|-->|pull   |-->|maintainers merge      |-->|media.git|
> > > > +     |to LMML|   |picks it |   |request|   |in media-committers.git|   +---------+
> > > > +     +-------+   +---------+   +-------+   +-----------------------+
> > > > +
> > > > +   For this workflow, pull requests can be generated by committers,
> > > > +   former committers, subsystem maintainers or by trusted long-time
> > > > +   contributors. If you are not in such group, please don't submit
> > > > +   pull requests, as they will not be processed.
> > > > +
> > > > +b. Committers' workflow: patches are handled by media committers::
> > > > +
> > > > +     +-------+   +---------+   +--------------------+   +-----------+   +---------+
> > > > +     |e-mail |-->|patchwork|-->|committers merge at |-->|maintainers|-->|media.git|
> > > > +     |to LMML|   |picks it |   |media-committers.git|   |approval   |   +---------+
> > > > +     +-------+   +---------+   +--------------------+   +-----------+
> > > > +
> > > > +On both workflows, all patches shall be properly reviewed at
> > > > +linux-media@vger.kernel.org (LMML) before being merged at media-committers.git.
> > > > +
> > > > +When patches are picked by patchwork and when merged at media-committers,
> > > > +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    
> > > 
> > > I'd remove the latter comma.  
> > 
> > OK.
> >   
> > >   
> > > > +explain why the errors are false positives.
> > > > +
> > > > +Patches will only be moved to the next stage in those two workflows if they
> > > > +pass on CI or if there are false-positives in the CI reports.
> > > > +
> > > > +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 +187,49 @@ 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, 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, thus such
> > > > +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 to a few hours
> > > > +       for a patch to be picked by patchwork.    
> > > 
> > > I'd just refer to "longer" in the latter case; there are no fixed time
> > > limits anyway.
> > >   
> > 
> > OK.
> >   
> > > > +
> > > > +.. [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 sign, please read
> > > > +Documentation/process/maintainer-pgp-guide.rst.
> > > >  
> > > > -- HDMI CEC:
> > > > -    Hans Verkuil <hverkuil@xs4all.nl>
> > > > +Subsystem 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@xs4all.nl>
> > > > -
> > > > -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> and
> > > > +  - Hans Verkuil <hverkuil@xs4all.nl>
> > > >  
> > > >  Submit Checklist Addendum
> > > >  -------------------------
> > > > @@ -106,18 +244,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 compilance 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 +269,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
> > > >  +++++++++++++++++++++
> > > >  
> > > > @@ -199,7 +336,7 @@ 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:``,    
> > >   
> 



Thanks,
Mauro

Re: [PATCH v4 3/5] docs: media: update maintainer-entry-profile for multi-committers

[Sakari Ailus]

Hi Mauro,

On Fri, Aug 22, 2025 at 11:31:59AM +0200, Mauro Carvalho Chehab wrote:
> Em Fri, 22 Aug 2025 08:59:29 +0000
> Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> 
> > Hi Mauro,
> > 
> > On Fri, Aug 22, 2025 at 10:23:46AM +0200, Mauro Carvalho Chehab wrote:
> > > Em Thu, 21 Aug 2025 12:26:18 +0000
> > > Sakari Ailus <sakari.ailus@iki.fi> escreveu:

...

> > > What about this:
> > > 
> > > <text>
> > > The Linux Media Community (aka: the LinuxTV Community) consist of developers 
> > > who work with the Linux Kernel media subsystem, together with users who
> > > benefit from such develoment and help testing the developed code.  
> > 
> > How about, with slight modifications:
> > 
> > The Linux Media Community (aka: the LinuxTV Community) is formed of
> > developers working on Linux Kernel Media Subsystem, together with users.
> 
> Works for me, although I prefer keep mentioning about the important
> role that users play on help testing drivers.

How about then:

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.

> 
> > 
> > > 
> > > They work on the top of the Media tree, which has code to support a    
> > > variety of devices: stream capture, analog and digital TV streams, cameras,
> > > remote controllers, HDMI CEC and media pipeline control.
> > > 
> > > The Media tree is mainly responsible to be the main source of the
> > > code under development with the contents of those directories:
> > > 
> > >   - drivers/media
> > >   - drivers/staging/media
> > >   - Documentation/admin-guide/media
> > >   - Documentation/driver-api/media
> > >   - Documentation/userspace-api/media
> > >   - Documentation/devicetree/bindings/media/\ [1]_
> > >   - include/media
> > > </text>
> > >   
> > > >   
> > > > >  
> > > > >    - drivers/media
> > > > >    - drivers/staging/media
> > > > > @@ -27,19 +28,158 @@ 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 files.    
> > > > 
> > > > I'd drop " files" as the documentation is split between C source code files
> > > > and ReST nowadays.  
> > > 
> > > OK.
> > >   
> > > > > -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
> > > > > +Due to the size and wide scope of the media subsystem, the media's
> > > > > +maintainership model is to have committers that have a broad knowledge of    
> > > > 
> > > > Maintainership or maintenance?
> > > > 
> > > > s/is to have/recognises/ ?  
> > > 
> > > OK.
> > >    
> > > > > +a specific aspect of the subsystem. It is the committers' 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.
> > > > >  
> > > > > -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).
> > > > > +Media committers
> > > > > +----------------
> > > > > +
> > > > > +In the media subsystem, there are experienced developers who can push
> > > > > +patches directly to the development tree. These developers are called
> > > > > +Media committers and are divided into the following categories:
> > > > > +
> > > > > +- Committers:
> > > > > +    contributors for one or more drivers within the media subsystem.
> > > > > +    They can push changes to the tree that do not affect the core or ABI.    
> > > > 
> > > > Question to Ricardo -- sorry if I already have asked this: can this be
> > > > enforced?
> > > >   
> > > > > +
> > > > > +- Core committers:
> > > > > +    responsible for part of the media core. They are typically
> > > > > +    responsible for one or more drivers within the media subsystem, but, besides
> > > > > +    that, they can also merge patches that change the code common to multiple
> > > > > +    drivers, including the kernel internal API.    
> > > > 
> > > > This doesn't say clearly whether e.g. the V4L2 or MC frameworks are
> > > > included or not. I think they should be and this should be mentioned. Same
> > > > for videobuf2.  
> > > 
> > > The problem of specifying what the core via frameworks, vb2, etc is that
> > > this would require constant maintainance. Core is everything that is not
> > > inside a driver for an specific driver.
> > > 
> > > We called this here as "the code common to multiple drivers". For me it
> > > is clear, but if you have a better generic term, I'm all ears.  
> > 
> > How about:
> > 
> > - Core committers:
> >     responsible for part of the Media Core, including V4L2, Media
> >     controller, Videobuf2, CEC and DVB frameworks. They are typically
> >     responsible for one or more drivers within the Media Subsystem, but,
> >     besides that, they can also merge patches that change the code common
> >     to multiple drivers, including the kernel internal API.
> > 
> > I think we should define Media Subsystem, Media Core and possibly Media
> > Community in the glossary but I'd do that after merging this set.
> 
> You forgot remote controllers there ;-)
> 
> Btw, that's exactly my point: when we enumerate things, we tend to forget
> about something, and, when new stuff gets add, we need to remember to
> add here.

The text above does not imply something isn't part of Media Core even if
not listed. But of course Remote Controller should have been in the above
list. Adding that results in:

- Core committers:
    responsible for part of the Media Core, including V4L2, Media
    controller, Videobuf2, Remote Controller, CEC and DVB frameworks. They
    are typically responsible for one or more drivers within the Media
    Subsystem, but, besides that, they can also merge patches that change
    the code common to multiple drivers, including the kernel internal API.

> 
> > 
> > >   
> > > >   
> > > > > +
> > > > > +- Subsystem maintainers:
> > > > > +    responsible for the subsystem as a whole, with access to the
> > > > > +    entire subsystem.
> > > > > +
> > > > > +    API/ABI changes are done via consensus between subsystem maintainers\ [2]_.
> > > > > +
> > > > > +    Only subsystem maintainers push changes that affect the userspace
> > > > > +    API/ABI. Committers may push ABI/API changes on their commits if they
> > > > > +    have approvals from subsystem maintainers.
> > > > > +
> > > > > +All media committers 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.    
> > > > 
> > > > Is there a need to mention this? Aren't people generally expected to
> > > > follow the process anyway?  
> > > 
> > > There's a big difference between "generally expected" and "have to agree".
> > > The goal here is really to prevent having bad committers as we had in the
> > > past on our previous multicommiters model before we moved to git. If this
> > > ever have again, by having an explicit agreement, one cannot deny he/she
> > > didn't know the rules.  
> > 
> > Fair enough. Either way, enforment is discretionary so I think this is
> > fine -- mistakes tend to happen, to everybody, at least in some extent.
> 
> Yeah, mistakes can happen. What we want to cover is intentional misbehavior.

I agree. I hope this will remain a theoretical possibility though.

-- 
Kind regards,

Sakari Ailus