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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

On Thu,  5 Feb 2026 15:32:51 +0100
Hans Verkuil <hverkuil+cisco@kernel.org> wrote:

> Here is v8, based on Mauro's feedback.
> 
> The main changes since v7 are:
> 
> - rename media-committer.rst to media-committers.rst
> - the 'Note' at the start of media-committers.rst is now just a list
>   of additional responsibilies (it made no sense that it was a 'Note').
> - incorporated Mauro's suggestions
> 
> Patch 1/3 updates maintainer-entry-profile.rst: it introduces the
> three Media maintainer levels (Media Driver Maintainer, Media Core Maintainer
> and Media Subsystem Maintainer) and what the responsibilities are.
> 
> Patch 2/3 adds back and updates the list of Media Maintainers that
> disappeared in patch 1/3. Please verify this whether the email
> addresses are the correct ones, and verify that the areas of responsibility
> are correct and that nothing is missing.
> 
> Patch 3/3 adds media-committers.rst: that focusses on the additional
> commit rights that can be granted to a Media Maintainer.
> 
> I have uploaded the documentation with these patches here:
> 
> https://hverkuil.home.xs4all.nl/spec/driver-api/maintainer-entry-profile.html
> https://hverkuil.home.xs4all.nl/spec/driver-api/media-committers.html
> 
> Mauro's feedback for v7 is here:
> 
> https://patchwork.linuxtv.org/project/linux-media/list/?series=21550

Hans, IMO almost ready. Yet, when looking at the html output, there
are some minor things to be improved. As before, sending you a patch
with them.

Feel free to either integrate it on a new version or to place it 
at the end.

-- 
Thanks,
Mauro

---

[PATCH] media maintainership docs: Some additional editorial changes

- standardise “Pull Request” spelling;
- better list URLs that are very confusing at the html output;
- better display "media-committers.git" at html output;
- minor formatting fixes;

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

diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst
index 2c5f1eba5684..c4b6d685cdda 100644
--- a/Documentation/driver-api/media/maintainer-entry-profile.rst
+++ b/Documentation/driver-api/media/maintainer-entry-profile.rst
@@ -79,7 +79,7 @@ maintainers are required, each with their own areas of expertise:
 
     Userspace API/ABI changes are made via consensus among Media Subsystem
     Maintainers\ [2]_. Media Maintainers may include API/ABI changes in
-    their pull requests if they are signed off by all Media Subsystem
+    their Pull Requests if they are signed off by all Media Subsystem
     Maintainers.
 
 All Media Maintainers shall agree with the Kernel development process as
@@ -102,7 +102,7 @@ Maintainer who is handling them and the patch status shall be updated according
 to these rules:
 
 - ``Under Review``: Used if the patch requires a second opinion
-  or when it is part of a pull request;
+  or when it is part of a Pull Request;
 - ``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
@@ -185,25 +185,32 @@ offloading some of the work of the Media Subsystem Maintainers.
 More details about Media Committers' roles and responsibilities can be
 found here: :ref:`Media Committers`.
 
-Media development tree
-----------------------
+Media development sites
+-----------------------
 
-The main development tree used by the media subsystem is hosted at
-https://gitlab.freedesktop.org/linux-media/.
-https://linuxtv.org/ hosts news about the subsystem,
-`wiki <https://www.linuxtv.org/wiki/index.php/Main_Page>`_ pages
-and a `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_
-instance where we track patches though their lifetime.
+The `LinuxTV <https://linuxtv.org/>`_ web site hosts news about the subsystem,
+together with:
 
-The stable tree used by media developers is at:
+- `Wiki pages <https://www.linuxtv.org/wiki/index.php/Main_Page>`_;
+- `Patchwork <https://patchwork.linuxtv.org/project/linux-media/list/>`_;
+- `Linux Media documentation <https://linuxtv.org/docs.php>`_;
+- and more.
 
-https://git.linuxtv.org/media.git/
+The main development trees used by the media subsystem are at:
 
-Patches there are initially committed to the media committers tree:
+- Stable tree:
+  - https://git.linuxtv.org/media.git/
 
-https://gitlab.freedesktop.org/linux-media/media-committers.git
+- Media committers tree:
+  - https://gitlab.freedesktop.org/linux-media/media-committers.git
+
+    Please note that it can be rebased, although only as a last resort.
+
+- Media development trees, including apps and CI:
+
+  - https://git.linuxtv.org/
+  - https://gitlab.freedesktop.org/linux-media/
 
-Please note that the latter can be rebased, although only as a last resort.
 
 .. _Media development workflow:
 
@@ -232,18 +239,18 @@ following baseline for your patch series:
 
 1. Features for the next mainline release:
 
-   - baseline shall be the media-committers.git ``next`` branch;
+   - baseline shall be the ``media-committers.git next`` branch;
 
 2. Bug fixes for the next mainline release:
 
-   - baseline shall be the media-committers.git ``next`` branch. If the
-     changes depend on a fix from the media-committers.git
-     ``fixes`` branch, then you can use that as baseline.
+   - baseline shall be the ``media-committers.git next`` branch. If the
+     changes depend on a fix from the ``media-committers.git fixes``
+     branch, then you can use that as baseline.
 
 3. Bug fixes for the current mainline release (-rcX):
 
    - baseline shall be the latest mainline -rcX release or the
-     media-committers.git ``fixes`` branch if changes depend on a mainline
+     ``media-committers.git fixes`` branch if changes depend on a mainline
      fix that is not yet merged;
 
 .. Note::
@@ -269,8 +276,8 @@ See Documentation/process/index.rst for more details about e-mail submission.
 Once a patch is submitted, it may follow either one of the following
 workflows:
 
-a. Media Maintainers' workflow: Media Maintainers post the PRs, which are
-   handled by the Media Subsystem Maintainers::
+a. Media Maintainers' workflow: Media Maintainers post the Pull Requests,
+   which are handled by the Media Subsystem Maintainers::
 
      +-------+   +------------+   +------+   +-------+   +---------------------+
      |e-mail |-->|picked up by|-->|code  |-->|pull   |-->|Subsystem Maintainers|
@@ -278,9 +285,9 @@ a. Media Maintainers' workflow: Media Maintainers post the PRs, which are
      |       |   |            |   |      |   |       |   |media-committers.git |
      +-------+   +------------+   +------+   +-------+   +---------------------+
 
-   For this workflow, pull requests are generated by Media Maintainers with
+   For this workflow, Pull Requests are generated by Media Maintainers with
    Patchwork access.  If you do not have Patchwork access, then please don't
-   submit pull requests, as they will not be processed.
+   submit Pull Requests, as they will not be processed.
 
 b. Media Committers' workflow: patches are handled by Media Maintainers with
    commit rights::
@@ -300,9 +307,9 @@ Patches will only be moved to the next stage in these two workflows if they
 pass on Media CI or if there are false-positives in the Media CI reports.
 
 For both workflows, all patches shall be properly reviewed at
-linux-media@vger.kernel.org (LMML) before being merged in media-committers.git.
-Media patches will be reviewed in a timely manner by the maintainers and
-reviewers as listed in the MAINTAINERS file.
+linux-media@vger.kernel.org (LMML) before being merged in
+``media-committers.git``. Media patches will be reviewed in a timely manner
+by the maintainers and reviewers as listed in the MAINTAINERS file.
 
 Media Maintainers shall request reviews from other Media Maintainers and
 developers where applicable, i.e. because those developers have more
@@ -352,15 +359,15 @@ and such a patch will be rejected.
 Authentication for pull and merge requests
 ++++++++++++++++++++++++++++++++++++++++++
 
-The authenticity of developers submitting pull requests and merge requests
+The authenticity of developers submitting Pull Requests and merge requests
 shall be validated by using the Linux Kernel Web of Trust, with PGP signing
 at some moment. See: :ref:`kernel_org_trust_repository`.
 
-With the pull request workflow, pull requests shall use PGP-signed tags.
+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
+rights will be granted to the gitlab instance used by the
+``media-committers.git`` tree, after receiving the e-mail documented in
 :ref:`media-committer-agreement`.
 
 For more details about PGP signing, please read
diff --git a/Documentation/driver-api/media/media-committers.rst b/Documentation/driver-api/media/media-committers.rst
index fd2f30700958..4ca2ac8d8c7b 100644
--- a/Documentation/driver-api/media/media-committers.rst
+++ b/Documentation/driver-api/media/media-committers.rst
@@ -21,7 +21,7 @@ and the Linux Media community.
 As Media Committer you have the following additional responsibilities:
 
 1. Patches you authored must have a ``Signed-off-by``, ``Reviewed-by``
-   or ``Acked-by`` from another Media Maintainer;
+   or ``Acked-by`` from another Media Maintainer before your merge;
 2. If a patch introduces a regression, then that must be corrected as soon
    as possible. Typically the patch is either reverted, or an additional
    patch is committed to fix the regression;
@@ -181,7 +181,7 @@ Maintainer not trusting the Media Maintainer or Committer anymore is enough
 to revoke their maintenance, Patchwork grants and/or commit rights.
 
 Having commit rights revoked doesn't prevent Media Maintainers to keep
-contributing to the subsystem either via the pull request or via email workflow
+contributing to the subsystem either via the Pull Request or via email workflow
 as documented at the :ref:`Media development workflow`.
 
 If a maintainer is inactive for more than a couple of Kernel cycles,