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

[Tom Rini <trini@konsulko.com>]

[-- 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 --]