Message-ID: <26a44a31-3ab3-40f0-9ef2-e4bb6484a254@kernel.org>
Date: Thu, 5 Feb 2026 12:52:35 +0100
From: Hans Verkuil <hverkuil+cisco@...nel.org>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
 Linux Doc Mailing List <linux-doc@...r.kernel.org>,
 Mauro Carvalho Chehab <mchehab@...nel.org>
Cc: linux-kernel@...r.kernel.org, linux-media@...r.kernel.org,
 Bryan O'Donoghue <bryan.odonoghue@...aro.org>,
 Jonathan Corbet <corbet@....net>,
 Laurent Pinchart <laurent.pinchart@...asonboard.com>,
 Nicolas Dufresne <nicolas.dufresne@...labora.com>,
 Ricardo Ribalda <ribalda@...omium.org>,
 Sakari Ailus <sakari.ailus@...ux.intel.com>, Sean Young <sean@...s.org>
Subject: Re: [PATCH 2/2] docs: media: media-committer: do some editorial
 changes

Hi Mauro,

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

Let me know what you think of my suggestions.

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

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

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

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

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

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

And change point 4 to this:

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

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

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

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


Regards,

	Hans

Powered by blists - more mailing lists