Skip to contentSkip to conversation

doc: develop: Document b4 for custodians

PATCH Applied Tom Rini 4 participants 16 messages Jan 20 – Jan 26

lore
Share & tools
lore

Tom Rini

author
#0 lore raw

cover doc: develop: Document b4 for custodians

Hey all,

Note that to apply this series, it depends on
https://lore.kernel.org/u-boot/[email protected]
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.

Signature · 1 line
Tom
author
#1 lore raw

PATCH 1/5 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.

---
 doc/develop/process.rst | 82 ++++++++++++++++++++---------------------
 1 file changed, 41 insertions(+), 41 deletions(-)
doc/develop/process.rst +41 -41
index 0651a1c23a48..3bda5e6b51dd 100644
@@ -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
 ------------------------
 
Signature · 1 line
2.43.0
Reviewed-by on v1 1/5
#2 lore raw

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

Hi Tom,

Quoted 3 lines · Tom Rini

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

Thanks!
Quentin

author
#3 lore raw

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

In reply to Tom Rini

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

---
 doc/develop/process.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
doc/develop/process.rst +1 -1
index 3bda5e6b51dd..f436a98433a7 100644
@@ -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:
Signature · 1 line
2.43.0
Reviewed-by on v1 2/5
#4 lore raw

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

Hi Tom

Quoted 4 lines · Tom Rini

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

You have just a typo here

Quoted 19 lines
---
 doc/develop/process.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
doc/develop/process.rst +1 -2
index 3bda5e6b51dd..f436a98433a7 100644
@@ -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:
--
Quoted 2 lines

2.43.0

I'm fine with it

author
#5 lore raw

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

Quoted 9 lines · Michael Nazzareno Trimarchi

Hi Tom

Quoted 4 lines · Tom Rini

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?

Quoted 25 lines
Quoted 20 lines
---
 doc/develop/process.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
doc/develop/process.rst +1 -2
index 3bda5e6b51dd..f436a98433a7 100644
@@ -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:
--
Quoted 2 lines

2.43.0

I'm fine with it

Signature · 1 line
Tom
author
#7 lore raw

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

In reply to 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.

---
 doc/develop/codingstyle.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
doc/develop/codingstyle.rst +1 -1
index 013bfebf7e48..7304eea0056a 100644
@@ -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 ``[email protected]`` and integrates with ``scripts/get_maintainer.pl`` for
Signature · 1 line
2.43.0
Reviewed-by on v1 3/5
#8 lore raw

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

Hi Tom,

Quoted 4 lines · 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.

TIL :)

Quoted 1 line

Thanks!
Quentin

author
#9 lore raw

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

In reply to Tom Rini

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

---
 doc/develop/sending_patches.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
doc/develop/sending_patches.rst +1 -1
index ee6e34089b5b..53c7655b2c34 100644
@@ -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.
Signature · 1 line
2.43.0
author
#11 lore raw

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

In reply to 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.

---
 doc/develop/codingstyle.rst     |  2 ++
 doc/develop/process.rst         | 29 +++++++++++++++++++++++++++++
 doc/develop/sending_patches.rst |  2 ++
 3 files changed, 33 insertions(+)
doc/develop/codingstyle.rst +2 -0
index 7304eea0056a..2a69162fa95f 100644
@@ -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
doc/develop/process.rst +29 -0
index f436a98433a7..fd81d9c5ebd4 100644
@@ -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
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
doc/develop/sending_patches.rst +2 -0
index 53c7655b2c34..e29fa175727e 100644
@@ -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
 --------------
 
Signature · 1 line
2.43.0
Reviewed-by on v1 5/5
#12 lore raw

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

Hi Tom,

Quoted 9 lines · 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.

Thanks!

Additional comments below.

Quoted 35 lines
---
  doc/develop/codingstyle.rst     |  2 ++
  doc/develop/process.rst         | 29 +++++++++++++++++++++++++++++
  doc/develop/sending_patches.rst |  2 ++
  3 files changed, 33 insertions(+)
doc/develop/codingstyle.rst +2 -0
index 7304eea0056a..2a69162fa95f 100644
@@ -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
doc/develop/process.rst +8 -0
index f436a98433a7..fd81d9c5ebd4 100644
@@ -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>`.

doc/develop/process.rst feedback to the submitter of a patch about what is going on: · line 252

Quoted 10 lines
doc/develop/process.rst +10 -0
+
+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?

doc/develop/process.rst feedback to the submitter of a patch about what is going on: · line 258

Quoted 6 lines
doc/develop/process.rst +6 -0
+* `"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

author
#13 lore raw

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

Quoted 58 lines · Quentin Schulz

Hi Tom,

Quoted 9 lines · 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.

Thanks!

Additional comments below.

Quoted 39 lines
---
  doc/develop/codingstyle.rst     |  2 ++
  doc/develop/process.rst         | 29 +++++++++++++++++++++++++++++
  doc/develop/sending_patches.rst |  2 ++
  3 files changed, 33 insertions(+)
doc/develop/codingstyle.rst +2 -0
index 7304eea0056a..2a69162fa95f 100644
@@ -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
doc/develop/process.rst +14 -0
index f436a98433a7..fd81d9c5ebd4 100644
@@ -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:
+
Quoted 8 lines

doc/develop/process.rst feedback to the submitter of a patch about what is going on: · line 252

Quoted 4 lines
doc/develop/process.rst +4 -0
+* `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.

Quoted 8 lines

doc/develop/process.rst feedback to the submitter of a patch about what is going on: · line 258

Quoted 6 lines
doc/develop/process.rst +6 -0
+* `"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.

Quoted 1 line

Should we hint at --check also?

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

Quoted 9 lines

"""
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.

Quoted 5 lines

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.

Quoted 8 lines

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.

Signature · 1 line
Tom
#14 lore raw

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

Quoted 94 lines · Tom Rini
Quoted 58 lines · Quentin Schulz

Hi Tom,

Quoted 9 lines · 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.

Thanks!

Additional comments below.

Quoted 39 lines
---
  doc/develop/codingstyle.rst     |  2 ++
  doc/develop/process.rst         | 29 +++++++++++++++++++++++++++++
  doc/develop/sending_patches.rst |  2 ++
  3 files changed, 33 insertions(+)
doc/develop/codingstyle.rst +2 -0
index 7304eea0056a..2a69162fa95f 100644
@@ -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
doc/develop/process.rst +14 -0
index f436a98433a7..fd81d9c5ebd4 100644
@@ -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:
+
Quoted 8 lines

doc/develop/process.rst feedback to the submitter of a patch about what is going on: · line 252

Quoted 4 lines
doc/develop/process.rst +4 -0
+* `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.

Quoted 8 lines

doc/develop/process.rst feedback to the submitter of a patch about what is going on: · line 258

Quoted 6 lines
doc/develop/process.rst +6 -0
+* `"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.

Quoted 1 line

Should we hint at --check also?

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

Quoted 6 lines

"""
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. """

Quoted 5 lines
Quoted 3 lines

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>"

Quoted 9 lines
Quoted 9 lines

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?

Quoted 8 lines
Quoted 5 lines

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
""""

Quoted 8 lines

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.

Signature · 1 line
Tom
Reviewed-by on v1 5/5
#15 lore raw

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

In reply to Tom Rini

Hi Tom,

Thank you for the patch.

Quoted 9 lines · 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.

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