From 5f6776883c66172cf784bc0ced2fbe3c1018ba9b Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 20 Jan 2026 14:11:43 -0600 Subject: doc: develop: process: Move the existing block about patch application We have a long block about the expectations and feedback about a patch applying, or not, as part of the Custodian workflow. Move this to the Custodians section from the Workflow of a custodian section. Signed-off-by: Tom Rini Reviewed-by: Quentin Schulz --- doc/develop/process.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/process.rst b/doc/develop/process.rst index 4bfbf0eb9c6..81e1aa7e34d 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -143,6 +143,17 @@ reworked/resubmitted, or if it was rejected. However, if a submitter feels it has been too long since posting their patch and not received any feedback, it is OK to follow-up and ask. +Another form of feedback is about applying the patch itself to the +source tree. The custodian is expected to put in a "best effort" if a +patch does not apply cleanly, but can be made to apply still. It is up +to the custodian to decide how recent of a commit the patch must be +against. It is acceptable to request patches against the last officially +released version of U-Boot or newer. Of course a custodian can also +accept patches against older code. It can be difficult to find the +correct balance between putting too much work on the custodian or too +much work on an individual submitting a patch when something does not +apply cleanly. + Review Process, Git Tags ------------------------ @@ -236,15 +247,8 @@ like this: #. U-Boot Philosophy, as documented in :doc:`designprinciples`. - #. Applies cleanly to the source tree. The custodian is expected to put in - a "best effort" if a patch does not apply cleanly, but can be made to apply - still. It is up to the custodian to decide how recent of a commit the - patch must be against. It is acceptable to request patches against the - last officially released version of U-Boot or newer. Of course a - custodian can also accept patches against older code. It can be - difficult to find the correct balance between putting too much work on - the custodian or too much work on an individual submitting a patch when - something does not apply cleanly. + #. Can be applied easily to the source tree, as documented in the + :ref:`custodians` section. #. Passes :doc:`ci_testing` as this checks for new warnings and other issues. -- cgit v1.2.3 From 78e100db5b2354329664fd06fdac870f1ef59c3f Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 20 Jan 2026 14:11:44 -0600 Subject: doc: develop: process: Rework the custodian feedback section Now that we have two items here, rework this slightly to be using bullet points, and so easier to expand on. Signed-off-by: Tom Rini Reviewed-by: Quentin Schulz --- doc/develop/process.rst | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/process.rst b/doc/develop/process.rst index 81e1aa7e34d..4159a945707 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -132,27 +132,28 @@ It is their responsibility to pick up patches from the mailing list that fall into their responsibility, and to process these. A very important responsibility of each custodian is to provide -feedback to the submitter of a patch about what is going on: if the -patch was accepted, or if it was rejected (which exact list of -reasons), if it needs to be reworked (with respective review -comments). Even a "I have no time now, will look into it later" -message is better than nothing. Also, if there are remarks to a -patch, these should leave no doubt if they were just comments and the -patch will be accepted anyway, or if the patch should be -reworked/resubmitted, or if it was rejected. However, if a submitter -feels it has been too long since posting their patch and not received -any feedback, it is OK to follow-up and ask. - -Another form of feedback is about applying the patch itself to the -source tree. The custodian is expected to put in a "best effort" if a -patch does not apply cleanly, but can be made to apply still. It is up -to the custodian to decide how recent of a commit the patch must be -against. It is acceptable to request patches against the last officially -released version of U-Boot or newer. Of course a custodian can also -accept patches against older code. It can be difficult to find the -correct balance between putting too much work on the custodian or too -much work on an individual submitting a patch when something does not -apply cleanly. +feedback to the submitter of a patch about what is going on: + + * If the patch was accepted, or if it was rejected (with exact list + of reasons), if it needs to be reworked (with respective review + comments). Even a "I have no time now, will look into it later" + message is better than nothing. Also, if there are remarks to a + patch, these should leave no doubt if they were just comments and + the patch will be accepted anyway, or if the patch should be + reworked/resubmitted, or if it was rejected. However, if a submitter + feels it has been too long since posting their patch and not + received any feedback, it is OK to follow-up and ask. + + * If the patch itself can still be applied to the tree. The custodian + is expected to put in a "best effort" if a patch does not apply + cleanly, but can be made to apply still. It is up to the custodian + to decide how recent of a commit the patch must be against. It is + acceptable to request patches against the last officially released + version of U-Boot or newer. Of course a custodian can also accept + patches against older code. It can be difficult to find the correct + balance between putting too much work on the custodian or too much + work on an individual submitting a patch when something does not + apply cleanly. Review Process, Git Tags ------------------------ -- cgit v1.2.3 From 7db33677c29ee494739557b5d3e8c1f48b3936e7 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 20 Jan 2026 14:11:45 -0600 Subject: doc: develop: process: Explain when/how Custodians may edit patches As seen with commit d503633a3676 ("Revert "doc: board: starfive: update jh7110 common description""), it has not always been clear what is and isn't allowed by custodians, and what the expectations are. To prevent further unintentional conflicts, document the limited cases where custodians are allowed to modify patches directly, and how to do that. Signed-off-by: Tom Rini Reviewed-by: Quentin Schulz --- doc/develop/process.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'doc/develop') diff --git a/doc/develop/process.rst b/doc/develop/process.rst index 4159a945707..0651a1c23a4 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -144,6 +144,12 @@ feedback to the submitter of a patch about what is going on: feels it has been too long since posting their patch and not received any feedback, it is OK to follow-up and ask. + * A custodian may make changes suggested by :doc:`checkpatch.pl + `. They must also in turn amend the commit message noting + their change, for example ``[trini: Fix typos]``, and add their own + :ref:`Signed-off-by ` tag. All other changes must be handled by + another iteration of the patch, or follow-up patch. + * If the patch itself can still be applied to the tree. The custodian is expected to put in a "best effort" if a patch does not apply cleanly, but can be made to apply still. It is up to the custodian -- cgit v1.2.3 From 8449e5c2342af2269f8ae14e659307a51fafeff8 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 20 Jan 2026 16:31:42 -0600 Subject: doc: develop: process: Move Custodians section Move the "Custodians" section to be after the "Review Process, Git Tags" section, in preparation for more re-organization. Signed-off-by: Tom Rini Reviewed-by: Quentin Schulz --- doc/develop/process.rst | 82 ++++++++++++++++++++++++------------------------- 1 file changed, 41 insertions(+), 41 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/process.rst b/doc/develop/process.rst index 0651a1c23a4..3bda5e6b51d 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -120,47 +120,6 @@ these can be "cherry-picked" and are subject to the normal merge rules. For example, a bug fix can come in later in the window but a full re-sync only happens within the merge window itself. -.. _custodians: - -Custodians ----------- - -The Custodians take responsibility for some area of the U-Boot code. The -in-tree ``MAINTAINERS`` files list who is responsible for which areas. - -It is their responsibility to pick up patches from the mailing list -that fall into their responsibility, and to process these. - -A very important responsibility of each custodian is to provide -feedback to the submitter of a patch about what is going on: - - * If the patch was accepted, or if it was rejected (with exact list - of reasons), if it needs to be reworked (with respective review - comments). Even a "I have no time now, will look into it later" - message is better than nothing. Also, if there are remarks to a - patch, these should leave no doubt if they were just comments and - the patch will be accepted anyway, or if the patch should be - reworked/resubmitted, or if it was rejected. However, if a submitter - feels it has been too long since posting their patch and not - received any feedback, it is OK to follow-up and ask. - - * A custodian may make changes suggested by :doc:`checkpatch.pl - `. They must also in turn amend the commit message noting - their change, for example ``[trini: Fix typos]``, and add their own - :ref:`Signed-off-by ` tag. All other changes must be handled by - another iteration of the patch, or follow-up patch. - - * If the patch itself can still be applied to the tree. The custodian - is expected to put in a "best effort" if a patch does not apply - cleanly, but can be made to apply still. It is up to the custodian - to decide how recent of a commit the patch must be against. It is - acceptable to request patches against the last officially released - version of U-Boot or newer. Of course a custodian can also accept - patches against older code. It can be difficult to find the correct - balance between putting too much work on the custodian or too much - work on an individual submitting a patch when something does not - apply cleanly. - Review Process, Git Tags ------------------------ @@ -232,6 +191,47 @@ document. For example, when your change affects a specific board or driver, then makes a lot of sense to put the respective maintainer of this code on Cc: +.. _custodians: + +Custodians +---------- + +The Custodians take responsibility for some area of the U-Boot code. The +in-tree ``MAINTAINERS`` files list who is responsible for which areas. + +It is their responsibility to pick up patches from the mailing list +that fall into their responsibility, and to process these. + +A very important responsibility of each custodian is to provide +feedback to the submitter of a patch about what is going on: + + * If the patch was accepted, or if it was rejected (with exact list + of reasons), if it needs to be reworked (with respective review + comments). Even a "I have no time now, will look into it later" + message is better than nothing. Also, if there are remarks to a + patch, these should leave no doubt if they were just comments and + the patch will be accepted anyway, or if the patch should be + reworked/resubmitted, or if it was rejected. However, if a submitter + feels it has been too long since posting their patch and not + received any feedback, it is OK to follow-up and ask. + + * A custodian may make changes suggested by :doc:`checkpatch.pl + `. They must also in turn amend the commit message noting + their change, for example ``[trini: Fix typos]``, and add their own + :ref:`Signed-off-by ` tag. All other changes must be handled by + another iteration of the patch, or follow-up patch. + + * If the patch itself can still be applied to the tree. The custodian + is expected to put in a "best effort" if a patch does not apply + cleanly, but can be made to apply still. It is up to the custodian + to decide how recent of a commit the patch must be against. It is + acceptable to request patches against the last officially released + version of U-Boot or newer. Of course a custodian can also accept + patches against older code. It can be difficult to find the correct + balance between putting too much work on the custodian or too much + work on an individual submitting a patch when something does not + apply cleanly. + Work flow of a Custodian ------------------------ -- cgit v1.2.3 From 05609eebdbf5b29fa179b5701bc7d44832ab9b34 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 20 Jan 2026 16:31:43 -0600 Subject: doc: develop: process: Make "Work flow of a Custodian" a subsection Make the "Work flow of a Custodian" section be a subsection of the Custodians section. Signed-off-by: Tom Rini Reviewed-by: Quentin Schulz Reviewed-by: Michael Trimarchi --- doc/develop/process.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/develop') diff --git a/doc/develop/process.rst b/doc/develop/process.rst index 3bda5e6b51d..f436a98433a 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -233,7 +233,7 @@ feedback to the submitter of a patch about what is going on: apply cleanly. Work flow of a Custodian ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ The normal flow of work in the U-Boot development process will look like this: -- cgit v1.2.3 From 385005732cffe635789f9a5aa24f1ac8b57686aa Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 20 Jan 2026 16:31:44 -0600 Subject: doc: develop: codingstyle: Update b4 external link Rather than pointing at the source code for b4, point the the official documentation. Also, use an anonymous reference for the link, per rST best practices. Signed-off-by: Tom Rini Reviewed-by: Quentin Schulz --- doc/develop/codingstyle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/develop') diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst index 013bfebf7e4..7304eea0056 100644 --- a/doc/develop/codingstyle.rst +++ b/doc/develop/codingstyle.rst @@ -24,7 +24,7 @@ The following rules apply: `_. Use `pylint `_ for checking the code. -* Use the `b4 `_ tool to prepare and +* Use the `b4 `__ tool to prepare and send your patches. b4 has become the preferred tool to sending patches for many Linux kernel contributors, and U-Boot ships with a ready-to-use ``.b4-config`` that targets ``u-boot@lists.denx.de`` and integrates with ``scripts/get_maintainer.pl`` for -- cgit v1.2.3 From e41a8f3f35ed870921c913a87eb9d5919112a8f3 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 20 Jan 2026 16:31:45 -0600 Subject: doc: develop: sending_patches: Update link to patchwork Make use of an anonymous reference for the external link here, per rST best practices. Signed-off-by: Tom Rini Reviewed-by: Quentin Schulz --- doc/develop/sending_patches.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/develop') diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst index ee6e34089b5..53c7655b2c3 100644 --- a/doc/develop/sending_patches.rst +++ b/doc/develop/sending_patches.rst @@ -325,7 +325,7 @@ Notes Patch Tracking -------------- -Like some other projects, U-Boot uses `Patchwork `_ +Like some other projects, U-Boot uses `Patchwork `__ to track the state of patches. This is one of the reasons why it is mandatory to submit all patches to the U-Boot mailing list - only then they will be picked up by patchwork. -- cgit v1.2.3 From 302c054d64a19c5bb579c3a74cc809f7338cf9de Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 20 Jan 2026 16:31:46 -0600 Subject: doc: develop: process: Document using b4 and patchwork for custodians - We already have good custodian documentation for patchwork, add a reference and then link to it here. - Add a reference to the existing b4 documentation, and reference it here. - Note and link to patchwork integration, am/shazam and ty features of b4 as these are the most likely useful portions. Be specific about keeping the default ${summary} as that includes important information. Signed-off-by: Tom Rini Reviewed-by: Mattijs Korpershoek Reviewed-by: Quentin Schulz --- doc/develop/codingstyle.rst | 2 ++ doc/develop/process.rst | 29 +++++++++++++++++++++++++++++ doc/develop/sending_patches.rst | 2 ++ 3 files changed, 33 insertions(+) (limited to 'doc/develop') diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst index 7304eea0056..2a69162fa95 100644 --- a/doc/develop/codingstyle.rst +++ b/doc/develop/codingstyle.rst @@ -24,6 +24,8 @@ The following rules apply: `_. Use `pylint `_ for checking the code. +.. _b4_contrib: + * Use the `b4 `__ tool to prepare and send your patches. b4 has become the preferred tool to sending patches for many Linux kernel contributors, and U-Boot ships with a ready-to-use ``.b4-config`` that diff --git a/doc/develop/process.rst b/doc/develop/process.rst index f436a98433a..fd81d9c5ebd 100644 --- a/doc/develop/process.rst +++ b/doc/develop/process.rst @@ -232,6 +232,35 @@ feedback to the submitter of a patch about what is going on: work on an individual submitting a patch when something does not apply cleanly. +Tooling +^^^^^^^ + +There are a number of tools available to help custodians and +contributors alike with their contributions. As a project we make use of +the Patchwork project hosted at `OzLabs `__ +and more discussion on how it is used from both a contributor as well as +custodian point of view can be found :ref:`here `. + +Another useful tool is `b4 `__ +and is documented from a contributor point of view :ref:`here +`. It also has a number of useful features from a custodian +point of view: + +* `Integration with patchwork + `__ + which allows for automatic state tracking. + +* `"am" and "shazam" + `__ + for applying a patch or series of patches. Of note is that with + ``shazam`` review tags can be applied automatically and cover letters + can be integrated as part of merging a series. + +* `"ty" `__ for + automatically sending emails once patches have been applied. It is + strongly encouraged to keep the default ``${summary}`` in the template + as that shows what the git commit hash is for a particular patch. + Work flow of a Custodian ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst index 53c7655b2c3..e29fa175727 100644 --- a/doc/develop/sending_patches.rst +++ b/doc/develop/sending_patches.rst @@ -322,6 +322,8 @@ Notes the memory footprint of the code. Remember: Small is beautiful! When adding new features follow the guidelines laid out in :doc:`system_configuration`. +.. _patchwork: + Patch Tracking -------------- -- cgit v1.2.3