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 <[email protected]>
Reviewed-by: Quentin Schulz <[email protected]>
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
