From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from lahtoruutu.iki.fi (lahtoruutu.iki.fi [185.185.170.37]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 21F513112DA; Thu, 21 Aug 2025 12:27:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=pass smtp.client-ip=185.185.170.37 ARC-Seal:i=2; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755779278; cv=pass; b=YGbULzw3oIb/lJp3H4NGFuMKs0OCHDdArgKikDs9YwAuW2Rp5D2jt8fqRVh7IX82Hp6YxnVpBfclnaq1yxXZV55RGz5+mK9/51raBdQq+5gdp6TwJr/hXmGxoIiwGY5hTXrXlhD/RqLOdp9xwK/D70zr9hdy6H6F6sxi4F828/U= ARC-Message-Signature:i=2; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755779278; c=relaxed/simple; bh=WJ8HAgyY4Ee6cw2CZ3YU3O5mUCSeG3Mm2qq5JK7FSQM=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=k96feAn76P8Se/WZEqwRIva4Mbu281T8nMatpGvnX+7qTWdR0M43H3oxNY47A92LB4cCBg+/dYP1lfT9HJGVAkyeJWTrM1KdbHZE66sSndgk2hLDSBwdKRo2gu4lejlMC3lZH+l8NtU+mgf1IWEMRrEEZjdQ+5LQBlJ4+4k84II= ARC-Authentication-Results:i=2; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=iki.fi; spf=pass smtp.mailfrom=iki.fi; dkim=pass (2048-bit key) header.d=iki.fi header.i=@iki.fi header.b=iqaKSCMW; arc=pass smtp.client-ip=185.185.170.37 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=iki.fi Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=iki.fi Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=iki.fi header.i=@iki.fi header.b="iqaKSCMW" Received: from hillosipuli.retiisi.eu (91-158-51-183.elisa-laajakaista.fi [91.158.51.183]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) (Authenticated sender: sailus) by lahtoruutu.iki.fi (Postfix) with ESMTPSA id 4c72dp2ZkCz49PyC; Thu, 21 Aug 2025 15:27:42 +0300 (EEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iki.fi; s=lahtoruutu; t=1755779262; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=eiQ6uFW+9v2JSH8VQaN26H4EvrYe/TDIOXZiIlCcHOk=; b=iqaKSCMWaUhCBvnYp2Ph5Vby0xvm2E4IhBQnlMoQvZIo+U3jH+bo+xqR+S4NOOoRv6ynmd SvSaxyXWnhwNJF6AlyDexEY8wOV6TZ57p5DYESmCxkYHHeHRpD3rdvjB1vgofMu7oOdFZs b++5SUL/+Nsqi5Q8mbu2qkOzsYfh0IXJ1Lr3LN5zQe8hgEtgsS8xIte9/7/HjJl/33Z0y8 UPSrpNqz8SPKwKmaXPc934R/pmIf/zb8s9JUa4BZxInR4hnVhyIbVtEuCm5PMQv2y3SsuK hXlzhtrCxPnGn3Hp9+yaeJy+ESxdGMHSUf2Jil34wvVY7bBk2qvkKsX0SqMz6Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=iki.fi; s=lahtoruutu; t=1755779262; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=eiQ6uFW+9v2JSH8VQaN26H4EvrYe/TDIOXZiIlCcHOk=; b=wMd15gLyeJRvZoLaTDaNLg9DrLA6q3zpJuZiPy8dW+j09z9H5Tz/R6uroNnv6ARK3mf2p7 d7FmPK0mSIHFBV0qsZwK4US5SWukaZw53UferEZXbj7LAodABnA/CA2y5kmyUBpfP8FaHp f1sNLRie6z1V3AHSEQkOXe2zvP8uDbcbbna1p/6CZ1S45cVsRa9e+sBDPlkkP1m0N09+M0 MBkS6dkKd58t14ffqq+ZIF6zbbHXGCIZKs/vox5vNuEdZEQspNs6PPPvoilBKle4crWSCH iwdfCvRDOAdhdPIzyiaeHWs78RNGmXTFMixbD9epaM8ZZ8wDvOxUYOGuQUbBZg== ARC-Authentication-Results: i=1; ORIGINATING; auth=pass smtp.auth=sailus smtp.mailfrom=sakari.ailus@iki.fi ARC-Seal: i=1; s=lahtoruutu; d=iki.fi; t=1755779262; a=rsa-sha256; cv=none; b=mvCAKOUB3s1N/ycfyMaPDgwoHCxQ/NDOUGUeEicnIBJGFkjr1dFNldJQnoDemC8AcN6mxn DGB28zIbUmXiwO1BnJzf1EXo9uDqU6V8dNSUwuN2MPOUMA+sUE1M4adpMOMdgOCWAMu69P La0BetE6iF1UOll0E23eR76leIxrBBdIxOKnjPyfR7+quE3Hiv5/0t0a0FAg6KfoH1CrXe 02tP2+u/QB+xhRy6J2hMAEqmsB+Do1atovfBa28GVEr7oKeGfp3yFhbotmUEOhBf61FjuU ir1FoWGlnxoaAT4kIqnrSubp6yY87eR++PbogxtMyP8NqvIzGZUesLFRQxsurA== Received: from valkosipuli.retiisi.eu (valkosipuli.local [192.168.4.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (prime256v1) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by hillosipuli.retiisi.eu (Postfix) with ESMTPS id B86DA634C96; Thu, 21 Aug 2025 15:26:17 +0300 (EEST) Date: Thu, 21 Aug 2025 12:26:18 +0000 From: Sakari Ailus To: Mauro Carvalho Chehab Cc: linux-kernel@vger.kernel.org, linux-media@vger.kernel.org, Hans Verkuil , Ricardo Ribalda Subject: Re: [PATCH v4 3/5] docs: media: update maintainer-entry-profile for multi-committers Message-ID: References: <5eed1e4a37d087f401b7bd54b793ea301e511d7e.1733218348.git.mchehab+huawei@kernel.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <5eed1e4a37d087f401b7bd54b793ea301e511d7e.1733218348.git.mchehab+huawei@kernel.org> 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 > Signed-off-by: Hans Verkuil > Reviewed-by: Ricardo Ribalda > --- > .../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 > +For more details about PGP sign, please read > +Documentation/process/maintainer-pgp-guide.rst. > > -- HDMI CEC: > - Hans Verkuil > +Subsystem maintainers > +--------------------- > > -- Media controller drivers: > - Laurent Pinchart > - > -- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers: > - Sakari Ailus > - > -- V4L2 drivers and core V4L2 frameworks: > - Hans Verkuil > - > -The subsystem maintainer is: > - Mauro Carvalho Chehab > - > -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 and > + - Hans Verkuil > > 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