patchtest.README: expand obtaining patches

Expand the section on how to obtain patches with more methods, expanded
explanations, and detailed steps. The suggested set of methods include:
b4, git-pw, "git format-patch", and MUA programs.

(From OE-Core rev: 9779bbfc047f62adedbdb5592389668220f7080e)

Signed-off-by: Trevor Woerner <twoerner@gmail.com>
Signed-off-by: Mathieu Dubois-Briand <mathieu.dubois-briand@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 77 insertions, 7 deletions

diff --git a/scripts/patchtest.README b/scripts/patchtest.README
index bfbe29a379..b321d8e47c 100644
--- a/scripts/patchtest.README
+++ b/scripts/patchtest.README
@@ -5,8 +5,7 @@
 Patchtest is a test framework for community patches based on the standard
 unittest python module. As input, it needs three elements to work properly:
 
-- a patch in mbox format (either created with `git format-patch` or fetched
-from 'patchwork')
+- one or more patches in separate, mbox-formated files
 - a test suite
 - a target repository
 
@@ -94,11 +93,15 @@ cmdline):
 
 ### Obtaining Patches
 
-Patch files can be obtained directly from cloned repositories using `git
-format-patch -N` (where N is the number of patches starting from HEAD to
-generate). git-pw can also be used with filters for users, patch/series IDs,
-and timeboxes if specific patches are desired. For more information, see the
-git-pw [documentation](https://patchwork.readthedocs.io/projects/git-pw/en/latest/).
+Separate, mbox-formatted patch files can be obtained in a number of
+ways:
+
+    - using b4 to obtain patches from a lore server
+    - using git-pw to obtain patches from a patchwork server
+    - using "git format-patch ..." to create patches from a git
+      repository
+    - using an email program, such as mutt or thunderbird, to obtain
+      patches from a mailing list
 
 Alternatively, `scripts/patchtest-get-series` can be used to pull mbox files from
 the Patchwork instance configured previously in .gitconfig. It uses a log file
@@ -109,6 +112,73 @@ the target project, but these parameters can be configured using the `--limit`,
 `--interval`, and `--project` arguments respectively. For more information, run
 `patchtest-get-series -h`.
 
+#### git-pw
+
+git-pw can be used with filters for users, patch/series IDs, and
+timeboxes if specific patches are desired. For more information, see the
+git-pw [documentation](https://patchwork.readthedocs.io/projects/git-pw/en/latest/).
+
+For example, to download a single patch from the Yocto Project's
+Patchwork server (and to demonstrate not having modified ~/.gitconfig):
+
+    (patchtest.venv) $ mkdir gawk
+    (patchtest.venv) $ git-pw --server https://patchwork.yoctoproject.org/api/1.2/ --project oe-core patch download --mbox 70101 gawk/
+
+To download a series, for example, try:
+
+    (patchtest.venv) $ mkdir clang
+    (patchtest.venv) $ git-pw --server https://patchwork.yoctoproject.org/api/1.2 --project oe-core series download --separate 38107 clang/
+
+#### git format-patch
+
+Patch files can be obtained directly from a git repository using `git
+format-patch -N` (where N is the number of patches starting from HEAD to
+generate) or using any other way of specifying a range of commit SHAs to
+git.
+
+This method would be the most likely used when testing patches in local
+mode before emailing them for review.
+
+#### b4
+
+In order to use b4, it needs to be installed. Fortunately it is a Python
+program that is hosted on pypi and can easily be installed into the same
+Python virtual environment that was created to run patchwork:
+
+    (patchtest.venv) $ pip install b4
+    (patchtest.venv) $ b4 --version
+    0.14.2
+
+To fetch the same single patch using b4 that was fetched with git-pw
+earlier, use:
+
+    (patchtest.venv) $ mkdir gawk-2
+    (patchtest.venv) $ b4 am -o gawk-2 https://lore.kernel.org/openembedded-core/20250912200740.2873851-1-Randy.MacLeod@windriver.com
+
+Fetching a patch series with b4 is a little more involved since b4 will
+create one mbox file with all the patches in the series in it. Given an
+mbox file with more than one patch in it, patchtest will only test the
+first one. So there needs to be a separate step to break apart the
+multiple patches into separate files:
+
+    (patchtest.venv) $ mkdir clang-2
+    (patchtest.venv) $ b4 am -o ross https://lore.kernel.org/openembedded-core/20250914133258.2625735-1-ross.burton@arm.com
+    (patchtest.venv) $ cat clang-2/v2_20250914_ross_burton_clang_improve_opt_viewer_packageconfig.mbx | formail -ds sh -c 'cat > ross/msg.$FILENO'
+
+NOTE: the formail utility is part of the procmail package for most Linux
+      distributions.
+
+#### mail user agents (MUA)
+
+Most email applications have a way of saving patch emails. Details for
+each MUA is beyond the scope of this document, but it is possible in
+most cases. The only catch is that each patch has to be saved in mbox
+format in its own individual file. Some client applications prefer to
+save emails in the Maildir format, and some programs will save a set of
+patches into one mbox file. The formail program from the procmail
+package is useful for manipulating and converting between formats and
+storage formats.
+
 ### Host Mode
 
 To run patchtest on the host, do the following: