From patchwork Fri Nov 29 09:31:45 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 13888588 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 6DE7C1586C8; Fri, 29 Nov 2024 11:15:09 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1732878909; cv=none; b=k4Mqyzww/hQe1sg39QK6/HZdkRBFqJKdBZWO83kgiDD4nwd+iuzungtQInUWoLRB4iO26tE3WhADN4yz2MhU7fD/T1TyKaN8xcMawbl/dF9kx3Vk1y/vd+N9u3z+dLh6ktUHFGO4GHgR44p2pcCbS6EGq1OI2fFHipcGBNd1P4Q= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1732878909; c=relaxed/simple; bh=g+vqenjgG+4hoUPvWp7gzWtx2UWJA8zid7qPRdVzQic=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=W7Cpc6bBqrXRAmZFjeXZx6REKKDWYjhdY++FKaF4x6ZzChX8emcGmK5WW+uSWMEuOcu4iZg3RQHnPZup9vdXZaAW9atM6Ma1VcfIDOzXDIbzq6ihbGwIQ/kq2GPdQ4Zchjv+gJUy/Kmf7nwkveFBoO7kZ9R1LggCitJZ7kjFhbw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=YvgqKuG0; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="YvgqKuG0" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B79BCC4CECF; Fri, 29 Nov 2024 11:15:08 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1732878908; bh=g+vqenjgG+4hoUPvWp7gzWtx2UWJA8zid7qPRdVzQic=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YvgqKuG0Soc1Wk4Wc5eyjw23Lt4felx0dsImAN+kpiQ3SkqbiylSov7kjuKz2cAPu Vpx5HzFKFjcCmxlczOEp0VwOgTLXAWeMzBVHzn8Q0X3cqCMWyYLLHKWvOoFohiGNUf JG2H7xOGvRJDyqqrEWnVu3I6srHkrjL6zwIJec4WuZwLPuO376zCze1/OwsS22iPAk L4xfDCy33jYKLh7I2neyd/D+/vbE1j0zte5eMczxmwDheyG7RW0sMdsldOIf7dlNnr 2kFlF3ks2HS6nda8HVVZDp2DDBDtZobstwqhKVuyZavs9eLdhGlcyIiUcDDGMlfLH7 6YGHoURdAlzGg== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tGxM0-0000000AVUW-2opx; Fri, 29 Nov 2024 10:32:00 +0100 From: Mauro Carvalho Chehab To: Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, linux-media@vger.kernel.org, Hans Verkuil Subject: [PATCH v2 1/2] docs: media: update maintainer-entry-profile for multi-committers Date: Fri, 29 Nov 2024 10:31:45 +0100 Message-ID: <99e1b9df713827ce2e6c21073276c97030071a07.1732872169.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.47.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-media@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Sender: Mauro Carvalho Chehab As the media subsystem will experiment with a multi-committers model, update the Maintainer's entry profile to the new rules. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Hans Verkuil Reviewed-by: Ricardo Ribalda --- .../media/maintainer-entry-profile.rst | 203 ++++++++++++++---- MAINTAINERS | 1 + 2 files changed, 158 insertions(+), 46 deletions(-) diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst index ffc712a5f632..47f15fad7f9f 100644 --- a/Documentation/driver-api/media/maintainer-entry-profile.rst +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst @@ -27,19 +27,133 @@ It covers, mainly, the contents of those directories: Both media userspace and Kernel APIs are documented and the documentation must be kept in sync with the API changes. It means that all patches that add new features to the subsystem must also bring changes to the -corresponding API files. +corresponding API documentation files. -Due to the size and wide scope of the media subsystem, media's -maintainership model is to have sub-maintainers that have a broad -knowledge of a specific aspect of the subsystem. It is the sub-maintainers' -task to review the patches, providing feedback to users if the patches are +Due to the size and wide scope of the media subsystem, the media's +maintainership model is to have committers that have a broad knowledge of +a specific aspect of the subsystem. It is the committers' task to +review the patches, providing feedback to users if the patches are following the subsystem rules and are properly using the media kernel and userspace APIs. -Patches for the media subsystem must be sent to the media mailing list -at linux-media@vger.kernel.org as plain text only e-mail. Emails with -HTML will be automatically rejected by the mail server. It could be wise -to also copy the sub-maintainer(s). +Media committers +---------------- + +In the media subsystem, there are experienced developers who can push +patches directly to the development tree. These developers are called +Media committers and are divided into the following categories: + +- Committers: responsible for one or more drivers within the media subsystem. + They can push changes to the tree that do not affect the core or ABI. + +- Core committers: responsible for part of the media core. They are typically + responsible for one or more drivers within the media subsystem, but, besides + that, they can also merge patches that change the code common to multiple + drivers, including the kernel internal API. + +- Subsystem maintainers: responsible for the subsystem as a whole, with + access to the entire subsystem. + + Only subsystem maintainers can push changes that affect the userspace + API/ABI. + +Media committers shall explicitly agree with the Kernel development process +as described at Documentation/process/index.rst and to the Kernel +development rules inside the Kernel documentation, including its code of +conduct. + +Media development tree +---------------------- + +The main development tree used by the media subsystem is hosted at LinuxTV.org, +where we also maintain news about the subsystem, wiki pages and a patchwork +instance where we track patches though their lifetime. + +The main tree used by media developers is at: + +https://git.linuxtv.org/media.git/ + +.. _Media development workflow: + +Media development workflow +++++++++++++++++++++++++++ + +All changes for the media subsystem must be sent first as e-mails to the +media mailing list, following the process documented at +Documentation/process/index.rst. + +It means that patches shall be submitted as plain text only via e-mail to: + + `https://subspace.kernel.org/vger.kernel.org.html `_ + +Emails with HTML will be automatically rejected by the mail server. + +It could be wise to also copy the media committer(s). You should use +``scripts/get_maintainers.pl`` to identify whom else needs to be copied. +Please always copy driver's authors and maintainers. + +Such patches need to be based against a public branch or tag as follows: + +1. Patches for new features need to be based at the ``next`` branch of + media.git tree; + +2. Fixes against an already released kernel should preferably be against + the latest released Kernel. If they require a previously-applied + change at media.git tree, they need to be against its ``fixes`` branch. + +3. Fixes for issues not present at the latest released kernel should + preferably be against the latest -rc1 Kernel. If they require a + previously-applied change at media.git tree, they need to be against + its ``fixes`` branch. + +Patches with fixes shall have: +- a ``Fixes:`` tag pointing to the first commit that introduced the bug; +- when applicable, a ``Cc: stable@vger.kernel.org``. + +Patches that were fixing bugs publicly reported by someone at the +linux-media@vger.kernel.org mailing list shall have: +- a ``Reported-by:`` tag immediately followed by a ``Closes:`` tag. + +Patches that change API shall update documentation accordingly at the +same patch series. + +See Documentation/process/index.rst for more details about e-mail submission. + +Once a patch is submitted, it may follow either one of the following +workflows: + +a. Pull request workflow: patches are handled by subsystem maintainers:: + + +------+ +---------+ +-------+ +-----------------------+ +---------+ + |e-mail|-->|patchwork|-->|pull |-->|maintainers merge |-->|media.git| + +------+ |picks it | |request| |in media-committers.git| +---------+ + +---------+ +-------+ +-----------------------+ + + For this workflow, pull requests can be generated by a committer, + a previous committer, subsystem maintainers or by a couple of trusted + long-time contributors. If you are not in such group, please don't submit + pull requests, as they will likely be ignored. + +b. Committers' workflow: patches are handled by media committers:: + + +------+ +---------+ +--------------------+ +-----------+ +---------+ + |e-mail|-->|patchwork|-->|committers merge at |-->|maintainers|-->|media.git| + +------+ |picks it | |media-committers.git| |approval | +---------+ + +---------+ +--------------------+ +-----------+ + +On both workflows, all patches shall be properly reviewed at +linux-media@vger.kernel.org before being merged at media-committers.git. + +When patches are picked by patchwork and when merged at media-committers, +CI bots will check for errors and may provide e-mail feedback about +patch problems. When this happens, the patch submitter must fix them +and send another version of the patch. + +Patches will only be moved to the next stage in those two workflows if they +don't fail on CI or if there are false-positives in the CI reports. + +Failures during e-mail submission ++++++++++++++++++++++++++++++++++ Media's workflow is heavily based on Patchwork, meaning that, once a patch is submitted, the e-mail will first be accepted by the mailing list @@ -47,51 +161,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 [2]_, 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\ [3]_ 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 a logic that checks if the +received e-mail contain a valid patch. Any whitespace and new line +breakages mangling the patch won't be recognized by patchwork, thus such +patch will be rejected. + +.. [2] It usually takes a few minutes for the patch to arrive, but + the e-mail server may be busy, so it may take up to a few hours + for a patch to be picked by patchwork. + +.. [3] 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 sign, via the +: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 a GPG-signed tag. -- Remote Controllers (infrared): - Sean Young +For more details about PGP sign, please read +Documentation/process/maintainer-pgp-guide.rst. -- HDMI CEC: - Hans Verkuil +Subsystem maintainers +--------------------- -- Media controller drivers: - Laurent Pinchart - -- ISP, v4l2-async, v4l2-fwnode, v4l2-flash-led-class and Sensor drivers: - Sakari Ailus - -- V4L2 drivers and core V4L2 frameworks: - Hans Verkuil - -The subsystem maintainer is: - Mauro Carvalho Chehab - -Media maintainers may delegate a patch to other media maintainers as needed. -On such case, checkpatch's ``delegate`` field indicates who's currently -responsible for reviewing a patch. +The subsystem maintainers are: + - Mauro Carvalho Chehab and + - Hans Verkuil Submit Checklist Addendum ------------------------- @@ -108,17 +220,14 @@ implementing the media APIs: ==================== ======================================================= Type Tool ==================== ======================================================= -V4L2 drivers\ [3]_ ``v4l2-compliance`` +V4L2 drivers\ [4]_ ``v4l2-compliance`` V4L2 virtual drivers ``contrib/test/test-media`` CEC drivers ``cec-compliance`` ==================== ======================================================= -.. [3] The ``v4l2-compliance`` also covers the media controller usage inside +.. [4] The ``v4l2-compliance`` also covers the media controller usage inside V4L2 drivers. -Other compilance tools are under development to check other parts of the -subsystem. - Those tests need to pass before the patches go upstream. Also, please notice that we build the Kernel with:: @@ -134,6 +243,8 @@ Where the check script is:: Be sure to not introduce new warnings on your patches without a very good reason. +Please see `Media development workflow`_ for e-mail submission rules. + Style Cleanup Patches +++++++++++++++++++++ @@ -199,7 +310,7 @@ tree between -rc6 and the next -rc1. Please notice that the media subsystem is a high traffic one, so it could take a while for us to be able to review your patches. Feel free to ping if you don't get a feedback in a couple of weeks or to ask -other developers to publicly add Reviewed-by and, more importantly, +other developers to publicly add ``Reviewed-by:`` and, more importantly, ``Tested-by:`` tags. Please note that we expect a detailed description for ``Tested-by:``, diff --git a/MAINTAINERS b/MAINTAINERS index 6db07b8fa215..f9bdef1b5966 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -14193,6 +14193,7 @@ MEDIA INPUT INFRASTRUCTURE (V4L/DVB) M: Mauro Carvalho Chehab L: linux-media@vger.kernel.org S: Maintained +P: Documentation/driver-api/media/maintainer-entry-profile.rst W: https://linuxtv.org Q: http://patchwork.kernel.org/project/linux-media/list/ T: git git://linuxtv.org/media_tree.git From patchwork Fri Nov 29 09:31:46 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 13888590 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id AA01E1993B7; Fri, 29 Nov 2024 11:15:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1732878922; cv=none; b=CjEcK81yDtUEhD3mVzhP/ZTvFpbSR5zn10rxLT/3csj9uPMVbV2sthRExEmKnRLnBEh+P+0sbs40q44XyfiYZw6BLDtZgvtEOrTk8utdI61E18BuI46pom2ZJlYmBh4IytV7NsslxjVnRNdp3hkT3B8N0a4bXYPE8WtN5ar0wkE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1732878922; c=relaxed/simple; bh=sylh7e9+iQo7mr6gOgMedtHqvg1CXUIxiUi1qpqtErI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=puF0OkTfh5dwHl95PUeodDq9oUrd8ig+OPP2ZgRA/0gedwO0E20RVcv//+Cx4ZHvPg2WZnYB2j1EZ/KS5VGWuPAtUw0ip1avj9PZubR+KjNQygiP3PDYai6y3BQEnsdeaARCZIMr54iSb4AwQY8KophRW2m6lASV6FMviGsaD+Y= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RDWoFtW/; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="RDWoFtW/" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 37649C4CECF; Fri, 29 Nov 2024 11:15:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1732878922; bh=sylh7e9+iQo7mr6gOgMedtHqvg1CXUIxiUi1qpqtErI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RDWoFtW/0vdX8oGsTBvvyp8Zas47iAN1ptOip1Ym6KfZOyXij/EQfhWKAM1EsF1TY a9WC3E1GIgfdgPvrsRwpjkFzMbdKeIH1sZ+HQWiIByCie7/FkAM1BVMpeCybExoW62 0U+oy/P4ntNyVPpQLFDFJFiy47D32xjbfX5QhzcyfKOIbjUkqeTF8zdmlmOnVjOtJ8 L7L0+aTyO50nOLDvLHrxws6Hsk2F6mTT0zErgzS9S+qEGnB35R+8z4l5xkBL5rAAzE CRAgxgKWWKvqn3j6QzDV7NpQEKtbcVRqpso3br5Dn/ZDoMA/ac6rYrMaDz5lnak3QT Nb/w0yBmTjhWg== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tGxM0-0000000AVUZ-2woI; Fri, 29 Nov 2024 10:32:00 +0100 From: Mauro Carvalho Chehab To: Cc: Mauro Carvalho Chehab , Jonathan Corbet , Mauro Carvalho Chehab , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-media@vger.kernel.org, workflows@vger.kernel.org, Hans Verkuil Subject: [PATCH v2 2/2] docs: media: document media multi-committers rules and process Date: Fri, 29 Nov 2024 10:31:46 +0100 Message-ID: X-Mailer: git-send-email 2.47.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-media@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Sender: Mauro Carvalho Chehab As the media subsystem will experiment with a multi-committers model, update the Maintainer's entry profile to the new rules, and add a file documenting the process to become a committer and to maintain such rights. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Hans Verkuil Reviewed-by: Ricardo Ribalda --- Documentation/driver-api/media/index.rst | 1 + .../media/maintainer-entry-profile.rst | 8 + .../driver-api/media/media-committer.rst | 278 ++++++++++++++++++ .../process/maintainer-pgp-guide.rst | 2 + 4 files changed, 289 insertions(+) create mode 100644 Documentation/driver-api/media/media-committer.rst diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst index d5593182a3f9..d0c725fcbc67 100644 --- a/Documentation/driver-api/media/index.rst +++ b/Documentation/driver-api/media/index.rst @@ -26,6 +26,7 @@ Documentation/userspace-api/media/index.rst :numbered: maintainer-entry-profile + media-committer v4l2-core dtv-core diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst index 47f15fad7f9f..650803c30c41 100644 --- a/Documentation/driver-api/media/maintainer-entry-profile.rst +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst @@ -62,6 +62,9 @@ as described at Documentation/process/index.rst and to the Kernel development rules inside the Kernel documentation, including its code of conduct. +More details about media commiters' roles and responsibilities can be +found here: Documentation/driver-api/media/media-committer.rst. + Media development tree ---------------------- @@ -195,6 +198,11 @@ shall be validated by using PGP sign, via the With the pull request workflow, pull requests shall use a GPG-signed tag. +With the committers' workflow, this is ensured at the time merge request +rights will be granted to the gitlab instance used by media-committers.git +tree, after receiving the e-mail documented at +:ref:`media-committer-agreement`. + For more details about PGP sign, please read Documentation/process/maintainer-pgp-guide.rst. diff --git a/Documentation/driver-api/media/media-committer.rst b/Documentation/driver-api/media/media-committer.rst new file mode 100644 index 000000000000..1756a7af6353 --- /dev/null +++ b/Documentation/driver-api/media/media-committer.rst @@ -0,0 +1,278 @@ +Media committers +================ + +What is a media committer? +-------------------------- + +A media committer is a developer who can push patches from other developers +and their own patches to the +`media-committers `_ +tree. + +It is a media committer's duty to ensure that their entries in the MAINTAINERS +file are kept up-to-date, and that submitted patches for files for which +they are listed as maintainers are timely reviewed on the mailing list, +ideally not waiting in patchwork as ``New`` for more than one Kernel merge +cycle, and, if accepted, applying them at the media committer's tree. + +These commit rights are granted with some expectation of responsibility: +committers are people who care about the Linux Kernel as a whole and +about the Linux media subsystem and want to help its development. It +is also based on a trust relationship between the rest of the committers, +maintainers and the Linux Media community. + +The Linux Media community, also called LinuxTV community, has its primary +site at https://linuxtv.org. + +As such, a media committer is not just someone who is capable of creating +code, but someone who has demonstrated their ability to collaborate +with the team, get the most knowledgeable people to review code, +contribute high-quality code, and follow through to fix issues (in code +or tests). + +.. Note:: + + 1. If a patch introduces a regression, then it is the media committer's + responsibility to correct that as soon as possible. Typically the + patch is either reverted, or an additional patch is committed that + fixes the regression; + 2. if patches are fixing bugs against already released Kernels, including + the reverts above mentioned, the media committer shall add the needed + tags. Please see :ref:`Media development workflow` for more details. + +Becoming a media committer +-------------------------- + +The most important aspect of volunteering to be a committer is that you have +demonstrated the ability to give good code reviews. So we are looking for +whether or not we think you will be good at doing that. + +As such, potential committers must earn enough credibility and trust from the +LinuxTV community. To do that, developers shall be familiar with the open +source model and have been active in the Linux Kernel community for some time, +and, in particular, in the media subsystem. + +So, in addition to actually making the code changes, you are basically +demonstrating your: + +- commitment to the project; +- ability to collaborate with the team and communicate well; +- understand of how upstream and the LinuxTV 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 intend to become committers are encouraged to participate +at the yearly Linux Media Summit, typically co-located with another Linux +conference. + +If you are doing such tasks and have become a valued developer, an +existing committer can nominate you to the media subsystem maintainers. + +The ultimate responsibility for accepting a nominated committer is up to +the subsystem's maintainers. The committers must earn a trust relationship +with all subsystem maintainers, as, by granting you commit rights, they will +be delegating part of their maintenance tasks. + +Due to that, to become a committer or a core committer, a consensus between +all subsystem maintainers is required, as they all need to trust a developer +well enough to be delegated the responsibility to maintain part of the code +and to properly review patches from third parties, in a timely manner and +keeping the status of the reviewed code at https://patchwork.linuxtv.org +updated. + +.. Note:: + + In order to preserve/protect the developers that could have their commit + rights granted, denied or removed as well as the subsystem maintainers who + have the task to accept or deny commit rights, all communication related to + nominating a committer, preserving commit rights or leaving such function + should happen in private as much as possible. + +.. _media-committer-agreement: + +Media committer's agreement +--------------------------- + +Once a nominated committer is accepted by all subsystem maintainers, +they will ask if the developer is interested in the nomination and discuss +what area(s) of the media subsystem the committer will be responsible for. + +Once the developer accepts being a committer, the new committer shall +explicitly accept the Kernel development policies described under its +Documentation/, and, in particular to the rules on this document, by writing +an e-mail to media-committers@linuxtv.org, with a declaration of intent +following the model below:: + + I, John Doe, would like to change my status to: Committer + + I intend to actively develop the XYZ driver, send fixes to drivers + that I can test, optionally reviewing patches and merging trivial + fixes in other areas of the subsystem, ... + + For the purpose of committing patches to the media-committer's tree, + I'll be using my user https://gitlab.freedesktop.org/users/. + +Followed by a formal declaration of agreement with the Kernel development +rules:: + + I hereby declare that I agree with the Kernel development rules described at: + + https://www.kernel.org/doc/html/latest/driver-api/media/media-committer.rst + + and to the Linux Kernel development process rules. + + I agree to the Code of Conduct as documented in: + https://www.kernel.org/doc/html/latest/process/code-of-conduct.rst + + I am aware that I can, at any point of time, retire. In that case, I will + send an e-mail to notify the subsystem maintainers for them to revoke my + commit rights. + + I am aware that the Kernel development rules change over time. + By doing a new push to media-commiter tree, I understand that I agree + with the rules in effect at the time of the commit. + +Such e-mail shall be signed with a PGP key cross signed by other Kernel and +media developers. As described at :ref:`media-developers-gpg`_, the PGP +signature, together with the gitlab user security are fundamental components +that ensure the authentity of the merge requests that will happen at the +media-committer.git tree. + +In case the kernel development process changes, by merging new commits +in the +`media-committer tree `_, +the media committer implicitly declares their agreement with the latest +version of the documented process including the contents of this file. + +.. note:: + + 1. Changes to the kernel media development process should be announced in + the media-committers mailinglist with a reasonable review period. All + committers are automatically subscribed to that mailinglist; + 2. Due to the distributed nature of the Kernel development, it is + possible that kernel development process changes may end being + reviewed/merged at the linux-docs mailing list, specially for the + contents under Documentation/process and for trivial typo fixes. + +Core committers +--------------- + +As described in Documentation/driver-api/media/maintainer-entry-profile.rst +a committer may be granted with additional rights to also be able to +change a core file and/or media subsystem's Kernel API. The extent of +the core committer's grants will be detailed by the subsystem maintainers +when they nominate a core committer. + +Existing committers may become core committers and vice versa. Such +decisions will be taken in consensus between the subsystem maintainers. + +Media committers rules +---------------------- + +Media committers shall do their best efforts to avoid merged patches that +would break any existing drivers. If it breaks, fixup or revert patches +shall be merged as soon as possible, aiming to be merged at the same Kernel +cycle the bug is reported. + +Media committers shall behave accordingly to the rights granted by +the subsystem maintainers, specially with regards of the scope of changes +they may apply directly at the media-committers tree. Such scope can +change over time on a mutual agreement between media committers and +maintainers. + +As described at :ref:`Media development workflow`, there are workflows. +For the committers' workflow, the following rules apply: + +- Each merged patch shall pass CI tests; + +- Media committers shall request reviews from other committers and + developers where applicable, i.e. because those developers have more + knowledge about some areas that are changed by a patch; + +- There shall be no open issues or unresolved or conflicting feedback + from anyone. Clear them up first. Defer to subsystem maintainers as needed. + +Patches that do not fall under the committer's workflow criteria will follow +the pull request workflow as described at :ref:`Media development workflow`. + +Only a subsystem maintainer can override such rules. + +All media committers shall ensure that patchwork will reflect the current +status, e.g. patches shall be delegated to the media committer who is +handling them and the patch status shall be updated according to these rules: + +- ``Under review``: Used if the patch requires a second opinion + or when it is part of a pull request; +- ``Accepted``: Once a patch is merged in the multi-committer tree. +- ``Superseded``: There is a newer version of the patch posted to the + mailing list. +- ``Duplicated``: There was another patch doing the same thing from someone + else that was accepted. +- ``Not Applicable``: Use for patch series that are not merged at media.git + tree (e.g. drm, dmabuf, upstream merge, etc.) but were cross-posted to the + linux-media mailing list. + +If the committer decides not to merge it, then reply by email to patch +authors, explaining why it is not merged, and patchwork shall be updated +accordingly with either: + +- ``Changes Requested``: if a new revision was requested; +- ``Rejected``: if the proposed change won't be merged upstream. + +If a media committer decides to retire, it is the committer's duty to +notify the subsystem maintainers about that decision. + +.. Note:: + + Patchwork supports a couple of clients to help semi-automating + status updates via its REST interface: + + https://patchwork.readthedocs.io/en/latest/usage/clients/ + +Maintaining media committer status +---------------------------------- + +A community of committers working together to move the Linux Kernel +forward is essential to creating successful projects that are rewarding +to work on. If there are problems or disagreements within the community, +they can usually be solved through healthy discussion and debate. + +In the unhappy event that a media committer continues to disregard good +citizenship (or actively disrupts the project), we may need to revoke +that person's status. In such cases, if someone suggests the revocation +with a good reason, then after discussing this among the media committers, +the final decision is taken by the subsystem maintainers. As the decision +to become a media committer comes from a consensus between subsystem +maintainers, a single subsystem maintainer not trusting the media committer +anymore is enough to revoke committer's grants. + +If a committer is inactive for more than a couple of Kernel cycles, +maintainers will try to reach you via e-mail. If not possible, they may +revoke your committer grants and update MAINTAINERS file entries +accordingly. If you wish to resume contributing later on, then contact +the subsystem maintainers to ask if your rights can be restored. + +A previous committer that had their commit rights revoked can keep +contributing to the subsystem via the pull request workflow as documented +at the :ref:`Media development workflow`. + +References +---------- + +Much of this was inspired by/copied from the committer policies of: + +- `Chromium `_; +- `WebKit `_; +- `Mozilla `_. + diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index f5277993b195..795ef8d89271 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -903,6 +903,8 @@ the new default in GnuPG v2). To set it, add (or modify) the trust-model tofu+pgp +.. _kernel_org_trust_repository: + Using the kernel.org web of trust repository --------------------------------------------