[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 at konsulko.com>

Reviewed-by: Quentin Schulz <quentin.schulz at 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