[PATCH 0/5] doc: develop: Document b4 for custodians

[PATCH 0/5] doc: develop: Document b4 for custodians

[Tom Rini]

Hey all,

Note that to apply this series, it depends on
https://lore.kernel.org/u-boot/20260120201327.451872-1-trini@konsulko.com
for context.

In order to more easily document using b4 in the custodian workflow, a
few minor changes needed to be made to the rest of the document in order
to make it easier to add another section and have the content flow well
while reading.

-- 
Tom

[PATCH 1/5] doc: develop: process: Move Custodians section

[Tom Rini]

Move the "Custodians" section to be after the "Review Process, Git Tags"
section, in preparation for more re-organization.

Signed-off-by: Tom Rini <trini@konsulko.com>
---
 doc/develop/process.rst | 82 ++++++++++++++++++++---------------------
 1 file changed, 41 insertions(+), 41 deletions(-)

diff --git a/doc/develop/process.rst b/doc/develop/process.rst
index 0651a1c23a48..3bda5e6b51dd 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
-      <checkpatch>`. 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 <dco>` 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
+      <checkpatch>`. 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 <dco>` 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
 ------------------------
 
-- 
2.43.0

[PATCH 2/5] doc: develop: process: Make "Work flow of a Custodian" a subsection

[Tom Rini]

Make the "Work flow of a Custodian" section be a subsection of the
Custodioans section.

Signed-off-by: Tom Rini <trini@konsulko.com>
---
 doc/develop/process.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/develop/process.rst b/doc/develop/process.rst
index 3bda5e6b51dd..f436a98433a7 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:
-- 
2.43.0

[PATCH 3/5] doc: develop: codingstyle: Update b4 external link

[Tom Rini]

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 <trini@konsulko.com>
---
 doc/develop/codingstyle.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst
index 013bfebf7e48..7304eea0056a 100644
--- a/doc/develop/codingstyle.rst
+++ b/doc/develop/codingstyle.rst
@@ -24,7 +24,7 @@ The following rules apply:
   <https://peps.python.org/pep-0008/>`_. Use `pylint
   <https://github.com/pylint-dev/pylint>`_ for checking the code.
 
-* Use the `b4 <https://git.kernel.org/pub/scm/utils/b4/b4.git/>`_ tool to prepare and
+* Use the `b4 <https://b4.docs.kernel.org/en/latest/>`__ 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
-- 
2.43.0

[PATCH 4/5] doc: develop: sending_patches: Update link to patchwork

[Tom Rini]

Make use of an anonymous reference for the external link here, per rST
best practices.

Signed-off-by: Tom Rini <trini@konsulko.com>
---
 doc/develop/sending_patches.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
index ee6e34089b5b..53c7655b2c34 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 <http://patchwork.ozlabs.org/>`_
+Like some other projects, U-Boot uses `Patchwork <http://patchwork.ozlabs.org/>`__
 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.
-- 
2.43.0

[PATCH 5/5] doc: develop: process: Document using b4 and patchwork for custodians

[Tom Rini]

- 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 <trini@konsulko.com>
---
 doc/develop/codingstyle.rst     |  2 ++
 doc/develop/process.rst         | 29 +++++++++++++++++++++++++++++
 doc/develop/sending_patches.rst |  2 ++
 3 files changed, 33 insertions(+)

diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst
index 7304eea0056a..2a69162fa95f 100644
--- a/doc/develop/codingstyle.rst
+++ b/doc/develop/codingstyle.rst
@@ -24,6 +24,8 @@ The following rules apply:
   <https://peps.python.org/pep-0008/>`_. Use `pylint
   <https://github.com/pylint-dev/pylint>`_ for checking the code.
 
+.. _b4_contrib:
+
 * Use the `b4 <https://b4.docs.kernel.org/en/latest/>`__ 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 f436a98433a7..fd81d9c5ebd4 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 <http://patchwork.ozlabs.org/>`__
+and more discussion on how it is used from both a contributor as well as
+custodian point of view can be found :ref:`here <patchwork>`.
+
+Another useful tool is `b4 <https://b4.docs.kernel.org/en/latest/>`__
+and is documented from a contributor point of view :ref:`here
+<b4_contrib>`. It also has a number of useful features from a custodian
+point of view:
+
+* `Integration with patchwork
+  <https://b4.docs.kernel.org/en/latest/config.html#patchwork-integration-settings>`__
+  which allows for automatic state tracking.
+
+* `"am" and "shazam"
+  <https://b4.docs.kernel.org/en/latest/maintainer/am-shazam.html>`__
+  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" <https://b4.docs.kernel.org/en/latest/maintainer/ty.html>`__ 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 53c7655b2c34..e29fa175727e 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
 --------------
 
-- 
2.43.0

Re: [PATCH 2/5] doc: develop: process: Make "Work flow of a Custodian" a subsection

[Michael Nazzareno Trimarchi]

Hi Tom

On Tue, Jan 20, 2026 at 11:35 PM Tom Rini <trini@konsulko.com> wrote:
>
> Make the "Work flow of a Custodian" section be a subsection of the
> Custodioans section.
>

You have just a typo here

> Signed-off-by: Tom Rini <trini@konsulko.com>
> ---
>  doc/develop/process.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/doc/develop/process.rst b/doc/develop/process.rst
> index 3bda5e6b51dd..f436a98433a7 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:
> --
> 2.43.0
>

I'm fine with it
Reviewed-by: Michael Trimarchi <michael@amarulasolutions.com>

Re: [PATCH 1/5] doc: develop: process: Move Custodians section

[Quentin Schulz]

Hi Tom,

On 1/20/26 11:31 PM, Tom Rini wrote:
> Move the "Custodians" section to be after the "Review Process, Git Tags"
> section, in preparation for more re-organization.
> 

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH 2/5] doc: develop: process: Make "Work flow of a Custodian" a subsection

[Quentin Schulz]

Hi Tom,

On 1/20/26 11:31 PM, Tom Rini wrote:
> Make the "Work flow of a Custodian" section be a subsection of the
> Custodioans section.
> 
> Signed-off-by: Tom Rini <trini@konsulko.com>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH 3/5] doc: develop: codingstyle: Update b4 external link

[Quentin Schulz]

Hi Tom,

On 1/20/26 11:31 PM, Tom Rini wrote:
> 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.
> 

TIL :)

> Signed-off-by: Tom Rini <trini@konsulko.com>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH 4/5] doc: develop: sending_patches: Update link to patchwork

[Quentin Schulz]

Hi Tom,

On 1/20/26 11:31 PM, Tom Rini wrote:
> Make use of an anonymous reference for the external link here, per rST
> best practices.
> 
> Signed-off-by: Tom Rini <trini@konsulko.com>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH 5/5] doc: develop: process: Document using b4 and patchwork for custodians

[Quentin Schulz]

Hi Tom,

On 1/20/26 11:31 PM, Tom Rini wrote:
> - 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 <trini@konsulko.com>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!

Additional comments below.

> ---
>   doc/develop/codingstyle.rst     |  2 ++
>   doc/develop/process.rst         | 29 +++++++++++++++++++++++++++++
>   doc/develop/sending_patches.rst |  2 ++
>   3 files changed, 33 insertions(+)
> 
> diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst
> index 7304eea0056a..2a69162fa95f 100644
> --- a/doc/develop/codingstyle.rst
> +++ b/doc/develop/codingstyle.rst
> @@ -24,6 +24,8 @@ The following rules apply:
>     <https://peps.python.org/pep-0008/>`_. Use `pylint
>     <https://github.com/pylint-dev/pylint>`_ for checking the code.
>   
> +.. _b4_contrib:
> +
>   * Use the `b4 <https://b4.docs.kernel.org/en/latest/>`__ 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 f436a98433a7..fd81d9c5ebd4 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 <http://patchwork.ozlabs.org/>`__
> +and more discussion on how it is used from both a contributor as well as
> +custodian point of view can be found :ref:`here <patchwork>`.
> +
> +Another useful tool is `b4 <https://b4.docs.kernel.org/en/latest/>`__
> +and is documented from a contributor point of view :ref:`here
> +<b4_contrib>`. It also has a number of useful features from a custodian
> +point of view:
> +
> +* `Integration with patchwork
> +  <https://b4.docs.kernel.org/en/latest/config.html#patchwork-integration-settings>`__
> +  which allows for automatic state tracking.
> +

Can we have this integration added to .b4-config so there's less to do 
for custodians? Ideally also with steps to finish the setup so that 
patchwork is fully working for them?

> +* `"am" and "shazam"
> +  <https://b4.docs.kernel.org/en/latest/maintainer/am-shazam.html>`__
> +  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.
> +

Is there any reason for using b4 am? (I only use b4 shazam myself).

Should we hint at --check also?

"""
Tells b4 to run a series of local checks on each patch of the series and 
display any problems. When b4 finds a valid patchwork project definition 
in the configuration settings, it also looks up the CI status of each patch.
"""

We can configure which command to run by setting
b4.am-perpatch-check-cmd in .b4-config 
(https://b4.docs.kernel.org/en/latest/config.html#am-and-shazam-settings)

We should absolutely make clear that both am and shazam fetch the latest 
version of the series, regardless of the link being passed to it (except 
if -v or --use-version is used). At least that's my experience with 
shazam and the docs states it should apply to both am and shazam.

I'm assuming the cover-letter being integrated as a merge commit would 
be behind the --merge option?

We may want to hint at -P or --cherry-pick as ways to only pick specific 
commits out of the patch series.

I'm not sure how much we want to hint at here versus letting custodians 
figure out their workflow on their own.

Cheers,
Quentin

Re: [PATCH 2/5] doc: develop: process: Make "Work flow of a Custodian" a subsection

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 1133 bytes --]

On Wed, Jan 21, 2026 at 10:44:42AM +0100, Michael Nazzareno Trimarchi wrote:
> Hi Tom
> 
> On Tue, Jan 20, 2026 at 11:35 PM Tom Rini <trini@konsulko.com> wrote:
> >
> > Make the "Work flow of a Custodian" section be a subsection of the
> > Custodioans section.
> >
> 
> You have just a typo here

Heinrich, can you fix this when applying please?

> 
> > Signed-off-by: Tom Rini <trini@konsulko.com>
> > ---
> >  doc/develop/process.rst | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/doc/develop/process.rst b/doc/develop/process.rst
> > index 3bda5e6b51dd..f436a98433a7 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:
> > --
> > 2.43.0
> >
> 
> I'm fine with it
> Reviewed-by: Michael Trimarchi <michael@amarulasolutions.com>

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 5/5] doc: develop: process: Document using b4 and patchwork for custodians

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 5381 bytes --]

On Wed, Jan 21, 2026 at 12:16:23PM +0100, Quentin Schulz wrote:
> Hi Tom,
> 
> On 1/20/26 11:31 PM, Tom Rini wrote:
> > - 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 <trini@konsulko.com>
> 
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
> 
> Thanks!
> 
> Additional comments below.
> 
> > ---
> >   doc/develop/codingstyle.rst     |  2 ++
> >   doc/develop/process.rst         | 29 +++++++++++++++++++++++++++++
> >   doc/develop/sending_patches.rst |  2 ++
> >   3 files changed, 33 insertions(+)
> > 
> > diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst
> > index 7304eea0056a..2a69162fa95f 100644
> > --- a/doc/develop/codingstyle.rst
> > +++ b/doc/develop/codingstyle.rst
> > @@ -24,6 +24,8 @@ The following rules apply:
> >     <https://peps.python.org/pep-0008/>`_. Use `pylint
> >     <https://github.com/pylint-dev/pylint>`_ for checking the code.
> > +.. _b4_contrib:
> > +
> >   * Use the `b4 <https://b4.docs.kernel.org/en/latest/>`__ 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 f436a98433a7..fd81d9c5ebd4 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 <http://patchwork.ozlabs.org/>`__
> > +and more discussion on how it is used from both a contributor as well as
> > +custodian point of view can be found :ref:`here <patchwork>`.
> > +
> > +Another useful tool is `b4 <https://b4.docs.kernel.org/en/latest/>`__
> > +and is documented from a contributor point of view :ref:`here
> > +<b4_contrib>`. It also has a number of useful features from a custodian
> > +point of view:
> > +
> > +* `Integration with patchwork
> > +  <https://b4.docs.kernel.org/en/latest/config.html#patchwork-integration-settings>`__
> > +  which allows for automatic state tracking.
> > +
> 
> Can we have this integration added to .b4-config so there's less to do for
> custodians? Ideally also with steps to finish the setup so that patchwork is
> fully working for them?

Yes, I can follow-up and add defaults for everything but API key.

> > +* `"am" and "shazam"
> > +  <https://b4.docs.kernel.org/en/latest/maintainer/am-shazam.html>`__
> > +  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.
> > +
> 
> Is there any reason for using b4 am? (I only use b4 shazam myself).

I use it from time to time when "shazam"'ing something results in a
merge I have to fixup and so "ty -l" doesn't show the patch. An "am"
will put it back in the ty list.

> Should we hint at --check also?

Not sure. I don't use it because I have something else that runs and
logs checkpatch later.

> """
> Tells b4 to run a series of local checks on each patch of the series and
> display any problems. When b4 finds a valid patchwork project definition in
> the configuration settings, it also looks up the CI status of each patch.
> """
> 
> We can configure which command to run by setting
> b4.am-perpatch-check-cmd in .b4-config
> (https://b4.docs.kernel.org/en/latest/config.html#am-and-shazam-settings)

Right, but we have checkpatch configured already in-tree.

> We should absolutely make clear that both am and shazam fetch the latest
> version of the series, regardless of the link being passed to it (except if
> -v or --use-version is used). At least that's my experience with shazam and
> the docs states it should apply to both am and shazam.
> 
> I'm assuming the cover-letter being integrated as a merge commit would be
> behind the --merge option?
> 
> We may want to hint at -P or --cherry-pick as ways to only pick specific
> commits out of the patch series.
> 
> I'm not sure how much we want to hint at here versus letting custodians
> figure out their workflow on their own.

The last point is the one I agree with most. I know at least Casey and
Mattijs are using b4 as well, so I'd like their feedback on document
here vs expect people to read upstream docs. As for example, I also
didn't mention "mbox" but I use that for both re-reviews as well as "oh,
this patch broke X, I need to reply now". But I would also expect
someone using b4 to see/know about that, or have their own workflow
already.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 5/5] doc: develop: process: Document using b4 and patchwork for custodians

[Mattijs Korpershoek]

On Wed, Jan 21, 2026 at 09:06, Tom Rini <trini@konsulko.com> wrote:

> On Wed, Jan 21, 2026 at 12:16:23PM +0100, Quentin Schulz wrote:
>> Hi Tom,
>> 
>> On 1/20/26 11:31 PM, Tom Rini wrote:
>> > - 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 <trini@konsulko.com>
>> 
>> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
>> 
>> Thanks!
>> 
>> Additional comments below.
>> 
>> > ---
>> >   doc/develop/codingstyle.rst     |  2 ++
>> >   doc/develop/process.rst         | 29 +++++++++++++++++++++++++++++
>> >   doc/develop/sending_patches.rst |  2 ++
>> >   3 files changed, 33 insertions(+)
>> > 
>> > diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst
>> > index 7304eea0056a..2a69162fa95f 100644
>> > --- a/doc/develop/codingstyle.rst
>> > +++ b/doc/develop/codingstyle.rst
>> > @@ -24,6 +24,8 @@ The following rules apply:
>> >     <https://peps.python.org/pep-0008/>`_. Use `pylint
>> >     <https://github.com/pylint-dev/pylint>`_ for checking the code.
>> > +.. _b4_contrib:
>> > +
>> >   * Use the `b4 <https://b4.docs.kernel.org/en/latest/>`__ 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 f436a98433a7..fd81d9c5ebd4 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 <http://patchwork.ozlabs.org/>`__
>> > +and more discussion on how it is used from both a contributor as well as
>> > +custodian point of view can be found :ref:`here <patchwork>`.
>> > +
>> > +Another useful tool is `b4 <https://b4.docs.kernel.org/en/latest/>`__
>> > +and is documented from a contributor point of view :ref:`here
>> > +<b4_contrib>`. It also has a number of useful features from a custodian
>> > +point of view:
>> > +
>> > +* `Integration with patchwork
>> > +  <https://b4.docs.kernel.org/en/latest/config.html#patchwork-integration-settings>`__
>> > +  which allows for automatic state tracking.
>> > +
>> 
>> Can we have this integration added to .b4-config so there's less to do for
>> custodians? Ideally also with steps to finish the setup so that patchwork is
>> fully working for them?
>
> Yes, I can follow-up and add defaults for everything but API key.
>
>> > +* `"am" and "shazam"
>> > +  <https://b4.docs.kernel.org/en/latest/maintainer/am-shazam.html>`__
>> > +  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.
>> > +
>> 
>> Is there any reason for using b4 am? (I only use b4 shazam myself).
>
> I use it from time to time when "shazam"'ing something results in a
> merge I have to fixup and so "ty -l" doesn't show the patch. An "am"
> will put it back in the ty list.
>
>> Should we hint at --check also?
>
> Not sure. I don't use it because I have something else that runs and
> logs checkpatch later.
>
>> """
>> Tells b4 to run a series of local checks on each patch of the series and
>> display any problems. When b4 finds a valid patchwork project definition in
>> the configuration settings, it also looks up the CI status of each patch.
>> """
>> 
>> We can configure which command to run by setting
>> b4.am-perpatch-check-cmd in .b4-config
>> (https://b4.docs.kernel.org/en/latest/config.html#am-and-shazam-settings)
>
> Right, but we have checkpatch configured already in-tree.

Personally, I always use --check when applying patches for review.

I usually run "b4 shazam -s -l --check <msgid>"

>
>> We should absolutely make clear that both am and shazam fetch the latest
>> version of the series, regardless of the link being passed to it (except if
>> -v or --use-version is used). At least that's my experience with shazam and
>> the docs states it should apply to both am and shazam.
>> 
>> I'm assuming the cover-letter being integrated as a merge commit would be
>> behind the --merge option?
>> 
>> We may want to hint at -P or --cherry-pick as ways to only pick specific
>> commits out of the patch series.
>> 
>> I'm not sure how much we want to hint at here versus letting custodians
>> figure out their workflow on their own.
>
> The last point is the one I agree with most. I know at least Casey and
> Mattijs are using b4 as well, so I'd like their feedback on document

I think mentioning like done in the patch is good enough. We don't want
to repeat the upstream b4 docs too much.

For b4 ty, there is some configuration required though. I have:

[b4]
    thanks-commit-url-mask = https://source.denx.de/u-boot/custodians/u-boot-dfu/-/commit/%.40s
    thanks-am-template = /home/mkorpershoek/.dotfiles-private/u-boot-dfu/thanks-am-template
    thanks-treename = https://source.denx.de/u-boot/custodians/u-boot-dfu

Where thanks-am-template is:
""""
Hi,

On ${sentdate}, ${fromname} wrote:
${quote}

Thanks, Applied to ${treename} (${branch})

${summary}

--
Mattijs
""""

> here vs expect people to read upstream docs. As for example, I also
> didn't mention "mbox" but I use that for both re-reviews as well as "oh,
> this patch broke X, I need to reply now". But I would also expect
> someone using b4 to see/know about that, or have their own workflow
> already.
>
> -- 
> Tom

Re: [PATCH 5/5] doc: develop: process: Document using b4 and patchwork for custodians

[Mattijs Korpershoek]

Hi Tom,

Thank you for the patch.

On Tue, Jan 20, 2026 at 16:31, Tom Rini <trini@konsulko.com> wrote:

> - 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 <trini@konsulko.com>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@kernel.org>

> ---
>  doc/develop/codingstyle.rst     |  2 ++
>  doc/develop/process.rst         | 29 +++++++++++++++++++++++++++++
>  doc/develop/sending_patches.rst |  2 ++
>  3 files changed, 33 insertions(+)
>