docs: media: multicommitters model documentation
v6 cover docs: media: multicommitters model documentation
I finally had time to continue Mauro's work on documenting the multicommitter model.
It is a fairly big overhaul of v5. The most significant change is that I extended the maintainer profile substantially. A lot of the committer requirements from the v5 of media-committer.rst were actually maintainer requirements, so I moved those over to the maintainer profile.
Patch 1/3 updates maintainer-entry-profile.rst: it introduces the three Media maintainer levels (Media Maintainer, Media Core Maintainer and Media Subsystem Maintainer) and what the responsibilities are.
Patch 2/3 adds media-committer.rst: that focusses on the additional commit rights that can be granted to a Media Maintainer.
Patch 3/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.
It feels much more consistent to me, I'm looking forward to the review comments.
I have uploaded the documentation with these patches here:
https://hverkuil.home.xs4all.nl/spec/driver-api/maintainer-entry-profile.html
https://hverkuil.home.xs4all.nl/spec/driver-api/media-committer.html
Regards,
Hans
Hans Verkuil (1):
docs: media: document Media Maintainers
Mauro Carvalho Chehab (2):
docs: media: update maintainer-entry-profile for multi-committers
docs: media: document media multi-committers rules and process
Documentation/driver-api/media/index.rst | 1 + .../media/maintainer-entry-profile.rst | 407 +++++++++++++++--- .../driver-api/media/media-committer.rst | 196 +++++++++ 3 files changed, 548 insertions(+), 56 deletions(-) create mode 100644 Documentation/driver-api/media/media-committer.rst
Signature · 1 line
2.51.0
PATCH v6 1/3 docs: media: update maintainer-entry-profile for multi-committers
From: Mauro Carvalho Chehab <[email protected]>
As the media subsystem will experiment with a multi-committers model, update the Maintainer's entry profile to the new rules.
--- .../media/maintainer-entry-profile.rst | 368 +++++++++++++++--- 1 file changed, 308 insertions(+), 60 deletions(-)
Documentation/driver-api/media/maintainer-entry-profile.rst +308 -60
@@ -4,19 +4,25 @@ Media Subsystem Profile Overview -------- -The media subsystem covers support for a variety of devices: stream -capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC -and media pipeline control. +The Linux Media Community (aka: the LinuxTV Community) is formed of +developers working on Linux Kernel Media Subsystem, together with users +who also play an important role in testing the code. -It covers, mainly, the contents of those directories: +The Media Subsystem has code to support a wide variety of media-related +devices: stream capture, analog and digital TV streams, cameras, +video codecs, video processing (resizers, etc.), radio, remote controllers, +HDMI CEC and media pipeline control. + +The Media Subsystem consists of the following directories in the kernel +tree: - drivers/media - drivers/staging/media + - include/media + - Documentation/devicetree/bindings/media/\ [1]_ - Documentation/admin-guide/media - Documentation/driver-api/media - Documentation/userspace-api/media - - Documentation/devicetree/bindings/media/\ [1]_ - - include/media .. [1] Device tree bindings are maintained by the OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers
@@ -27,19 +33,264 @@ It covers, mainly, the contents of those directories: Both media userspace and Kernel APIs are documented and the documentation must be kept in sync with the API changes. It means that all patches that add new features to the subsystem must also bring changes to the -corresponding API files. +corresponding API documentation. -Due to the size and wide scope of the media subsystem, media's -maintainership model is to have sub-maintainers that have a broad -knowledge of a specific aspect of the subsystem. It is the sub-maintainers' -task to review the patches, providing feedback to users if the patches are -following the subsystem rules and are properly using the media kernel and -userspace APIs. +A small subsystem will typically consist of driver maintainers (as listed +in the MAINTAINERS file) and one or two subsystem maintainers who merge +the patches when ready, maintain the subsystem core code and make the pull +requests to Linus. Due to the size and wide scope of the Media Subsystem +this does not scale and more maintainance layers are needed. -Patches for the media subsystem must be sent to the media mailing list -at [email protected] 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 Maintainers +----------------- + +The media subsystem has three layers of media maintainers: + +- Media Maintainer: + Responsible for a group of drivers within the Media Subsystem. Typically + these are all drivers that have something in common, e.g. codec drivers + or drivers from the same vendor. Media Maintainers provide feedback if the + patches are not following the subsystem rules, or are not using the + media kernel or userspace APIs correctly, or have poor code quality. They + also keep patchwork up to date, decide when patches are ready for merging, + and create Pull Requests for the Media Subsystem Maintainers to merge. + + A Media Maintainer 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). + +- Media Core Maintainer: + Media Maintainers who are also responsible for one or more media core + frameworks. + + Core framework changes are done via consensus between the relevant Media + Core Maintainers. Media Maintainers may include core framework changes in + their Pull Requests if they are signed off by the relevant Media Core + Maintainers. + +- Media Subsystem Maintainers: + Responsible for the subsystem as a whole, with access to the + entire subsystem. Responsible for merging Pull Requests from other + Media Maintainers. + + Userspace API/ABI changes are done via consensus between Media Subsystem + Maintainers\ [2]_. Media (Core) Maintainers may include API/ABI changes in + their Pull Requests if they are signed off by the all Media Subsystem + Maintainers. + +All Media Maintainers shall explicitly agree with the Kernel development process +as described at Documentation/process/index.rst and to the Kernel +development rules inside the Kernel documentation, including its code of +conduct. + +All Media Maintainers shall ensure that patchwork will reflect the current +status, e.g. patches shall be delegated to the Media Maintainer who is +handling them and the patch status shall be updated according to these rules: + +- ``Under Review``: Used if the patch requires a second opinion + or when it is part of a pull request; +- ``Accepted``: Once a patch is merged in the multi-committer tree. +- ``Superseded``: There is a newer version of the patch posted to the + mailing list. +- ``Duplicated``: There was another patch doing the same thing from someone + else that was accepted. +- ``Not Applicable``: Use for patch series that are not merged at media.git + tree (e.g. drm, dmabuf, upstream merge, etc.) but were cross-posted to the + linux-media mailing list. + +If the Media Maintainer decides not to accept a patch, then reply by email to +the patch authors, explaining why it is not accepted, and patchwork shall be +updated accordingly with either: + +- ``Changes Requested``: if a new revision was requested; +- ``Rejected``: if the proposed change is not acceptable at all. + +.. Note:: + + Patchwork supports a couple of clients to help semi-automating + status updates via its REST interface: + + https://patchwork.readthedocs.io/en/latest/usage/clients/ + +Media Maintainers are reachable via the #linux-media IRC channel at OFTC. + +.. [2] Everything that would break backward compatibility with existing + non-kernel code are API/ABI changes. This includes ioctl and sysfs + interfaces, v4l2 controls, and their behaviors. + +Becoming a Media Maintainer +--------------------------- + +The most important aspect of volunteering to be a Media Maintainer is that you +have demonstrated the ability to give good code reviews. So we are looking for +whether or not we think you will be good at doing that. + +As such, potential maintainers must earn enough credibility and trust from the +Linux Media Community. To do that, developers shall be familiar with the open +source model and have been active in the Linux Kernel community for some time, +and, in particular, in the media subsystem. + +In addition to actually making the code changes, you are basically +demonstrating your: + +- commitment to the project; +- ability to collaborate with the team and communicate well; +- understand of how upstream and the Linux Media Community work + (policies, processes for testing, code review, ...) +- reasonable knowledge about: + + - the Kernel development process: + Documentation/process/index.rst + + - the Media development profile: + Documentation/driver-api/media/maintainer-entry-profile.rst + +- understanding of the projects' code base and coding style; +- ability to provide feedback to the patch authors; +- ability to judge when a patch might be ready for review and to submit; +- ability to write good code (last but certainly not least). + +Developers that desire to become maintainers are encouraged to participate +at the yearly Linux Media Summit, typically co-located with a Linux related +conference. These summits will be announced at the linux-media mailing list. + +If you are doing such tasks and have become a valued developer, an +existing Media Maintainer can nominate you to the Media Subsystem Maintainers. + +The ultimate responsibility for accepting a nominated maintainer is up to +the subsystem's maintainers. The nominated maintainer must have earned a trust +relationship with all Media Subsystem Maintainers, as, by becoming Media +Maintainer, you will take over part of their maintenance tasks. + +Media Committers +---------------- + +Experienced and trusted Media (Core) Maintainers may be granted commit rights +which allow them to directly push patches to the media development tree instead +of posting a Pull Request for the Media Subsystem Maintainers. This helps +offloading some of the work of the Media Subsystem Maintainers. + +Media development tree +---------------------- + +The main development tree used by the media subsystem is hosted at +gitlab.freedesktop.org. LinuxTV.org hosts 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://gitlab.freedesktop.org/linux-media/media-committers.git + +Please note that this tree can be rebased, although only as a last resort. + +.. _Media development workflow: + +Media development workflow +++++++++++++++++++++++++++ + +All changes for the media subsystem shall be sent first as e-mails to the +media mailing list, following the process documented at +Documentation/process/index.rst. + +It means that patches shall be submitted as plain text only via e-mail to [email protected] (aka: LMML). While subscription is not mandatory, +you can find details about how to subscribe to it and to see its archives at: + + https://subspace.kernel.org/vger.kernel.org.html + +Emails with HTML will be automatically rejected by the mail server. + +It could be wise to also copy the Media Maintainer(s). You should use +``scripts/get_maintainers.pl`` to identify whom else needs to be copied. +Please always copy driver's authors and maintainers. + +To minimize the chance of merge conflicts for your patch series, and make +easier to backport patches to stable Kernels, we recommend that you use the +following baseline for your patch series: + +1. Features for the next mainline release: + + - baseline shall be the media-committers.git ``next`` branch; + +2. Bug fixes for the next mainline release: + + - baseline shall be the media-committers.git ``next`` branch. If the + changes depend on a fix from the media-committers.git + ``fixes`` branch, then you can use that as baseline. + +3. Bug fixes for the current mainline release (-rcX): + + - baseline shall be the latest mainline -rcX release or the + media-committers.git ``fixes`` branch if changes depend on a mainline + fix that is not yet merged; + +.. Note:: + + See https://www.kernel.org/category/releases.html for an overview + about Kernel release types. + +Patches with fixes shall have: + +- a ``Fixes:`` tag pointing to the first commit that introduced the bug; +- when applicable, a ``Cc: [email protected]``. + +Patches that were fixing bugs publicly reported by someone at the [email protected] mailing list shall have: + +- a ``Reported-by:`` tag immediately followed by a ``Closes:`` tag. + +Patches that change API shall update documentation accordingly at the +same patch series. + +See Documentation/process/index.rst for more details about e-mail submission. + +Once a patch is submitted, it may follow either one of the following +workflows: + +a. Media Maintainers' workflow: Media Maintainers post the PRs, which + are handled by the Media Subsystem Maintainers:: + + +-------+ +------------+ +------+ +-------+ +----------------------------+ + |e-mail |-->|picked up by|-->|code |-->|pull |-->|Subsystem Maintainers merge | + |to LMML| |patchwork | |review| |request| |in media-committers.git | + +-------+ +------------+ +------+ +-------+ +----------------------------+ + + For this workflow, pull requests are generated by Media Maintainers. + If you are not a Media Maintainer, then please don't submit pull requests, + as they will not be processed. + +b. Media Committers' workflow: patches are handled by Media Maintainers with + commit rights:: + + +-------+ +------------+ +------+ +--------------------------+ + |e-mail |-->|picked up by|-->|code |-->|Media Committers merge in | + |to LMML| |patchwork | |review| |media-committers.git | + +-------+ +------------+ +------+ +--------------------------+ + +When patches are picked up by patchwork and when merged at media-committers, +Media CI bots will check for errors and may provide e-mail feedback about +patch problems. When this happens, the patch submitter must fix them or +explain why the errors are false positives. + +Patches will only be moved to the next stage in these two workflows if they +pass on Media CI or if there are false-positives in the Media CI reports. + +For both workflows, all patches shall be properly reviewed at [email protected] (LMML) before being merged in media-committers.git. +Media patches will be reviewed in a timely manner by the maintainers and +reviewers as listed in the MAINTAINERS file. + +Media Maintainers shall request reviews from other Media Maintainers and +developers where applicable, i.e. because those developers have more +knowledge about some areas that are changed by a patch. + +There shall be no open issues or unresolved or conflicting feedback +from anyone. Clear them up first. Defer to the Media Subsystem +Maintainers if needed. + +Failures during e-mail submission ++++++++++++++++++++++++++++++++++ Media's workflow is heavily based on Patchwork, meaning that, once a patch is submitted, the e-mail will first be accepted by the mailing list
@@ -47,51 +298,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 a longer time + 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 <[email protected]> +For more details about PGP sign, please read +Documentation/process/maintainer-pgp-guide.rst. -- HDMI CEC: - Hans Verkuil <[email protected]> +Subsystem Media Maintainers +--------------------------- -- Media controller drivers: - Laurent Pinchart <[email protected]> - -- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers: - Sakari Ailus <[email protected]> - -- V4L2 drivers and core V4L2 frameworks: - Hans Verkuil <[email protected]> - -The subsystem maintainer is: - Mauro Carvalho Chehab <[email protected]> - -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 <[email protected]> + - Hans Verkuil <[email protected]> Submit Checklist Addendum -------------------------
@@ -106,18 +355,15 @@ that should be used in order to check if the drivers are properly implementing the media APIs: ==================== ======================================================= -Type Tool +Type Utility ==================== ======================================================= -V4L2 drivers\ [3]_ ``v4l2-compliance`` +V4L2 drivers\ [5]_ ``v4l2-compliance`` V4L2 virtual drivers ``contrib/test/test-media`` CEC drivers ``cec-compliance`` ==================== ======================================================= -.. [3] The ``v4l2-compliance`` also covers the media controller usage inside - V4L2 drivers. - -Other compliance tools are under development to check other parts of the -subsystem. +.. [5] The ``v4l2-compliance`` utility also covers the media controller usage + inside V4L2 drivers. Those tests need to pass before the patches go upstream.
@@ -134,6 +380,8 @@ Where the check script is:: Be sure to not introduce new warnings on your patches without a very good reason. +Please see `Media development workflow`_ for e-mail submission rules. + Style Cleanup Patches +++++++++++++++++++++
@@ -183,23 +431,23 @@ In particular, we accept lines with more than 80 columns: Key Cycle Dates --------------- -New submissions can be sent at any time, but if they intend to hit the +New submissions can be sent at any time, but if they are intended to hit the next merge window they should be sent before -rc5, and ideally stabilized in the linux-media branch by -rc6. Review Cadence -------------- -Provided that your patch is at https://patchwork.linuxtv.org, it should +Provided that your patch has landed in https://patchwork.linuxtv.org, it should be sooner or later handled, so you don't need to re-submit a patch. -Except for bug fixes, we don't usually add new patches to the development -tree between -rc6 and the next -rc1. +Except for important bug fixes, we don't usually add new patches to the +development tree between -rc6 and the next -rc1. Please notice that the media subsystem is a high traffic one, so it could take a while for us to be able to review your patches. Feel free to ping if you don't get a feedback in a couple of weeks or to ask -other developers to publicly add Reviewed-by and, more importantly, +other developers to publicly add ``Reviewed-by:`` and, more importantly, ``Tested-by:`` tags. Please note that we expect a detailed description for ``Tested-by:``,
Signature · 1 line
2.51.0
Re: [PATCHv6 1/3] docs: media: update maintainer-entry-profile for multi-committers
Quoted 8 lines · Hans Verkuil
From: Mauro Carvalho Chehab <[email protected]>
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 <[email protected]>Reviewed-by Ricardo Ribalda <[email protected]>Signed-off-by Hans Verkuil <[email protected]>
I've read it and I only have some tiny nits, looks great.
Quoted 97 lines
--- .../media/maintainer-entry-profile.rst | 368 +++++++++++++++--- 1 file changed, 308 insertions(+), 60 deletions(-)Documentation/driver-api/media/maintainer-entry-profile.rst +52
-17@@ -4,19 +4,25 @@ Media Subsystem Profile Overview -------- -The media subsystem covers support for a variety of devices: stream -capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC -and media pipeline control. +The Linux Media Community (aka: the LinuxTV Community) is formed of +developers working on Linux Kernel Media Subsystem, together with users +who also play an important role in testing the code. -It covers, mainly, the contents of those directories: +The Media Subsystem has code to support a wide variety of media-related +devices: stream capture, analog and digital TV streams, cameras, +video codecs, video processing (resizers, etc.), radio, remote controllers, +HDMI CEC and media pipeline control. + +The Media Subsystem consists of the following directories in the kernel +tree: - drivers/media - drivers/staging/media + - include/media + - Documentation/devicetree/bindings/media/\ [1]_ - Documentation/admin-guide/media - Documentation/driver-api/media - Documentation/userspace-api/media - - Documentation/devicetree/bindings/media/\ [1]_ - - include/media .. [1] Device tree bindings are maintained by the OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers@@ -27,19 +33,264 @@ It covers, mainly, the contents of those directories: Both media userspace and Kernel APIs are documented and the documentation must be kept in sync with the API changes. It means that all patches that add new features to the subsystem must also bring changes to the -corresponding API files. +corresponding API documentation. -Due to the size and wide scope of the media subsystem, media's -maintainership model is to have sub-maintainers that have a broad -knowledge of a specific aspect of the subsystem. It is the sub-maintainers' -task to review the patches, providing feedback to users if the patches are -following the subsystem rules and are properly using the media kernel and -userspace APIs. +A small subsystem will typically consist of driver maintainers (as listed +in the MAINTAINERS file) and one or two subsystem maintainers who merge +the patches when ready, maintain the subsystem core code and make the pull +requests to Linus. Due to the size and wide scope of the Media Subsystem +this does not scale and more maintainance layers are needed. -Patches for the media subsystem must be sent to the media mailing list -at [email protected] 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 Maintainers +----------------- + +The media subsystem has three layers of media maintainers: + +- Media Maintainer: + Responsible for a group of drivers within the Media Subsystem. Typically + these are all drivers that have something in common, e.g. codec drivers + or drivers from the same vendor. Media Maintainers provide feedback if the + patches are not following the subsystem rules, or are not using the + media kernel or userspace APIs correctly, or have poor code quality. They + also keep patchwork up to date, decide when patches are ready for merging, + and create Pull Requests for the Media Subsystem Maintainers to merge. + + A Media Maintainer 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). + +- Media Core Maintainer: + Media Maintainers who are also responsible for one or more media core + frameworks. + + Core framework changes are done via consensus between the relevant Media + Core Maintainers. Media Maintainers may include core framework changes in + their Pull Requests if they are signed off by the relevant Media Core + Maintainers. + +- Media Subsystem Maintainers: + Responsible for the subsystem as a whole, with access to the + entire subsystem. Responsible for merging Pull Requests from other + Media Maintainers. + + Userspace API/ABI changes are done via consensus between Media Subsystem
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 87
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +10
-0+ Maintainers\ [2]_. Media (Core) Maintainers may include API/ABI changes in + their Pull Requests if they are signed off by the all Media Subsystem + Maintainers. + +All Media Maintainers shall explicitly agree with the Kernel development process +as described at Documentation/process/index.rst and to the Kernel +development rules inside the Kernel documentation, including its code of +conduct. + +All Media Maintainers shall ensure that patchwork will reflect the current
How about making patchwork a link to our patchwork. Note that patchwork is mentioned a few times in this file, all of them could be a link.
Quoted 59 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +59
-0+status, e.g. patches shall be delegated to the Media Maintainer who is +handling them and the patch status shall be updated according to these rules: + +- ``Under Review``: Used if the patch requires a second opinion + or when it is part of a pull request; +- ``Accepted``: Once a patch is merged in the multi-committer tree. +- ``Superseded``: There is a newer version of the patch posted to the + mailing list. +- ``Duplicated``: There was another patch doing the same thing from someone + else that was accepted. +- ``Not Applicable``: Use for patch series that are not merged at media.git + tree (e.g. drm, dmabuf, upstream merge, etc.) but were cross-posted to the + linux-media mailing list. + +If the Media Maintainer decides not to accept a patch, then reply by email to +the patch authors, explaining why it is not accepted, and patchwork shall be +updated accordingly with either: + +- ``Changes Requested``: if a new revision was requested; +- ``Rejected``: if the proposed change is not acceptable at all. + +.. Note:: + + Patchwork supports a couple of clients to help semi-automating + status updates via its REST interface: + + https://patchwork.readthedocs.io/en/latest/usage/clients/ + +Media Maintainers are reachable via the #linux-media IRC channel at OFTC. + +.. [2] Everything that would break backward compatibility with existing + non-kernel code are API/ABI changes. This includes ioctl and sysfs + interfaces, v4l2 controls, and their behaviors. + +Becoming a Media Maintainer +--------------------------- + +The most important aspect of volunteering to be a Media Maintainer is that you +have demonstrated the ability to give good code reviews. So we are looking for +whether or not we think you will be good at doing that. + +As such, potential maintainers must earn enough credibility and trust from the +Linux Media Community. To do that, developers shall be familiar with the open +source model and have been active in the Linux Kernel community for some time, +and, in particular, in the media subsystem. + +In addition to actually making the code changes, you are basically +demonstrating your: + +- commitment to the project; +- ability to collaborate with the team and communicate well; +- understand of how upstream and the Linux Media Community work + (policies, processes for testing, code review, ...) +- reasonable knowledge about: + + - the Kernel development process: + Documentation/process/index.rst + + - the Media development profile:
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 156
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +10
-0+ 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 maintainers are encouraged to participate +at the yearly Linux Media Summit, typically co-located with a Linux related +conference. These summits will be announced at the linux-media mailing list.
These summits are announced on the linux-media mailing list.
Quoted 13 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +13
-0+ +If you are doing such tasks and have become a valued developer, an +existing Media Maintainer can nominate you to the Media Subsystem Maintainers. + +The ultimate responsibility for accepting a nominated maintainer is up to +the subsystem's maintainers. The nominated maintainer must have earned a trust +relationship with all Media Subsystem Maintainers, as, by becoming Media +Maintainer, you will take over part of their maintenance tasks. + +Media Committers +---------------- + +Experienced and trusted Media (Core) Maintainers may be granted commit rights
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 179
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +10
-0+which allow them to directly push patches to the media development tree instead +of posting a Pull Request for the Media Subsystem Maintainers. This helps +offloading some of the work of the Media Subsystem Maintainers. + +Media development tree +---------------------- + +The main development tree used by the media subsystem is hosted at +gitlab.freedesktop.org. LinuxTV.org hosts news about the subsystem, wiki pages +and a patchwork instance where we track patches though their lifetime.
Should all be links (LinuxTV.org, patchwork, wiki, gitlab.freedesktop.org).
Quoted 17 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +17
-0+ +The main tree used by media developers is at: + +https://gitlab.freedesktop.org/linux-media/media-committers.git + +Please note that this tree can be rebased, although only as a last resort. + +.. _Media development workflow: + +Media development workflow +++++++++++++++++++++++++++ + +All changes for the media subsystem shall be sent first as e-mails to the +media mailing list, following the process documented at +Documentation/process/index.rst. + +It means that patches shall be submitted as plain text only via e-mail to
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 206
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +10
-0[email protected] (aka: LMML). While subscription is not mandatory, +you can find details about how to subscribe to it and to see its archives at: + + https://subspace.kernel.org/vger.kernel.org.html + +Emails with HTML will be automatically rejected by the mail server. + +It could be wise to also copy the Media Maintainer(s). You should use +``scripts/get_maintainers.pl`` to identify whom else needs to be copied. +Please always copy driver's authors and maintainers.
git config for using scripts/get_maintainers.pl is useful
Quoted 234 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +127
-43+ +To minimize the chance of merge conflicts for your patch series, and make +easier to backport patches to stable Kernels, we recommend that you use the +following baseline for your patch series: + +1. Features for the next mainline release: + + - baseline shall be the media-committers.git ``next`` branch; + +2. Bug fixes for the next mainline release: + + - baseline shall be the media-committers.git ``next`` branch. If the + changes depend on a fix from the media-committers.git + ``fixes`` branch, then you can use that as baseline. + +3. Bug fixes for the current mainline release (-rcX): + + - baseline shall be the latest mainline -rcX release or the + media-committers.git ``fixes`` branch if changes depend on a mainline + fix that is not yet merged; + +.. Note:: + + See https://www.kernel.org/category/releases.html for an overview + about Kernel release types. + +Patches with fixes shall have: + +- a ``Fixes:`` tag pointing to the first commit that introduced the bug; +- when applicable, a ``Cc: [email protected]``. + +Patches that were fixing bugs publicly reported by someone at the [email protected] mailing list shall have: + +- a ``Reported-by:`` tag immediately followed by a ``Closes:`` tag. + +Patches that change API shall update documentation accordingly at the +same patch series. + +See Documentation/process/index.rst for more details about e-mail submission. + +Once a patch is submitted, it may follow either one of the following +workflows: + +a. Media Maintainers' workflow: Media Maintainers post the PRs, which + are handled by the Media Subsystem Maintainers:: + + +-------+ +------------+ +------+ +-------+ +----------------------------+ + |e-mail |-->|picked up by|-->|code |-->|pull |-->|Subsystem Maintainers merge | + |to LMML| |patchwork | |review| |request| |in media-committers.git | + +-------+ +------------+ +------+ +-------+ +----------------------------+ + + For this workflow, pull requests are generated by Media Maintainers. + If you are not a Media Maintainer, then please don't submit pull requests, + as they will not be processed. + +b. Media Committers' workflow: patches are handled by Media Maintainers with + commit rights:: + + +-------+ +------------+ +------+ +--------------------------+ + |e-mail |-->|picked up by|-->|code |-->|Media Committers merge in | + |to LMML| |patchwork | |review| |media-committers.git | + +-------+ +------------+ +------+ +--------------------------+ + +When patches are picked up by patchwork and when merged at media-committers, +Media CI bots will check for errors and may provide e-mail feedback about +patch problems. When this happens, the patch submitter must fix them or +explain why the errors are false positives. + +Patches will only be moved to the next stage in these two workflows if they +pass on Media CI or if there are false-positives in the Media CI reports. + +For both workflows, all patches shall be properly reviewed at [email protected] (LMML) before being merged in media-committers.git. +Media patches will be reviewed in a timely manner by the maintainers and +reviewers as listed in the MAINTAINERS file. + +Media Maintainers shall request reviews from other Media Maintainers and +developers where applicable, i.e. because those developers have more +knowledge about some areas that are changed by a patch. + +There shall be no open issues or unresolved or conflicting feedback +from anyone. Clear them up first. Defer to the Media Subsystem +Maintainers if needed. + +Failures during e-mail submission ++++++++++++++++++++++++++++++++++ Media's workflow is heavily based on Patchwork, meaning that, once a patch is submitted, the e-mail will first be accepted by the mailing list@@ -47,51 +298,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 a longer time + 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 <[email protected]> +For more details about PGP sign, please read +Documentation/process/maintainer-pgp-guide.rst. -- HDMI CEC: - Hans Verkuil <[email protected]> +Subsystem Media Maintainers +--------------------------- -- Media controller drivers: - Laurent Pinchart <[email protected]> - -- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers: - Sakari Ailus <[email protected]> - -- V4L2 drivers and core V4L2 frameworks: - Hans Verkuil <[email protected]> - -The subsystem maintainer is: - Mauro Carvalho Chehab <[email protected]> - -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 <[email protected]> + - Hans Verkuil <[email protected]> Submit Checklist Addendum -------------------------@@ -106,18 +355,15 @@ that should be used in order to check if the drivers are properly implementing the media APIs: ==================== ======================================================= -Type Tool +Type Utility ==================== ======================================================= -V4L2 drivers\ [3]_ ``v4l2-compliance`` +V4L2 drivers\ [5]_ ``v4l2-compliance`` V4L2 virtual drivers ``contrib/test/test-media`` CEC drivers ``cec-compliance`` ==================== ======================================================= -.. [3] The ``v4l2-compliance`` also covers the media controller usage inside - V4L2 drivers. - -Other compliance tools are under development to check other parts of the -subsystem. +.. [5] The ``v4l2-compliance`` utility also covers the media controller usage + inside V4L2 drivers. Those tests need to pass before the patches go upstream.@@ -134,6 +380,8 @@ Where the check script is:: Be sure to not introduce new warnings on your patches without a very good reason. +Please see `Media development workflow`_ for e-mail submission rules. + Style Cleanup Patches +++++++++++++++++++++@@ -183,23 +431,23 @@ In particular, we accept lines with more than 80 columns: Key Cycle Dates --------------- -New submissions can be sent at any time, but if they intend to hit the +New submissions can be sent at any time, but if they are intended to hit the next merge window they should be sent before -rc5, and ideally stabilized in the linux-media branch by -rc6. Review Cadence -------------- -Provided that your patch is at https://patchwork.linuxtv.org, it should +Provided that your patch has landed in https://patchwork.linuxtv.org, it should be sooner or later handled, so you don't need to re-submit a patch. -Except for bug fixes, we don't usually add new patches to the development -tree between -rc6 and the next -rc1. +Except for important bug fixes, we don't usually add new patches to the +development tree between -rc6 and the next -rc1. Please notice that the media subsystem is a high traffic one, so it could take a while for us to be able to review your patches. Feel free to ping if you don't get a feedback in a couple of weeks or to ask -other developers to publicly add Reviewed-by and, more importantly, +other developers to publicly add ``Reviewed-by:`` and, more importantly, ``Tested-by:`` tags. Please note that we expect a detailed description for ``Tested-by:``,Signature · 1 line
2.51.0
Re: [PATCHv6 1/3] docs: media: update maintainer-entry-profile for multi-committers
Quoted 11 lines · Sean Young
Quoted 8 lines · Hans Verkuil
From: Mauro Carvalho Chehab <[email protected]>
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 <[email protected]>Reviewed-by Ricardo Ribalda <[email protected]>Signed-off-by Hans Verkuil <[email protected]>I've read it and I only have some tiny nits, looks great.
Thank you!
Quoted 3 lines
Reviewed-by Sean Young <[email protected]>
<snip>
Quoted 5 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 206
Quoted 3 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +3
-0+It could be wise to also copy the Media Maintainer(s). You should use +``scripts/get_maintainers.pl`` to identify whom else needs to be copied. +Please always copy driver's authors and maintainers.git config for using
scripts/get_maintainers.plis useful
I'm not sure I understand what you meant with this.
Regards,
Hans
Re: [PATCHv6 1/3] docs: media: update maintainer-entry-profile for multi-committers
Quoted 19 lines · Hans Verkuil
Quoted 11 lines · Sean Young
Quoted 8 lines · Hans Verkuil
From: Mauro Carvalho Chehab <[email protected]>
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 <[email protected]>Reviewed-by Ricardo Ribalda <[email protected]>Signed-off-by Hans Verkuil <[email protected]>I've read it and I only have some tiny nits, looks great.
Thank you!
Quoted 3 lines
Reviewed-by Sean Young <[email protected]>
Quoted 8 lines
<snip>
Quoted 5 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 206
Quoted 3 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +3
-0+It could be wise to also copy the Media Maintainer(s). You should use +``scripts/get_maintainers.pl`` to identify whom else needs to be copied. +Please always copy driver's authors and maintainers.git config for using
scripts/get_maintainers.plis usefulI'm not sure I understand what you meant with this.
I should have been more specific. I use this in my .gitconfig:
[sendemail]
tocmd ="scripts/get_maintainer.pl --no-git --no-git-fallback --no-l --no-roles --no-rolestats" cccmd ="scripts/get_maintainer.pl --no-git --no-git-fallback --no-m --no-roles --no-rolestats"
I find this very handy, I thought everyone was using this (possibly not).
Sean
Re: [PATCHv6 1/3] docs: media: update maintainer-entry-profile for multi-committers
In reply to Hans VerkuilEm Mon, 27 Oct 2025 14:28:31 +0100
Hans Verkuil <[email protected]> escreveu:
Quoted 56 lines
From: Mauro Carvalho Chehab <[email protected]>
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 <[email protected]>Reviewed-by Ricardo Ribalda <[email protected]>Signed-off-by Hans Verkuil <[email protected]>--- .../media/maintainer-entry-profile.rst | 368 +++++++++++++++--- 1 file changed, 308 insertions(+), 60 deletions(-)Documentation/driver-api/media/maintainer-entry-profile.rst +13
-8@@ -4,19 +4,25 @@ Media Subsystem Profile Overview -------- -The media subsystem covers support for a variety of devices: stream -capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC -and media pipeline control. +The Linux Media Community (aka: the LinuxTV Community) is formed of +developers working on Linux Kernel Media Subsystem, together with users +who also play an important role in testing the code. -It covers, mainly, the contents of those directories: +The Media Subsystem has code to support a wide variety of media-related +devices: stream capture, analog and digital TV streams, cameras, +video codecs, video processing (resizers, etc.), radio, remote controllers, +HDMI CEC and media pipeline control. + +The Media Subsystem consists of the following directories in the kernel +tree: - drivers/media - drivers/staging/media + - include/media + - Documentation/devicetree/bindings/media/\ [1]_ - Documentation/admin-guide/media - Documentation/driver-api/media - Documentation/userspace-api/media - - Documentation/devicetree/bindings/media/\ [1]_ - - include/media .. [1] Device tree bindings are maintained by the OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers@@ -27,19 +33,264 @@ It covers, mainly, the contents of those directories: Both media userspace and Kernel APIs are documented and the documentation must be kept in sync with the API changes. It means that all patches that add new features to the subsystem must also bring changes to the -corresponding API files. +corresponding API documentation. -Due to the size and wide scope of the media subsystem, media's
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 42
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +5
-5-maintainership model is to have sub-maintainers that have a broad -knowledge of a specific aspect of the subsystem. It is the sub-maintainers' -task to review the patches, providing feedback to users if the patches are -following the subsystem rules and are properly using the media kernel and -userspace APIs. +A small subsystem will typically consist of driver maintainers (as listed +in the MAINTAINERS file) and one or two subsystem maintainers who merge +the patches when ready, maintain the subsystem core code and make the pull +requests to Linus. Due to the size and wide scope of the Media Subsystem +this does not scale and more maintainance layers are needed.
I didn't like this paragraph. media maintainer's profile is not the right place to tell how a small subsystem would be maintained or not. Dropping that out-of-scope part, we have only:
Due to the size and wide scope of the Media Subsystem this does not scale and more maintainance layers are needed.
Which doesn't say much. Also, it defeats the goal of this paragraph: to describe the maintainership model we're adopting, and what a media contributor should know about it. On version 5, we had:
Due to the size and wide scope of the media subsystem, the media's maintainance model recognizes 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.
On my view, v5 text is more aligned to what it is needed here.
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 45
Quoted 7 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-4-Patches for the media subsystem must be sent to the media mailing list -at [email protected] 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 Maintainers +-----------------
While it is fine to keep this name here, there's a lack of consistency after your rename:
Media committers -> Media maintainers (all 3 committers group below)
1. committers -> Media maintainers
2. core committers -> Media core maintainers
3. subsystem maintainers -> Media subsystem maintainers
This is very confusing, as "Media maintainers" refer to the group of people that aren't core committers/subsystem maintainers and to the entire group.
Also, everybody listed in MAINTAINERS is a maintainer. Any maintainer for something under drivers/media would be referred as
"a media maintainer" by other kernel developers.
More importantly, being listed as a media maintainer at MAINTAINERS doesn't imply receiving commit rights at the media.git tree.
So, in the lack of a better terminology, better to stick with nomenclature we already agreed up to v5.
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 47
Quoted 2 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ +The media subsystem has three layers of media maintainers:
"three layers" seems to imply that a patch need to pass to 3 different levels of committers. I would write it as:
The media subsystem maintainership consists of:
And then, add a new type there to remind people about the MAINTAINERS file entries:
1. Media maintainers and reviewers
Everyone that has an entry at MAINTAINERS file for a component inside the media tree. They're typically authors and senior developers responsible for maintaining one or more components at the media subsystem.
Patches affecting such components should be copied to their corresponding media maintainers and reviewers when submitted to the [email protected] mailing list.
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 49
Quoted 2 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ +- Media Maintainer:
2. Media Committers:
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories:
Quoted 3 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +3
-0+ Responsible for a group of drivers within the Media Subsystem. Typically + these are all drivers that have something in common, e.g. codec drivers + or drivers from the same vendor.
OK
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 61
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +10
-0+ Media Maintainers provide feedback if the + patches are not following the subsystem rules, or are not using the + media kernel or userspace APIs correctly, or have poor code quality. They + also keep patchwork up to date, decide when patches are ready for merging, + and create Pull Requests for the Media Subsystem Maintainers to merge. + + A Media Maintainer 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).
Those duties also apply to all types of committers. Better place at the end.
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 64
Quoted 2 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ +- Media Core Maintainer:
3. Media Core Committers:
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 70
Quoted 7 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +7
-0+ Media Maintainers who are also responsible for one or more media core + frameworks. + + Core framework changes are done via consensus between the relevant Media + Core Maintainers. Media Maintainers may include core framework changes in + their Pull Requests if they are signed off by the relevant Media Core + Maintainers.
Nomenclature needs update at the above paragraph.
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 73
Quoted 2 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ +- Media Subsystem Maintainers:
4. Media Subsystem Maintainers:
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 80
Quoted 8 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +8
-0+ Responsible for the subsystem as a whole, with access to the + entire subsystem. Responsible for merging Pull Requests from other + Media Maintainers. + + Userspace API/ABI changes are done via consensus between Media Subsystem + Maintainers\ [2]_. Media (Core) Maintainers may include API/ABI changes in + their Pull Requests if they are signed off by the all Media Subsystem + Maintainers.
Nomenclature needs update at the above paragraphs.
After listing the 4 types of roles, we can place here:
Media Maintainers provide feedback if the patches are not following the subsystem rules, or are not using the media kernel or userspace APIs correctly, or have poor code quality.
Media Committers, core Committers and Media Subsystem Maintainers have commit rights at the media development tree. We refer to all of them as "Committers" inside the media documentation.
Committers keep patchwork up to date, decide when patches are ready for merging
and create Pull Requests when patches are ready to merge.
A 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).
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 85
Quoted 4 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +4
-0+All Media Maintainers shall explicitly agree with the Kernel development process +as described at Documentation/process/index.rst and to the Kernel +development rules inside the Kernel documentation, including its code of +conduct.
All Media Maintainers -> Committers
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 89
Quoted 4 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +4
-0+ +All Media Maintainers shall ensure that patchwork will reflect the current +status, e.g. patches shall be delegated to the Media Maintainer who is +handling them and the patch status shall be updated according to these rules:
All Media Maintainers -> Committers
Quoted 5 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +5
-0+ +- ``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
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 104
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +10
-0+ 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 Media Maintainer decides not to accept a patch, then reply by email to +the patch authors, explaining why it is not accepted, and patchwork shall be +updated accordingly with either:
the Media Maintainer -> the Committer
(same change everywhere inside this doc)
Quoted 59 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +59
-0+ +- ``Changes Requested``: if a new revision was requested; +- ``Rejected``: if the proposed change is not acceptable at all. + +.. Note:: + + Patchwork supports a couple of clients to help semi-automating + status updates via its REST interface: + + https://patchwork.readthedocs.io/en/latest/usage/clients/ + +Media Maintainers are reachable via the #linux-media IRC channel at OFTC. + +.. [2] Everything that would break backward compatibility with existing + non-kernel code are API/ABI changes. This includes ioctl and sysfs + interfaces, v4l2 controls, and their behaviors. + +Becoming a Media Maintainer +--------------------------- + +The most important aspect of volunteering to be a Media Maintainer is that you +have demonstrated the ability to give good code reviews. So we are looking for +whether or not we think you will be good at doing that. + +As such, potential maintainers must earn enough credibility and trust from the +Linux Media Community. To do that, developers shall be familiar with the open +source model and have been active in the Linux Kernel community for some time, +and, in particular, in the media subsystem. + +In addition to actually making the code changes, you are basically +demonstrating your: + +- commitment to the project; +- ability to collaborate with the team and communicate well; +- understand of how upstream and the Linux Media Community work + (policies, processes for testing, code review, ...) +- reasonable knowledge about: + + - the Kernel development process: + Documentation/process/index.rst + + - the Media development profile: + Documentation/driver-api/media/maintainer-entry-profile.rst + +- understanding of the projects' code base and coding style; +- ability to provide feedback to the patch authors; +- ability to judge when a patch might be ready for review and to submit; +- ability to write good code (last but certainly not least). + +Developers that desire to become maintainers are encouraged to participate +at the yearly Linux Media Summit, typically co-located with a Linux related +conference. These summits will be announced at the linux-media mailing list. + +If you are doing such tasks and have become a valued developer, an +existing Media Maintainer can nominate you to the Media Subsystem Maintainers. + +The ultimate responsibility for accepting a nominated maintainer is up to +the subsystem's maintainers. The nominated maintainer must have earned a trust +relationship with all Media Subsystem Maintainers, as, by becoming Media
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 172
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +9
-0+Maintainer, you will take over part of their maintenance tasks. + +Media Committers +---------------- + +Experienced and trusted Media (Core) Maintainers may be granted commit rights +which allow them to directly push patches to the media development tree instead +of posting a Pull Request for the Media Subsystem Maintainers. This helps +offloading some of the work of the Media Subsystem Maintainers.
This one sounds confusing.
On your version, there are 6 types of maintainers related to media subsytem, plus the ones on MAINTAINERS, as one could potentially be a "media maintainer", a "core maintainer" or even a "subsystem maintainer", being responsible to update patchwork but still not having commit rights.
I don't think we want that.
---
I'll stop the review here, as IMHO we need first to address the nomenclature. Then check if the terms are properly used along the docs in a consistent way.
Thanks,
Mauro
Re: [PATCHv6 1/3] docs: media: update maintainer-entry-profile for multi-committers
Em Wed, 3 Dec 2025 10:43:28 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 10 lines
Em Mon, 27 Oct 2025 14:28:31 +0100
Hans Verkuil <[email protected]> escreveu:On your version, there are 6 types of maintainers related to media subsytem, plus the ones on
MAINTAINERS, as one could potentially be a "media maintainer", a "core maintainer" or even a "subsystem maintainer", being responsible to update patchwork but still not having commit rights.I don't think we want that.
Heh, I should have read it to the end...
it sounds that you're actually proposing exactly that: have a mix of maintainers with and without commit rights.
On such case, I think we need to define them as something like:
Media Maintainers
-----------------
1. Media maintainers and reviewers
- Everyone that has an entry at MAINTAINERS for a media-related file;
2. Media Committers
- Subset of media maintainers that have commit rights
3. Media Core Maintainers
- responsible for one or more media framework;
4. Media Core Committers
- Subset of media core maintainers that have commit rights
5. Media Subsystem Maintainers
- Those have commit rights.
I won't add (1) to List of Media Maintainers session. We have already the MAINTAINERS file to track them. Keeping two files updated with the same data is confusing.
Also, we need to plan a cleanup MAINTAINERS, pinging and eventually drop or replace inactive Media Maintainers.
Thanks,
Mauro
Re: [PATCHv6 1/3] docs: media: update maintainer-entry-profile for multi-committers
Quoted 24 lines · Mauro Carvalho Chehab
Em Wed, 3 Dec 2025 10:43:28 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:Quoted 10 lines
Em Mon, 27 Oct 2025 14:28:31 +0100
Hans Verkuil <[email protected]> escreveu:On your version, there are 6 types of maintainers related to media subsytem, plus the ones on
MAINTAINERS, as one could potentially be a "media maintainer", a "core maintainer" or even a "subsystem maintainer", being responsible to update patchwork but still not having commit rights.I don't think we want that.
Heh, I should have read it to the end...
it sounds that you're actually proposing exactly that: have a mix of maintainers with and without commit rights.
On such case, I think we need to define them as something like:
Quoted 8 lines
Media Maintainers
-----------------1. Media maintainers and reviewers
- Everyone that has an entry at
MAINTAINERSfor a media-related file;2. Media Committers
I wouldn't make that a separate class. It is irrelevant in practice if a maintainer has commit rights. The only difference is that instead of posting a PR they can commit directly. That's only relevant for us as subsystem maintainers.
Developers care only about which maintains what and who should I Cc.
Regards,
Hans
Quoted 26 lines
- Subset of media maintainers that have commit rights
3. Media Core Maintainers
- responsible for one or more media framework;
4. Media Core Committers
- Subset of media core maintainers that have commit rights
5. Media Subsystem Maintainers
- Those have commit rights.
I won't add (1) to List of Media Maintainers session. We have already the
MAINTAINERSfile to track them. Keeping two files updated with the same data is confusing.Also, we need to plan a cleanup
MAINTAINERS, pinging and eventually drop or replace inactive Media Maintainers.Thanks,
Mauro
Re: [PATCHv6 1/3] docs: media: update maintainer-entry-profile for multi-committers
In reply to Mauro Carvalho ChehabQuoted 81 lines · Mauro Carvalho Chehab
Em Mon, 27 Oct 2025 14:28:31 +0100
Hans Verkuil <[email protected]> escreveu:Quoted 56 lines
From: Mauro Carvalho Chehab <[email protected]>
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 <[email protected]>Reviewed-by Ricardo Ribalda <[email protected]>Signed-off-by Hans Verkuil <[email protected]>--- .../media/maintainer-entry-profile.rst | 368 +++++++++++++++--- 1 file changed, 308 insertions(+), 60 deletions(-)Documentation/driver-api/media/maintainer-entry-profile.rst +13
-8@@ -4,19 +4,25 @@ Media Subsystem Profile Overview -------- -The media subsystem covers support for a variety of devices: stream -capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC -and media pipeline control. +The Linux Media Community (aka: the LinuxTV Community) is formed of +developers working on Linux Kernel Media Subsystem, together with users +who also play an important role in testing the code. -It covers, mainly, the contents of those directories: +The Media Subsystem has code to support a wide variety of media-related +devices: stream capture, analog and digital TV streams, cameras, +video codecs, video processing (resizers, etc.), radio, remote controllers, +HDMI CEC and media pipeline control. + +The Media Subsystem consists of the following directories in the kernel +tree: - drivers/media - drivers/staging/media + - include/media + - Documentation/devicetree/bindings/media/\ [1]_ - Documentation/admin-guide/media - Documentation/driver-api/media - Documentation/userspace-api/media - - Documentation/devicetree/bindings/media/\ [1]_ - - include/media .. [1] Device tree bindings are maintained by the OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers@@ -27,19 +33,264 @@ It covers, mainly, the contents of those directories: Both media userspace and Kernel APIs are documented and the documentation must be kept in sync with the API changes. It means that all patches that add new features to the subsystem must also bring changes to the -corresponding API files. +corresponding API documentation. -Due to the size and wide scope of the media subsystem, media'sDocumentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 42
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +5
-5-maintainership model is to have sub-maintainers that have a broad -knowledge of a specific aspect of the subsystem. It is the sub-maintainers' -task to review the patches, providing feedback to users if the patches are -following the subsystem rules and are properly using the media kernel and -userspace APIs. +A small subsystem will typically consist of driver maintainers (as listed +in the MAINTAINERS file) and one or two subsystem maintainers who merge +the patches when ready, maintain the subsystem core code and make the pull +requests to Linus. Due to the size and wide scope of the Media Subsystem +this does not scale and more maintainance layers are needed.I didn't like this paragraph. media maintainer's profile is not the right place to tell how a small subsystem would be maintained or not. Dropping that out-of-scope part, we have only:
Due to the size and wide scope of the Media Subsystem this does not scale and more maintainance layers are needed.
Which doesn't say much. Also, it defeats the goal of this paragraph: to describe the maintainership model we're adopting, and what a media contributor should know about it. On version 5, we had:
Quoted 8 lines
Due to the size and wide scope of the media subsystem, the media's maintainance model recognizes 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.
On my view, v5 text is more aligned to what it is needed here.
Alternative:
Due to the size and wide scope of the media subsystem, multiple layers of maintainers are required, each with their own areas of expertise.
Quoted 27 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 45
Quoted 9 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-4-Patches for the media subsystem must be sent to the media mailing list -at [email protected] 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 Maintainers +-----------------While it is fine to keep this name here, there's a lack of consistency after your rename:
Media committers -> Media maintainers (all 3 committers group below)
1. committers -> Media maintainers
2. core committers -> Media core maintainers
3. subsystem maintainers -> Media subsystem maintainersThis is very confusing, as "Media maintainers" refer to the group of people that aren't core committers/subsystem maintainers and to the entire group.
Also, everybody listed in
MAINTAINERSis a maintainer. Any maintainer for something underdrivers/mediawould be referred as
"a media maintainer" by other kernel developers.
Quoted 5 lines
More importantly, being listed as a media maintainer at
MAINTAINERSdoesn't imply receiving commit rights at the media.git tree.So, in the lack of a better terminology, better to stick with nomenclature we already agreed up to v5.
A major problem with v5 is that it mixed 'maintainer' with 'committer'. A committer is a maintainer with commit rights. But the maintainer duties remain the same, whether you have commit rights or not. It's one of the reasons why previous versions were hard to understand.
But I agree that "Media Maintainer" needs a better name. I think "Media Core Maintainer" and "Media Subsystem Maintainer" are clear, but for "Media Maintainer" we need something better.
Today "Media Maintainers" in the sense of this document are Nicolas (codec drivers) and Bryan (Qualcomm drivers). So developers with the responsibility for certain classes of drivers.
"Media Specialist Maintainer"? Maintainers specializing in a certain type of driver.
Basically the hierarchy is:
Media Contributor
Media Driver Maintainer
Media Specialist (?) Maintainer
Media Core Maintainer
Media Subsystem Maintainer
The last three can post media PRs or have media commit rights.
As mentioned in my reply to Ricardo, a Media Driver Maintainer can also get commit rights, but I prefer to postpone that until we have a candidate for that.
Quoted 7 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 47
Quoted 3 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ +The media subsystem has three layers of media maintainers:"three layers" seems to imply that a patch need to pass to 3 different levels of committers. I would write it as:
Quoted 6 lines
The media subsystem maintainership consists of:
And then, add a new type there to remind people about the
MAINTAINERSfile entries:1. Media maintainers and reviewers
I'd call that "Media Driver Maintainer"
Quoted 3 lines
Everyone that has an entry at
MAINTAINERSfile for a component inside the media tree. They're typically authors and senior
I'd drop 'senior', that doesn't add anything.
Quoted 7 lines
developers responsible for maintaining one or more components at the media subsystem.
Patches affecting such components should be copied to their corresponding media maintainers and reviewers when submitted to the [email protected] mailing list.
Quoted 5 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 49
Quoted 2 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ +- Media Maintainer:2. Media Committers:
"Media Specialist Maintainer" or something along those lines.
Definitely not 'committer'.
Quoted 18 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories:
Quoted 4 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +3
-0+ Responsible for a group of drivers within the Media Subsystem. Typically + these are all drivers that have something in common, e.g. codec drivers + or drivers from the same vendor.OK
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 61
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +10
-0+ Media Maintainers provide feedback if the + patches are not following the subsystem rules, or are not using the + media kernel or userspace APIs correctly, or have poor code quality. They + also keep patchwork up to date, decide when patches are ready for merging, + and create Pull Requests for the Media Subsystem Maintainers to merge. + + A Media Maintainer 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).
Quoted 10 lines
Those duties also apply to all types of committers. Better place at the end.
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 64
Quoted 2 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ +- Media Core Maintainer:3. Media Core Committers:
Quoted 2 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ Media Maintainers who are also responsible for one or more media core + frameworks.
With this I tried to indicate that the Media Core Maintainer duties are in addition to those of the Media Specialist Maintainer.
Quoted 6 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 70
Quoted 5 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +5
-0+ + Core framework changes are done via consensus between the relevant Media + Core Maintainers. Media Maintainers may include core framework changes in + their Pull Requests if they are signed off by the relevant Media Core + Maintainers.
Quoted 7 lines
Nomenclature needs update at the above paragraph.
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 73
Quoted 2 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ +- Media Subsystem Maintainers:4. Media Subsystem Maintainers:
Here it should clearly state that these duties are in addition to those of a Media Core Maintainer.
Quoted 29 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 80
Quoted 8 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +8
-0+ Responsible for the subsystem as a whole, with access to the + entire subsystem. Responsible for merging Pull Requests from other + Media Maintainers. + + Userspace API/ABI changes are done via consensus between Media Subsystem + Maintainers\ [2]_. Media (Core) Maintainers may include API/ABI changes in + their Pull Requests if they are signed off by the all Media Subsystem + Maintainers.Nomenclature needs update at the above paragraphs.
After listing the 4 types of roles, we can place here:
Media Maintainers provide feedback if the patches are not following the subsystem rules, or are not using the media kernel or userspace APIs correctly, or have poor code quality.
Media Committers, core Committers and Media Subsystem Maintainers have commit rights at the media development tree. We refer to all of them as "Committers" inside the media documentation.
Committers keep patchwork up to date, decide when patches are ready for merging
and create Pull Requests when patches are ready to merge.A 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).
Quoted 6 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 85
Quoted 4 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +4
-0+All Media Maintainers shall explicitly agree with the Kernel development process +as described at Documentation/process/index.rst and to the Kernel +development rules inside the Kernel documentation, including its code of +conduct.All Media Maintainers -> Committers
No, no, no! A committer is a maintainer with commit rights. But the maintainer may be too inexperienced, not yet trusted enough, or just not interested in getting commit rights.
The next patch describes the extra responsibilities a committer has, but that makes no difference to their responsibilities as maintainer.
The word 'committer' shouldn't occur in this section, other than as a reference to the committer documentation.
I think the maintainer job is far more important than being able to commit to a tree. Just posting a PR and letting someone else do the commit is a lot easier.
It's fairly time consuming for me to check a PR and ensure it is fine to commit. Which is of course why we want a multi-committer model. But that also pushes the time that I now spend to the maintainer with the commit rights. So other than prestige it is just more work compared to posting a PR.
Regards,
Hans
Quoted 116 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 89
Quoted 5 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +4
-0+ +All Media Maintainers shall ensure that patchwork will reflect the current +status, e.g. patches shall be delegated to the Media Maintainer who is +handling them and the patch status shall be updated according to these rules:All Media Maintainers -> Committers
Quoted 5 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +5
-0+ +- ``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 theDocumentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 104
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +10
-0+ 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 Media Maintainer decides not to accept a patch, then reply by email to +the patch authors, explaining why it is not accepted, and patchwork shall be +updated accordingly with either:the Media Maintainer -> the Committer
(same change everywhere inside this doc)
Quoted 59 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +59
-0+ +- ``Changes Requested``: if a new revision was requested; +- ``Rejected``: if the proposed change is not acceptable at all. + +.. Note:: + + Patchwork supports a couple of clients to help semi-automating + status updates via its REST interface: + + https://patchwork.readthedocs.io/en/latest/usage/clients/ + +Media Maintainers are reachable via the #linux-media IRC channel at OFTC. + +.. [2] Everything that would break backward compatibility with existing + non-kernel code are API/ABI changes. This includes ioctl and sysfs + interfaces, v4l2 controls, and their behaviors. + +Becoming a Media Maintainer +--------------------------- + +The most important aspect of volunteering to be a Media Maintainer is that you +have demonstrated the ability to give good code reviews. So we are looking for +whether or not we think you will be good at doing that. + +As such, potential maintainers must earn enough credibility and trust from the +Linux Media Community. To do that, developers shall be familiar with the open +source model and have been active in the Linux Kernel community for some time, +and, in particular, in the media subsystem. + +In addition to actually making the code changes, you are basically +demonstrating your: + +- commitment to the project; +- ability to collaborate with the team and communicate well; +- understand of how upstream and the Linux Media Community work + (policies, processes for testing, code review, ...) +- reasonable knowledge about: + + - the Kernel development process: + Documentation/process/index.rst + + - the Media development profile: + Documentation/driver-api/media/maintainer-entry-profile.rst + +- understanding of the projects' code base and coding style; +- ability to provide feedback to the patch authors; +- ability to judge when a patch might be ready for review and to submit; +- ability to write good code (last but certainly not least). + +Developers that desire to become maintainers are encouraged to participate +at the yearly Linux Media Summit, typically co-located with a Linux related +conference. These summits will be announced at the linux-media mailing list. + +If you are doing such tasks and have become a valued developer, an +existing Media Maintainer can nominate you to the Media Subsystem Maintainers. + +The ultimate responsibility for accepting a nominated maintainer is up to +the subsystem's maintainers. The nominated maintainer must have earned a trust +relationship with all Media Subsystem Maintainers, as, by becoming MediaDocumentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 172
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +9
-0+Maintainer, you will take over part of their maintenance tasks. + +Media Committers +---------------- + +Experienced and trusted Media (Core) Maintainers may be granted commit rights +which allow them to directly push patches to the media development tree instead +of posting a Pull Request for the Media Subsystem Maintainers. This helps +offloading some of the work of the Media Subsystem Maintainers.This one sounds confusing.
On your version, there are 6 types of maintainers related to media subsytem, plus the ones on
MAINTAINERS, as one could potentially be a "media maintainer", a "core maintainer" or even a "subsystem maintainer", being responsible to update patchwork but still not having commit rights.I don't think we want that.
---
I'll stop the review here, as IMHO we need first to address the nomenclature. Then check if the terms are properly used along the docs in a consistent way.
Thanks,
Mauro
Re: [PATCHv6 1/3] docs: media: update maintainer-entry-profile for multi-committers
Quoted 89 lines · On Fri, 23 Jan 2026 15:16:37 +0100 Hans Verkuil <[email protected]>…
Quoted 88 lines · Mauro Carvalho Chehab
Em Mon, 27 Oct 2025 14:28:31 +0100
Hans Verkuil <[email protected]> escreveu:Quoted 56 lines
From: Mauro Carvalho Chehab <[email protected]>
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 <[email protected]>Reviewed-by Ricardo Ribalda <[email protected]>Signed-off-by Hans Verkuil <[email protected]>--- .../media/maintainer-entry-profile.rst | 368 +++++++++++++++--- 1 file changed, 308 insertions(+), 60 deletions(-)Documentation/driver-api/media/maintainer-entry-profile.rst +13
-8@@ -4,19 +4,25 @@ Media Subsystem Profile Overview -------- -The media subsystem covers support for a variety of devices: stream -capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC -and media pipeline control. +The Linux Media Community (aka: the LinuxTV Community) is formed of +developers working on Linux Kernel Media Subsystem, together with users +who also play an important role in testing the code. -It covers, mainly, the contents of those directories: +The Media Subsystem has code to support a wide variety of media-related +devices: stream capture, analog and digital TV streams, cameras, +video codecs, video processing (resizers, etc.), radio, remote controllers, +HDMI CEC and media pipeline control. + +The Media Subsystem consists of the following directories in the kernel +tree: - drivers/media - drivers/staging/media + - include/media + - Documentation/devicetree/bindings/media/\ [1]_ - Documentation/admin-guide/media - Documentation/driver-api/media - Documentation/userspace-api/media - - Documentation/devicetree/bindings/media/\ [1]_ - - include/media .. [1] Device tree bindings are maintained by the OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers@@ -27,19 +33,264 @@ It covers, mainly, the contents of those directories: Both media userspace and Kernel APIs are documented and the documentation must be kept in sync with the API changes. It means that all patches that add new features to the subsystem must also bring changes to the -corresponding API files. +corresponding API documentation. -Due to the size and wide scope of the media subsystem, media'sDocumentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 42
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +5
-5-maintainership model is to have sub-maintainers that have a broad -knowledge of a specific aspect of the subsystem. It is the sub-maintainers' -task to review the patches, providing feedback to users if the patches are -following the subsystem rules and are properly using the media kernel and -userspace APIs. +A small subsystem will typically consist of driver maintainers (as listed +in the MAINTAINERS file) and one or two subsystem maintainers who merge +the patches when ready, maintain the subsystem core code and make the pull +requests to Linus. Due to the size and wide scope of the Media Subsystem +this does not scale and more maintainance layers are needed.I didn't like this paragraph. media maintainer's profile is not the right place to tell how a small subsystem would be maintained or not. Dropping that out-of-scope part, we have only:
Due to the size and wide scope of the Media Subsystem this does not scale and more maintainance layers are needed.
Which doesn't say much. Also, it defeats the goal of this paragraph: to describe the maintainership model we're adopting, and what a media contributor should know about it. On version 5, we had:
Due to the size and wide scope of the media subsystem, the media's maintainance model recognizes 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.
Quoted 6 lines
Quoted 1 line
On my view, v5 text is more aligned to what it is needed here.
Alternative:
Due to the size and wide scope of the media subsystem, multiple layers of maintainers are required, each with their own areas of expertise.
That's OK. what I didn't like was:
A small subsystem will typically consist of driver maintainers (as listed in the MAINTAINERS file) and one or two subsystem maintainers who merge the patches when ready, maintain the subsystem core code and make the pull requests to Linus. Due to the size and wide scope of the Media Subsystem this does not scale and more maintainance layers are needed.
What a "small subsystem" does (or does not) is not something that should be documented at the media subsystem profile.
Quoted 28 lines
Quoted 28 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 45
Quoted 7 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-4-Patches for the media subsystem must be sent to the media mailing list -at [email protected] 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 Maintainers +-----------------While it is fine to keep this name here, there's a lack of consistency after your rename:
Media committers -> Media maintainers (all 3 committers group below)
1. committers -> Media maintainers
2. core committers -> Media core maintainers
3. subsystem maintainers -> Media subsystem maintainersThis is very confusing, as "Media maintainers" refer to the group of people that aren't core committers/subsystem maintainers and to the entire group.
Also, everybody listed in
MAINTAINERSis a maintainer. Any maintainer for something underdrivers/mediawould be referred as
"a media maintainer" by other kernel developers.More importantly, being listed as a media maintainer at
MAINTAINERSdoesn't imply receiving commit rights at the media.git tree.
Quoted 7 lines
Quoted 2 lines
So, in the lack of a better terminology, better to stick with nomenclature we already agreed up to v5.
A major problem with v5 is that it mixed 'maintainer' with 'committer'. A committer is a maintainer with commit rights. But the maintainer duties remain the same, whether you have commit rights or not. It's one of the reasons why previous versions were hard to understand.
This is a concept change from the original idea, but I'm OK with that.
Quoted 7 lines
But I agree that "Media Maintainer" needs a better name. I think "Media Core Maintainer" and "Media Subsystem Maintainer" are clear, but for "Media Maintainer" we need something better.
Today "Media Maintainers" in the sense of this document are Nicolas (codec drivers) and Bryan (Qualcomm drivers). So developers with the responsibility for certain classes of drivers.
Well, in that sense, "Qualcomm drivers" is not different from any other "<vendor> drivers". for me, it is at the "Media Driver Maintainer" group.
Up to some point, the same applies to Nicolas: he is responsible for a set of drivers, but, his case is IMO a little bit different.
Quoted 9 lines
"Media Specialist Maintainer"? Maintainers specializing in a certain type of driver.
Basically the hierarchy is:
Media Contributor
Media Driver Maintainer
Media Specialist (?) Maintainer
I don't like "Specialist". Maybe
"Media <type> Reviewer" or "Media <type> Maintainer". See below.
Quoted 2 lines
Media Core Maintainer
Media Subsystem Maintainer
IMO, we should define clearly the scope. Something like:
- Media Driver Maintainer: Maintains a set of media drivers. Could be driver-specific or even all drivers from a given vendor;
- Media <type> reviewer: Reviews all drivers of the same type, independently of the author/vendor;
IMO, Nicolas, while working on codec drivers from someone else is acting as "Media Codec Reviewer" (I don't mind calling it as:
"Media Codec Maintainer").
- Media Core Maintainer: Maintains parts of the media framework itself;
Quoted 1 line
The last three can post media PRs or have media commit rights.
I don't mind much with the concept that some random driver maintainers would be sending PRs. Shuah, for instance, have been sending us PRs instead of patch series for quite a while. We might grant in the future commit rights to Media Driver Maintainers and even to Media Contributors that we trust enough, have been involved with the community for a long time and have a long history of good contributions.
Quoted 10 lines
As mentioned in my reply to Ricardo, a Media Driver Maintainer can also get commit rights, but I prefer to postpone that until we have a candidate for that.
Quoted 7 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 47
Quoted 3 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ +The media subsystem has three layers of media maintainers:"three layers" seems to imply that a patch need to pass to 3 different levels of committers. I would write it as:
Quoted 8 lines
Quoted 6 lines
The media subsystem maintainership consists of:
And then, add a new type there to remind people about the
MAINTAINERSfile entries:1. Media maintainers and reviewers
I'd call that "Media Driver Maintainer"
Ok.
Quoted 5 lines
Quoted 3 lines
Everyone that has an entry at
MAINTAINERSfile for a component inside the media tree. They're typically authors and seniorI'd drop 'senior', that doesn't add anything.
Works for me.
Quoted 11 lines
Quoted 11 lines
developers responsible for maintaining one or more components at the media subsystem.
Patches affecting such components should be copied to their corresponding media maintainers and reviewers when submitted to the [email protected] mailing list.
Quoted 2 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ +- Media Maintainer:
Quoted 5 lines
Quoted 1 line
2. Media Committers:
"Media Specialist Maintainer" or something along those lines.
Definitely not 'committer'.
Ok, but see above.
Quoted 85 lines
Quoted 18 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories:
Quoted 4 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +3
-0+ Responsible for a group of drivers within the Media Subsystem. Typically + these are all drivers that have something in common, e.g. codec drivers + or drivers from the same vendor.OK
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 61
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +10
-0+ Media Maintainers provide feedback if the + patches are not following the subsystem rules, or are not using the + media kernel or userspace APIs correctly, or have poor code quality. They + also keep patchwork up to date, decide when patches are ready for merging, + and create Pull Requests for the Media Subsystem Maintainers to merge. + + A Media Maintainer 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).Quoted 10 lines
Those duties also apply to all types of committers. Better place at the end.
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 64
Quoted 2 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ +- Media Core Maintainer:3. Media Core Committers:
Quoted 2 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ Media Maintainers who are also responsible for one or more media core + frameworks.With this I tried to indicate that the Media Core Maintainer duties are in addition to those of the Media Specialist Maintainer.
Quoted 6 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 70
Quoted 5 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +5
-0+ + Core framework changes are done via consensus between the relevant Media + Core Maintainers. Media Maintainers may include core framework changes in + their Pull Requests if they are signed off by the relevant Media Core + Maintainers.Quoted 7 lines
Nomenclature needs update at the above paragraph.
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 73
Quoted 2 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +2
-0+ +- Media Subsystem Maintainers:4. Media Subsystem Maintainers:
Here it should clearly state that these duties are in addition to those of a Media Core Maintainer.
Quoted 29 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 80
Quoted 8 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +8
-0+ Responsible for the subsystem as a whole, with access to the + entire subsystem. Responsible for merging Pull Requests from other + Media Maintainers. + + Userspace API/ABI changes are done via consensus between Media Subsystem + Maintainers\ [2]_. Media (Core) Maintainers may include API/ABI changes in + their Pull Requests if they are signed off by the all Media Subsystem + Maintainers.Nomenclature needs update at the above paragraphs.
After listing the 4 types of roles, we can place here:
Media Maintainers provide feedback if the patches are not following the subsystem rules, or are not using the media kernel or userspace APIs correctly, or have poor code quality.
Media Committers, core Committers and Media Subsystem Maintainers have commit rights at the media development tree. We refer to all of them as "Committers" inside the media documentation.
Committers keep patchwork up to date, decide when patches are ready for merging
and create Pull Requests when patches are ready to merge.A 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).
Quoted 6 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 85
Quoted 4 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +4
-0+All Media Maintainers shall explicitly agree with the Kernel development process +as described at Documentation/process/index.rst and to the Kernel +development rules inside the Kernel documentation, including its code of +conduct.All Media Maintainers -> Committers
Quoted 3 lines
No, no, no! A committer is a maintainer with commit rights. But the maintainer may be too inexperienced, not yet trusted enough, or just not interested in getting commit rights.
Ok.
Quoted 2 lines
The next patch describes the extra responsibilities a committer has, but that makes no difference to their responsibilities as maintainer.
Once we have a new version for patch 1, I'll review the next ones.
Quoted 2 lines
The word 'committer' shouldn't occur in this section, other than as a reference to the committer documentation.
Ok.
Quoted 128 lines
I think the maintainer job is far more important than being able to commit to a tree. Just posting a PR and letting someone else do the commit is a lot easier.
It's fairly time consuming for me to check a PR and ensure it is fine to commit. Which is of course why we want a multi-committer model. But that also pushes the time that I now spend to the maintainer with the commit rights. So other than prestige it is just more work compared to posting a PR.
Regards,
Hans
Quoted 115 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 89
Quoted 5 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +4
-0+ +All Media Maintainers shall ensure that patchwork will reflect the current +status, e.g. patches shall be delegated to the Media Maintainer who is +handling them and the patch status shall be updated according to these rules:All Media Maintainers -> Committers
Quoted 5 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +5
-0+ +- ``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 theDocumentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 104
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +10
-0+ 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 Media Maintainer decides not to accept a patch, then reply by email to +the patch authors, explaining why it is not accepted, and patchwork shall be +updated accordingly with either:the Media Maintainer -> the Committer
(same change everywhere inside this doc)
Quoted 59 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +59
-0+ +- ``Changes Requested``: if a new revision was requested; +- ``Rejected``: if the proposed change is not acceptable at all. + +.. Note:: + + Patchwork supports a couple of clients to help semi-automating + status updates via its REST interface: + + https://patchwork.readthedocs.io/en/latest/usage/clients/ + +Media Maintainers are reachable via the #linux-media IRC channel at OFTC. + +.. [2] Everything that would break backward compatibility with existing + non-kernel code are API/ABI changes. This includes ioctl and sysfs + interfaces, v4l2 controls, and their behaviors. + +Becoming a Media Maintainer +--------------------------- + +The most important aspect of volunteering to be a Media Maintainer is that you +have demonstrated the ability to give good code reviews. So we are looking for +whether or not we think you will be good at doing that. + +As such, potential maintainers must earn enough credibility and trust from the +Linux Media Community. To do that, developers shall be familiar with the open +source model and have been active in the Linux Kernel community for some time, +and, in particular, in the media subsystem. + +In addition to actually making the code changes, you are basically +demonstrating your: + +- commitment to the project; +- ability to collaborate with the team and communicate well; +- understand of how upstream and the Linux Media Community work + (policies, processes for testing, code review, ...) +- reasonable knowledge about: + + - the Kernel development process: + Documentation/process/index.rst + + - the Media development profile: + Documentation/driver-api/media/maintainer-entry-profile.rst + +- understanding of the projects' code base and coding style; +- ability to provide feedback to the patch authors; +- ability to judge when a patch might be ready for review and to submit; +- ability to write good code (last but certainly not least). + +Developers that desire to become maintainers are encouraged to participate +at the yearly Linux Media Summit, typically co-located with a Linux related +conference. These summits will be announced at the linux-media mailing list. + +If you are doing such tasks and have become a valued developer, an +existing Media Maintainer can nominate you to the Media Subsystem Maintainers. + +The ultimate responsibility for accepting a nominated maintainer is up to +the subsystem's maintainers. The nominated maintainer must have earned a trust +relationship with all Media Subsystem Maintainers, as, by becoming MediaDocumentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 172
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +9
-0+Maintainer, you will take over part of their maintenance tasks. + +Media Committers +---------------- + +Experienced and trusted Media (Core) Maintainers may be granted commit rights +which allow them to directly push patches to the media development tree instead +of posting a Pull Request for the Media Subsystem Maintainers. This helps +offloading some of the work of the Media Subsystem Maintainers.This one sounds confusing.
On your version, there are 6 types of maintainers related to media subsytem, plus the ones on
MAINTAINERS, as one could potentially be a "media maintainer", a "core maintainer" or even a "subsystem maintainer", being responsible to update patchwork but still not having commit rights.I don't think we want that.
---
I'll stop the review here, as IMHO we need first to address the nomenclature. Then check if the terms are properly used along the docs in a consistent way.
Thanks,
Mauro
Re: [PATCHv6 1/3] docs: media: update maintainer-entry-profile for multi-committers
In reply to Hans VerkuilHi Hans
Thanks for the new version
Quoted 191 lines · Hans Verkuil
From: Mauro Carvalho Chehab <[email protected]>
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 <[email protected]>Reviewed-by Ricardo Ribalda <[email protected]>Signed-off-by Hans Verkuil <[email protected]>--- .../media/maintainer-entry-profile.rst | 368 +++++++++++++++--- 1 file changed, 308 insertions(+), 60 deletions(-)Documentation/driver-api/media/maintainer-entry-profile.rst +137
-17@@ -4,19 +4,25 @@ Media Subsystem Profile Overview -------- -The media subsystem covers support for a variety of devices: stream -capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC -and media pipeline control. +The Linux Media Community (aka: the LinuxTV Community) is formed of +developers working on Linux Kernel Media Subsystem, together with users +who also play an important role in testing the code. -It covers, mainly, the contents of those directories: +The Media Subsystem has code to support a wide variety of media-related +devices: stream capture, analog and digital TV streams, cameras, +video codecs, video processing (resizers, etc.), radio, remote controllers, +HDMI CEC and media pipeline control. + +The Media Subsystem consists of the following directories in the kernel +tree: - drivers/media - drivers/staging/media + - include/media + - Documentation/devicetree/bindings/media/\ [1]_ - Documentation/admin-guide/media - Documentation/driver-api/media - Documentation/userspace-api/media - - Documentation/devicetree/bindings/media/\ [1]_ - - include/media .. [1] Device tree bindings are maintained by the OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers@@ -27,19 +33,264 @@ It covers, mainly, the contents of those directories: Both media userspace and Kernel APIs are documented and the documentation must be kept in sync with the API changes. It means that all patches that add new features to the subsystem must also bring changes to the -corresponding API files. +corresponding API documentation. -Due to the size and wide scope of the media subsystem, media's -maintainership model is to have sub-maintainers that have a broad -knowledge of a specific aspect of the subsystem. It is the sub-maintainers' -task to review the patches, providing feedback to users if the patches are -following the subsystem rules and are properly using the media kernel and -userspace APIs. +A small subsystem will typically consist of driver maintainers (as listed +in the MAINTAINERS file) and one or two subsystem maintainers who merge +the patches when ready, maintain the subsystem core code and make the pull +requests to Linus. Due to the size and wide scope of the Media Subsystem +this does not scale and more maintainance layers are needed. -Patches for the media subsystem must be sent to the media mailing list -at [email protected] 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 Maintainers +----------------- + +The media subsystem has three layers of media maintainers: + +- Media Maintainer: + Responsible for a group of drivers within the Media Subsystem. Typically + these are all drivers that have something in common, e.g. codec drivers + or drivers from the same vendor. Media Maintainers provide feedback if the + patches are not following the subsystem rules, or are not using the + media kernel or userspace APIs correctly, or have poor code quality. They + also keep patchwork up to date, decide when patches are ready for merging, + and create Pull Requests for the Media Subsystem Maintainers to merge. + + A Media Maintainer 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). + +- Media Core Maintainer: + Media Maintainers who are also responsible for one or more media core + frameworks. + + Core framework changes are done via consensus between the relevant Media + Core Maintainers. Media Maintainers may include core framework changes in + their Pull Requests if they are signed off by the relevant Media Core + Maintainers. + +- Media Subsystem Maintainers: + Responsible for the subsystem as a whole, with access to the + entire subsystem. Responsible for merging Pull Requests from other + Media Maintainers. + + Userspace API/ABI changes are done via consensus between Media Subsystem + Maintainers\ [2]_. Media (Core) Maintainers may include API/ABI changes in + their Pull Requests if they are signed off by the all Media Subsystem + Maintainers. + +All Media Maintainers shall explicitly agree with the Kernel development process +as described at Documentation/process/index.rst and to the Kernel +development rules inside the Kernel documentation, including its code of +conduct. + +All Media Maintainers shall ensure that patchwork will reflect the current +status, e.g. patches shall be delegated to the Media Maintainer who is +handling them and the patch status shall be updated according to these rules: + +- ``Under Review``: Used if the patch requires a second opinion + or when it is part of a pull request; +- ``Accepted``: Once a patch is merged in the multi-committer tree. +- ``Superseded``: There is a newer version of the patch posted to the + mailing list. +- ``Duplicated``: There was another patch doing the same thing from someone + else that was accepted. +- ``Not Applicable``: Use for patch series that are not merged at media.git + tree (e.g. drm, dmabuf, upstream merge, etc.) but were cross-posted to the + linux-media mailing list. + +If the Media Maintainer decides not to accept a patch, then reply by email to +the patch authors, explaining why it is not accepted, and patchwork shall be +updated accordingly with either: + +- ``Changes Requested``: if a new revision was requested; +- ``Rejected``: if the proposed change is not acceptable at all. + +.. Note:: + + Patchwork supports a couple of clients to help semi-automating + status updates via its REST interface: + + https://patchwork.readthedocs.io/en/latest/usage/clients/ + +Media Maintainers are reachable via the #linux-media IRC channel at OFTC. + +.. [2] Everything that would break backward compatibility with existing + non-kernel code are API/ABI changes. This includes ioctl and sysfs + interfaces, v4l2 controls, and their behaviors. + +Becoming a Media Maintainer +--------------------------- + +The most important aspect of volunteering to be a Media Maintainer is that you +have demonstrated the ability to give good code reviews. So we are looking for +whether or not we think you will be good at doing that. + +As such, potential maintainers must earn enough credibility and trust from the +Linux Media Community. To do that, developers shall be familiar with the open +source model and have been active in the Linux Kernel community for some time, +and, in particular, in the media subsystem. + +In addition to actually making the code changes, you are basically +demonstrating your: + +- commitment to the project; +- ability to collaborate with the team and communicate well; +- understand of how upstream and the Linux Media Community work + (policies, processes for testing, code review, ...) +- reasonable knowledge about: + + - the Kernel development process: + Documentation/process/index.rst + + - the Media development profile: + Documentation/driver-api/media/maintainer-entry-profile.rst + +- understanding of the projects' code base and coding style; +- ability to provide feedback to the patch authors; +- ability to judge when a patch might be ready for review and to submit; +- ability to write good code (last but certainly not least). + +Developers that desire to become maintainers are encouraged to participate +at the yearly Linux Media Summit, typically co-located with a Linux related +conference. These summits will be announced at the linux-media mailing list. + +If you are doing such tasks and have become a valued developer, an +existing Media Maintainer can nominate you to the Media Subsystem Maintainers. + +The ultimate responsibility for accepting a nominated maintainer is up to +the subsystem's maintainers. The nominated maintainer must have earned a trust
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 172
Quoted 10 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +10
-0+relationship with all Media Subsystem Maintainers, as, by becoming Media +Maintainer, you will take over part of their maintenance tasks. + +Media Committers +---------------- + +Experienced and trusted Media (Core) Maintainers may be granted commit rights +which allow them to directly push patches to the media development tree instead +of posting a Pull Request for the Media Subsystem Maintainers. This helps +offloading some of the work of the Media Subsystem Maintainers.
I believe the consensus was that anyone could be a committer, not only core maintainers.
IMHO there is no point in designing all this process for just 4 people.
I also prefer the original nomenclature for the roles:
Contributor: Anyone that posts a patch to the ML
Committer: Contributors that can commit (List provided by you) Core Committer: Laurent, Sakari, Sean and Sebastian (Names in the original presentation, should be updated)
Subsystem Maintainer: Mauro and Hans
In my head, a maintainer is someone that pushes to the upper tree, rebases and merges. In the media-committer tree that is only you and Mauro.
Quoted 269 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +161
-44+ +Media development tree +---------------------- + +The main development tree used by the media subsystem is hosted at +gitlab.freedesktop.org. LinuxTV.org hosts 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://gitlab.freedesktop.org/linux-media/media-committers.git + +Please note that this tree can be rebased, although only as a last resort. + +.. _Media development workflow: + +Media development workflow +++++++++++++++++++++++++++ + +All changes for the media subsystem shall be sent first as e-mails to the +media mailing list, following the process documented at +Documentation/process/index.rst. + +It means that patches shall be submitted as plain text only via e-mail to [email protected] (aka: LMML). While subscription is not mandatory, +you can find details about how to subscribe to it and to see its archives at: + + https://subspace.kernel.org/vger.kernel.org.html + +Emails with HTML will be automatically rejected by the mail server. + +It could be wise to also copy the Media Maintainer(s). You should use +``scripts/get_maintainers.pl`` to identify whom else needs to be copied. +Please always copy driver's authors and maintainers. + +To minimize the chance of merge conflicts for your patch series, and make +easier to backport patches to stable Kernels, we recommend that you use the +following baseline for your patch series: + +1. Features for the next mainline release: + + - baseline shall be the media-committers.git ``next`` branch; + +2. Bug fixes for the next mainline release: + + - baseline shall be the media-committers.git ``next`` branch. If the + changes depend on a fix from the media-committers.git + ``fixes`` branch, then you can use that as baseline. + +3. Bug fixes for the current mainline release (-rcX): + + - baseline shall be the latest mainline -rcX release or the + media-committers.git ``fixes`` branch if changes depend on a mainline + fix that is not yet merged; + +.. Note:: + + See https://www.kernel.org/category/releases.html for an overview + about Kernel release types. + +Patches with fixes shall have: + +- a ``Fixes:`` tag pointing to the first commit that introduced the bug; +- when applicable, a ``Cc: [email protected]``. + +Patches that were fixing bugs publicly reported by someone at the [email protected] mailing list shall have: + +- a ``Reported-by:`` tag immediately followed by a ``Closes:`` tag. + +Patches that change API shall update documentation accordingly at the +same patch series. + +See Documentation/process/index.rst for more details about e-mail submission. + +Once a patch is submitted, it may follow either one of the following +workflows: + +a. Media Maintainers' workflow: Media Maintainers post the PRs, which + are handled by the Media Subsystem Maintainers:: + + +-------+ +------------+ +------+ +-------+ +----------------------------+ + |e-mail |-->|picked up by|-->|code |-->|pull |-->|Subsystem Maintainers merge | + |to LMML| |patchwork | |review| |request| |in media-committers.git | + +-------+ +------------+ +------+ +-------+ +----------------------------+ + + For this workflow, pull requests are generated by Media Maintainers. + If you are not a Media Maintainer, then please don't submit pull requests, + as they will not be processed. + +b. Media Committers' workflow: patches are handled by Media Maintainers with + commit rights:: + + +-------+ +------------+ +------+ +--------------------------+ + |e-mail |-->|picked up by|-->|code |-->|Media Committers merge in | + |to LMML| |patchwork | |review| |media-committers.git | + +-------+ +------------+ +------+ +--------------------------+ + +When patches are picked up by patchwork and when merged at media-committers, +Media CI bots will check for errors and may provide e-mail feedback about +patch problems. When this happens, the patch submitter must fix them or +explain why the errors are false positives. + +Patches will only be moved to the next stage in these two workflows if they +pass on Media CI or if there are false-positives in the Media CI reports. + +For both workflows, all patches shall be properly reviewed at [email protected] (LMML) before being merged in media-committers.git. +Media patches will be reviewed in a timely manner by the maintainers and +reviewers as listed in the MAINTAINERS file. + +Media Maintainers shall request reviews from other Media Maintainers and +developers where applicable, i.e. because those developers have more +knowledge about some areas that are changed by a patch. + +There shall be no open issues or unresolved or conflicting feedback +from anyone. Clear them up first. Defer to the Media Subsystem +Maintainers if needed. + +Failures during e-mail submission ++++++++++++++++++++++++++++++++++ Media's workflow is heavily based on Patchwork, meaning that, once a patch is submitted, the e-mail will first be accepted by the mailing list@@ -47,51 +298,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 a longer time + 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 <[email protected]> +For more details about PGP sign, please read +Documentation/process/maintainer-pgp-guide.rst. -- HDMI CEC: - Hans Verkuil <[email protected]> +Subsystem Media Maintainers +--------------------------- -- Media controller drivers: - Laurent Pinchart <[email protected]> - -- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers: - Sakari Ailus <[email protected]> - -- V4L2 drivers and core V4L2 frameworks: - Hans Verkuil <[email protected]> - -The subsystem maintainer is: - Mauro Carvalho Chehab <[email protected]> - -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 <[email protected]> + - Hans Verkuil <[email protected]> Submit Checklist Addendum -------------------------@@ -106,18 +355,15 @@ that should be used in order to check if the drivers are properly implementing the media APIs: ==================== ======================================================= -Type Tool +Type Utility ==================== ======================================================= -V4L2 drivers\ [3]_ ``v4l2-compliance`` +V4L2 drivers\ [5]_ ``v4l2-compliance`` V4L2 virtual drivers ``contrib/test/test-media`` CEC drivers ``cec-compliance`` ==================== ======================================================= -.. [3] The ``v4l2-compliance`` also covers the media controller usage inside - V4L2 drivers. - -Other compliance tools are under development to check other parts of the -subsystem. +.. [5] The ``v4l2-compliance`` utility also covers the media controller usage + inside V4L2 drivers. Those tests need to pass before the patches go upstream.@@ -134,6 +380,8 @@ Where the check script is:: Be sure to not introduce new warnings on your patches without a very good reason. +Please see `Media development workflow`_ for e-mail submission rules. + Style Cleanup Patches +++++++++++++++++++++@@ -183,23 +431,23 @@ In particular, we accept lines with more than 80 columns: Key Cycle Dates --------------- -New submissions can be sent at any time, but if they intend to hit the +New submissions can be sent at any time, but if they are intended to hit the next merge window they should be sent before -rc5, and ideally stabilized in the linux-media branch by -rc6. Review Cadence -------------- -Provided that your patch is at https://patchwork.linuxtv.org, it should +Provided that your patch has landed in https://patchwork.linuxtv.org, it should be sooner or later handled, so you don't need to re-submit a patch. -Except for bug fixes, we don't usually add new patches to the development -tree between -rc6 and the next -rc1. +Except for important bug fixes, we don't usually add new patches to the +development tree between -rc6 and the next -rc1. Please notice that the media subsystem is a high traffic one, so it could take a while for us to be able to review your patches. Feel free to ping if you don't get a feedback in a couple of weeks or to ask -other developers to publicly add Reviewed-by and, more importantly, +other developers to publicly add ``Reviewed-by:`` and, more importantly, ``Tested-by:`` tags. Please note that we expect a detailed description for ``Tested-by:``, --2.51.0
Signature · 1 line
Ricardo Ribalda
Re: [PATCHv6 1/3] docs: media: update maintainer-entry-profile for multi-committers
Quoted 195 lines · Ricardo Ribalda
Hi Hans
Thanks for the new version
Quoted 190 lines · Hans Verkuil
From: Mauro Carvalho Chehab <[email protected]>
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 <[email protected]>Reviewed-by Ricardo Ribalda <[email protected]>Signed-off-by Hans Verkuil <[email protected]>--- .../media/maintainer-entry-profile.rst | 368 +++++++++++++++--- 1 file changed, 308 insertions(+), 60 deletions(-)Documentation/driver-api/media/maintainer-entry-profile.rst +136
-17@@ -4,19 +4,25 @@ Media Subsystem Profile Overview -------- -The media subsystem covers support for a variety of devices: stream -capture, analog and digital TV streams, cameras, remote controllers, HDMI CEC -and media pipeline control. +The Linux Media Community (aka: the LinuxTV Community) is formed of +developers working on Linux Kernel Media Subsystem, together with users +who also play an important role in testing the code. -It covers, mainly, the contents of those directories: +The Media Subsystem has code to support a wide variety of media-related +devices: stream capture, analog and digital TV streams, cameras, +video codecs, video processing (resizers, etc.), radio, remote controllers, +HDMI CEC and media pipeline control. + +The Media Subsystem consists of the following directories in the kernel +tree: - drivers/media - drivers/staging/media + - include/media + - Documentation/devicetree/bindings/media/\ [1]_ - Documentation/admin-guide/media - Documentation/driver-api/media - Documentation/userspace-api/media - - Documentation/devicetree/bindings/media/\ [1]_ - - include/media .. [1] Device tree bindings are maintained by the OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS maintainers@@ -27,19 +33,264 @@ It covers, mainly, the contents of those directories: Both media userspace and Kernel APIs are documented and the documentation must be kept in sync with the API changes. It means that all patches that add new features to the subsystem must also bring changes to the -corresponding API files. +corresponding API documentation. -Due to the size and wide scope of the media subsystem, media's -maintainership model is to have sub-maintainers that have a broad -knowledge of a specific aspect of the subsystem. It is the sub-maintainers' -task to review the patches, providing feedback to users if the patches are -following the subsystem rules and are properly using the media kernel and -userspace APIs. +A small subsystem will typically consist of driver maintainers (as listed +in the MAINTAINERS file) and one or two subsystem maintainers who merge +the patches when ready, maintain the subsystem core code and make the pull +requests to Linus. Due to the size and wide scope of the Media Subsystem +this does not scale and more maintainance layers are needed. -Patches for the media subsystem must be sent to the media mailing list -at [email protected] 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 Maintainers +----------------- + +The media subsystem has three layers of media maintainers: + +- Media Maintainer: + Responsible for a group of drivers within the Media Subsystem. Typically + these are all drivers that have something in common, e.g. codec drivers + or drivers from the same vendor. Media Maintainers provide feedback if the + patches are not following the subsystem rules, or are not using the + media kernel or userspace APIs correctly, or have poor code quality. They + also keep patchwork up to date, decide when patches are ready for merging, + and create Pull Requests for the Media Subsystem Maintainers to merge. + + A Media Maintainer 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). + +- Media Core Maintainer: + Media Maintainers who are also responsible for one or more media core + frameworks. + + Core framework changes are done via consensus between the relevant Media + Core Maintainers. Media Maintainers may include core framework changes in + their Pull Requests if they are signed off by the relevant Media Core + Maintainers. + +- Media Subsystem Maintainers: + Responsible for the subsystem as a whole, with access to the + entire subsystem. Responsible for merging Pull Requests from other + Media Maintainers. + + Userspace API/ABI changes are done via consensus between Media Subsystem + Maintainers\ [2]_. Media (Core) Maintainers may include API/ABI changes in + their Pull Requests if they are signed off by the all Media Subsystem + Maintainers. + +All Media Maintainers shall explicitly agree with the Kernel development process +as described at Documentation/process/index.rst and to the Kernel +development rules inside the Kernel documentation, including its code of +conduct. + +All Media Maintainers shall ensure that patchwork will reflect the current +status, e.g. patches shall be delegated to the Media Maintainer who is +handling them and the patch status shall be updated according to these rules: + +- ``Under Review``: Used if the patch requires a second opinion + or when it is part of a pull request; +- ``Accepted``: Once a patch is merged in the multi-committer tree. +- ``Superseded``: There is a newer version of the patch posted to the + mailing list. +- ``Duplicated``: There was another patch doing the same thing from someone + else that was accepted. +- ``Not Applicable``: Use for patch series that are not merged at media.git + tree (e.g. drm, dmabuf, upstream merge, etc.) but were cross-posted to the + linux-media mailing list. + +If the Media Maintainer decides not to accept a patch, then reply by email to +the patch authors, explaining why it is not accepted, and patchwork shall be +updated accordingly with either: + +- ``Changes Requested``: if a new revision was requested; +- ``Rejected``: if the proposed change is not acceptable at all. + +.. Note:: + + Patchwork supports a couple of clients to help semi-automating + status updates via its REST interface: + + https://patchwork.readthedocs.io/en/latest/usage/clients/ + +Media Maintainers are reachable via the #linux-media IRC channel at OFTC. + +.. [2] Everything that would break backward compatibility with existing + non-kernel code are API/ABI changes. This includes ioctl and sysfs + interfaces, v4l2 controls, and their behaviors. + +Becoming a Media Maintainer +--------------------------- + +The most important aspect of volunteering to be a Media Maintainer is that you +have demonstrated the ability to give good code reviews. So we are looking for +whether or not we think you will be good at doing that. + +As such, potential maintainers must earn enough credibility and trust from the +Linux Media Community. To do that, developers shall be familiar with the open +source model and have been active in the Linux Kernel community for some time, +and, in particular, in the media subsystem. + +In addition to actually making the code changes, you are basically +demonstrating your: + +- commitment to the project; +- ability to collaborate with the team and communicate well; +- understand of how upstream and the Linux Media Community work + (policies, processes for testing, code review, ...) +- reasonable knowledge about: + + - the Kernel development process: + Documentation/process/index.rst + + - the Media development profile: + Documentation/driver-api/media/maintainer-entry-profile.rst + +- understanding of the projects' code base and coding style; +- ability to provide feedback to the patch authors; +- ability to judge when a patch might be ready for review and to submit; +- ability to write good code (last but certainly not least). + +Developers that desire to become maintainers are encouraged to participate +at the yearly Linux Media Summit, typically co-located with a Linux related +conference. These summits will be announced at the linux-media mailing list. + +If you are doing such tasks and have become a valued developer, an +existing Media Maintainer can nominate you to the Media Subsystem Maintainers. + +The ultimate responsibility for accepting a nominated maintainer is up to
Quoted 8 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 169
Quoted 8 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +8
-0+the subsystem's maintainers. The nominated maintainer must have earned a trust +relationship with all Media Subsystem Maintainers, as, by becoming Media +Maintainer, you will take over part of their maintenance tasks. + +Media Committers +---------------- + +Experienced and trusted Media (Core) Maintainers may be granted commit rights
Based on Ricardo's question below this should probably be rewritten as:
'Media Maintainers and Media Core Maintainers'
I also think that this "Media Committers" section shouldn't be added in this patch, but in the next patch. It is clearer in the context of that one.
Quoted 7 lines
Documentation/driver-api/media/maintainer-entry-profile.rst It covers, mainly, the contents of those directories: · line 172
Quoted 3 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +3
-0+which allow them to directly push patches to the media development tree instead +of posting a Pull Request for the Media Subsystem Maintainers. This helps +offloading some of the work of the Media Subsystem Maintainers.I believe the consensus was that anyone could be a committer, not only core maintainers.
IMHO there is no point in designing all this process for just 4 people.
The maintainer-entry-profile section is about the responsibilities of a media maintainer. Committers are maintainers with commit rights, but you can be a maintainer without commit rights: either because you are not experienced/trusted enough, or because you don't want them in the first place. E.g., as CEC maintainer I have commit rights for drm. But I really want to give those up since it is so rare that I have patches for drm that it takes me too much time to figure out how it worked.
The reverse, being a committer without being a maintainer, makes no sense.
So this section describes the responsibilities of media maintainers, and the next patch describes the additional responsibilities of a media committer.
Note that, while I am not opposed to giving media driver maintainers commit rights, I prefer to add that when we actually have someone that falls in that category. It must be someone with a proven track record of understanding the bigger picture. And usually such people become media maintainers rather than staying just driver maintainers.
Quoted 9 lines
I also prefer the original nomenclature for the roles:
Contributor: Anyone that posts a patch to the ML
Committer: Contributors that can commit (List provided by you) Core Committer: Laurent, Sakari, Sean and Sebastian (Names in the original presentation, should be updated)
Subsystem Maintainer: Mauro and Hans
Quoted 3 lines
In my head, a maintainer is someone that pushes to the upper tree, rebases and merges. In the media-committer tree that is only you and Mauro.
No, a maintainer is someone who decides when patches are ready for mainline inclusion and posts PRs. A committer is a maintainer who can directly push patches to the git tree and can skip the PR step.
Previous versions of this series mixed those concepts, which was very confusing.
Regards,
Hans
Quoted 273 lines
Quoted 271 lines
Documentation/driver-api/media/maintainer-entry-profile.rst +161
-44+ +Media development tree +---------------------- + +The main development tree used by the media subsystem is hosted at +gitlab.freedesktop.org. LinuxTV.org hosts 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://gitlab.freedesktop.org/linux-media/media-committers.git + +Please note that this tree can be rebased, although only as a last resort. + +.. _Media development workflow: + +Media development workflow +++++++++++++++++++++++++++ + +All changes for the media subsystem shall be sent first as e-mails to the +media mailing list, following the process documented at +Documentation/process/index.rst. + +It means that patches shall be submitted as plain text only via e-mail to [email protected] (aka: LMML). While subscription is not mandatory, +you can find details about how to subscribe to it and to see its archives at: + + https://subspace.kernel.org/vger.kernel.org.html + +Emails with HTML will be automatically rejected by the mail server. + +It could be wise to also copy the Media Maintainer(s). You should use +``scripts/get_maintainers.pl`` to identify whom else needs to be copied. +Please always copy driver's authors and maintainers. + +To minimize the chance of merge conflicts for your patch series, and make +easier to backport patches to stable Kernels, we recommend that you use the +following baseline for your patch series: + +1. Features for the next mainline release: + + - baseline shall be the media-committers.git ``next`` branch; + +2. Bug fixes for the next mainline release: + + - baseline shall be the media-committers.git ``next`` branch. If the + changes depend on a fix from the media-committers.git + ``fixes`` branch, then you can use that as baseline. + +3. Bug fixes for the current mainline release (-rcX): + + - baseline shall be the latest mainline -rcX release or the + media-committers.git ``fixes`` branch if changes depend on a mainline + fix that is not yet merged; + +.. Note:: + + See https://www.kernel.org/category/releases.html for an overview + about Kernel release types. + +Patches with fixes shall have: + +- a ``Fixes:`` tag pointing to the first commit that introduced the bug; +- when applicable, a ``Cc: [email protected]``. + +Patches that were fixing bugs publicly reported by someone at the [email protected] mailing list shall have: + +- a ``Reported-by:`` tag immediately followed by a ``Closes:`` tag. + +Patches that change API shall update documentation accordingly at the +same patch series. + +See Documentation/process/index.rst for more details about e-mail submission. + +Once a patch is submitted, it may follow either one of the following +workflows: + +a. Media Maintainers' workflow: Media Maintainers post the PRs, which + are handled by the Media Subsystem Maintainers:: + + +-------+ +------------+ +------+ +-------+ +----------------------------+ + |e-mail |-->|picked up by|-->|code |-->|pull |-->|Subsystem Maintainers merge | + |to LMML| |patchwork | |review| |request| |in media-committers.git | + +-------+ +------------+ +------+ +-------+ +----------------------------+ + + For this workflow, pull requests are generated by Media Maintainers. + If you are not a Media Maintainer, then please don't submit pull requests, + as they will not be processed. + +b. Media Committers' workflow: patches are handled by Media Maintainers with + commit rights:: + + +-------+ +------------+ +------+ +--------------------------+ + |e-mail |-->|picked up by|-->|code |-->|Media Committers merge in | + |to LMML| |patchwork | |review| |media-committers.git | + +-------+ +------------+ +------+ +--------------------------+ + +When patches are picked up by patchwork and when merged at media-committers, +Media CI bots will check for errors and may provide e-mail feedback about +patch problems. When this happens, the patch submitter must fix them or +explain why the errors are false positives. + +Patches will only be moved to the next stage in these two workflows if they +pass on Media CI or if there are false-positives in the Media CI reports. + +For both workflows, all patches shall be properly reviewed at [email protected] (LMML) before being merged in media-committers.git. +Media patches will be reviewed in a timely manner by the maintainers and +reviewers as listed in the MAINTAINERS file. + +Media Maintainers shall request reviews from other Media Maintainers and +developers where applicable, i.e. because those developers have more +knowledge about some areas that are changed by a patch. + +There shall be no open issues or unresolved or conflicting feedback +from anyone. Clear them up first. Defer to the Media Subsystem +Maintainers if needed. + +Failures during e-mail submission ++++++++++++++++++++++++++++++++++ Media's workflow is heavily based on Patchwork, meaning that, once a patch is submitted, the e-mail will first be accepted by the mailing list@@ -47,51 +298,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 a longer time + 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 <[email protected]> +For more details about PGP sign, please read +Documentation/process/maintainer-pgp-guide.rst. -- HDMI CEC: - Hans Verkuil <[email protected]> +Subsystem Media Maintainers +--------------------------- -- Media controller drivers: - Laurent Pinchart <[email protected]> - -- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers: - Sakari Ailus <[email protected]> - -- V4L2 drivers and core V4L2 frameworks: - Hans Verkuil <[email protected]> - -The subsystem maintainer is: - Mauro Carvalho Chehab <[email protected]> - -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 <[email protected]> + - Hans Verkuil <[email protected]> Submit Checklist Addendum -------------------------@@ -106,18 +355,15 @@ that should be used in order to check if the drivers are properly implementing the media APIs: ==================== ======================================================= -Type Tool +Type Utility ==================== ======================================================= -V4L2 drivers\ [3]_ ``v4l2-compliance`` +V4L2 drivers\ [5]_ ``v4l2-compliance`` V4L2 virtual drivers ``contrib/test/test-media`` CEC drivers ``cec-compliance`` ==================== ======================================================= -.. [3] The ``v4l2-compliance`` also covers the media controller usage inside - V4L2 drivers. - -Other compliance tools are under development to check other parts of the -subsystem. +.. [5] The ``v4l2-compliance`` utility also covers the media controller usage + inside V4L2 drivers. Those tests need to pass before the patches go upstream.@@ -134,6 +380,8 @@ Where the check script is:: Be sure to not introduce new warnings on your patches without a very good reason. +Please see `Media development workflow`_ for e-mail submission rules. + Style Cleanup Patches +++++++++++++++++++++@@ -183,23 +431,23 @@ In particular, we accept lines with more than 80 columns: Key Cycle Dates --------------- -New submissions can be sent at any time, but if they intend to hit the +New submissions can be sent at any time, but if they are intended to hit the next merge window they should be sent before -rc5, and ideally stabilized in the linux-media branch by -rc6. Review Cadence -------------- -Provided that your patch is at https://patchwork.linuxtv.org, it should +Provided that your patch has landed in https://patchwork.linuxtv.org, it should be sooner or later handled, so you don't need to re-submit a patch. -Except for bug fixes, we don't usually add new patches to the development -tree between -rc6 and the next -rc1. +Except for important bug fixes, we don't usually add new patches to the +development tree between -rc6 and the next -rc1. Please notice that the media subsystem is a high traffic one, so it could take a while for us to be able to review your patches. Feel free to ping if you don't get a feedback in a couple of weeks or to ask -other developers to publicly add Reviewed-by and, more importantly, +other developers to publicly add ``Reviewed-by:`` and, more importantly, ``Tested-by:`` tags. Please note that we expect a detailed description for ``Tested-by:``, --2.51.0
Re: [PATCHv6 1/3] docs: media: update maintainer-entry-profile for multi-committers
Quoted 20 lines · On Fri, 23 Jan 2026 14:42:30 +0100 Hans Verkuil <[email protected]>…
Quoted 15 lines · Ricardo Ribalda
Hi Hans
Thanks for the new version
Quoted 1 line · Hans Verkuil
I also prefer the original nomenclature for the roles:
Contributor: Anyone that posts a patch to the ML
Committer: Contributors that can commit (List provided by you) Core Committer: Laurent, Sakari, Sean and Sebastian (Names in the original presentation, should be updated)
Subsystem Maintainer: Mauro and HansQuoted 3 lines
In my head, a maintainer is someone that pushes to the upper tree, rebases and merges. In the media-committer tree that is only you and Mauro.
Quoted 5 lines
No, a maintainer is someone who decides when patches are ready for mainline inclusion and posts PRs. A committer is a maintainer who can directly push patches to the git tree and can skip the PR step.
Previous versions of this series mixed those concepts, which was very confusing.
The problem with this version is that it is also mixing/overriding nomenclatures. Basically:
- a maintainer is anyone with his name at MAINTAINERS file;
- subsystem maintainer is also a clear concept.
We need to avoid more mess to the "maintainer" here. This was clearer at the previous version, as "committer" and "core committer" are clear concepts and won't conflict with existing nomenclature, but now that we're splitting committer function as an orthogonal attribute (nothing against that), we need better names for the maintainers that are described on this profile. maybe:
- media core maintainer: for people responsible to maintain part of the media framework;
- media driver maintainer: for everyone else that is listed at MAINTAINERS with stuff under drivers/media and/or drivers/staging/media(*) and it is not a media core maintainer.
(*) Should the ones with drivers only at staging be placed on
a different group like "staging media driver maintainer"?
Regards,
Mauro
PATCH v6 2/3 docs: media: document media multi-committers rules and process
In reply to Hans VerkuilFrom: Mauro Carvalho Chehab <[email protected]>
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.
--- Documentation/driver-api/media/index.rst | 1 + .../media/maintainer-entry-profile.rst | 13 ++ .../driver-api/media/media-committer.rst | 196 ++++++++++++++++++ 3 files changed, 210 insertions(+) create mode 100644 Documentation/driver-api/media/media-committer.rst
Documentation/driver-api/media/index.rst +1 -0
@@ -26,6 +26,7 @@ Documentation/userspace-api/media/index.rst :numbered: maintainer-entry-profile + media-committer v4l2-core dtv-core
Documentation/driver-api/media/maintainer-entry-profile.rst +13 -0
@@ -171,6 +171,9 @@ which allow them to directly push patches to the media development tree instead of posting a Pull Request for the Media Subsystem Maintainers. This helps offloading some of the work of the Media Subsystem Maintainers. +More details about Media Committers' roles and responsibilities can be +found here: :ref:`Media Committers`. + Media development tree ----------------------
@@ -332,9 +335,19 @@ See: :ref:`kernel_org_trust_repository`. With the pull request workflow, pull requests shall use PGP-signed tags. +With the committers' workflow, this is ensured at the time merge request +rights will be granted to the gitlab instance used by the media-committers.git +tree, after receiving the e-mail documented in +:ref:`media-committer-agreement`. + For more details about PGP sign, please read Documentation/process/maintainer-pgp-guide.rst. +Maintaining media maintainer status +----------------------------------- + +See :ref:`Maintain Media Status`. + Subsystem Media Maintainers ---------------------------
Documentation/driver-api/media/media-committer.rst new file +196 -0
196 lines not on this page · raw message
Signature · 1 line
2.51.0
PATCH v6 3/3 docs: media: document Media Maintainers
In reply to Hans VerkuilDocument who the Media Maintainers are and what their responsibilities are.
--- .../media/maintainer-entry-profile.rst | 40 +++++++++++++++++-- 1 file changed, 37 insertions(+), 3 deletions(-)
Documentation/driver-api/media/maintainer-entry-profile.rst +37 -3
@@ -348,13 +348,47 @@ Maintaining media maintainer status See :ref:`Maintain Media Status`. -Subsystem Media Maintainers ---------------------------- +List of Media Maintainers +------------------------- -The subsystem maintainers are: +The Media Subsystem Maintainers are: - Mauro Carvalho Chehab <[email protected]> - Hans Verkuil <[email protected]> +The Media Core Maintainers are: + - Sakari Ailus <[email protected]> + + - ISP + - sensor drivers + - v4l2-async and v4l2-fwnode core frameworks + - v4l2-flash-led-class core framework + + - Mauro Carvalho Chehab <[email protected]> + + - DVB + - Laurent Pinchart <[email protected]> + + - Media controller drivers + - Core media controller framework + - Hans Verkuil <[email protected]> + + - V4L2 drivers + - V4L2 and videobuf2 core frameworks + - HDMI CEC drivers + - HDMI CEC core framework + - Sean Young <[email protected]> + + - Remote Controller (infrared) drivers + - Remote Controller (infrared) core framework + +The Media Maintainers are: + - Nicolas Dufresne <[email protected]> + + - Codec drivers + - Bryan O'Donoghue <[email protected]> + + - Qualcomm drivers + Submit Checklist Addendum -------------------------
Signature · 1 line
2.51.0