docs: complete most of the maintainer docs

Some of the articles are still barely more than stubs, but it's better
than nothing at all.

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

10 files changed, 316 insertions, 16 deletions

diff --git a/docs/config.rst b/docs/config.rst
index 3f58707..7e299a1 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -198,6 +198,8 @@ These settings control patch attestation.
 
   Default: ``None``
 
+.. _ty_settings:
+
 Thank-you (ty) settings
 ~~~~~~~~~~~~~~~~~~~~~~~
 These settings control the behaviour of ``b4 ty`` command.
@@ -222,6 +224,7 @@ These settings control the behaviour of ``b4 ty`` command.
 
   Default: ``None``
 
+.. _patchwork_settings:
 
 Patchwork integration settings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/index.rst b/docs/index.rst
index c24b793..6f29d41 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,10 +24,11 @@ For maintainers
 
    maintainer/overview
    maintainer/mbox
-   maintainer/patches
-   maintainer/prs
-   maintainer/thanks
-   maintainer/keys
+   maintainer/am-shazam
+   maintainer/diff
+   maintainer/pr
+   maintainer/ty
+   maintainer/kr
 
 For developers
 --------------
diff --git a/docs/maintainer/patches.rst b/docs/maintainer/am-shazam.rst
index 2ebe4b1..2ebe4b1 100644
--- a/docs/maintainer/patches.rst
+++ b/docs/maintainer/am-shazam.rst
diff --git a/docs/maintainer/diff.rst b/docs/maintainer/diff.rst
new file mode 100644
index 0000000..260b56d
--- /dev/null
+++ b/docs/maintainer/diff.rst
@@ -0,0 +1,56 @@
+b4 diff: comparing patch series
+===============================
+The ``diff`` subcommand allows comparing two different revisions of the
+same patch series using ``git range-diff``. Note, that in order to
+perform the ``range-diff`` comparison, both revisions need to cleanly
+apply to the current tree, which may not always be easy to achieve.
+
+The easiest way to use it is to prepare two mbox files of the series you
+would like to compare first::
+
+    $ b4 am --no-cover -n ver1 msgid-of-ver-1
+    $ b4 am --no-cover -n ver2 msgid-of-ver-2
+    $ b4 diff -m ver1.mbx ver2.mbx
+
+Optional flags
+--------------
+``-g GITDIR, --gitdir GITDIR``
+  Specify a path to the git tree to use, if not running the command
+  inside a git tree.
+
+``-p USEPROJECT, --use-project USEPROJECT``
+  **(DEPRECATED)**: This is a legacy option that made sense before
+  public-inbox supported collating and retrieving threads from across
+  multiple lists. This flag will probably go away in the future.
+
+``-C, --no-cache``
+  By default, b4 will cache the retrieved threads for about 10 minutes.
+  This lets you force b4 to ignore cache and retrieve the latest
+  results.
+
+``-v WANTVERS [WANTVERS ...], --compare-versions WANTVERS [WANTVERS ...]``
+  To properly work, this requires that both versions being compared are
+  part of the same thread, which is rarely the case. In the future, this
+  may work better as more series use the ``change-id`` trailer to keep
+  track of revisions across discussion threads.
+
+  Example: ``b4 diff <msgid> -v 2 3``
+
+``-n, --no-diff``
+  By default, ``b4 diff`` will output the results of the range-diff
+  command. However, this can be a wall of text, so instead you may want
+  to just view the command that you can run yourself with the ranges
+  prepared by b4. This additionally allows you to tweak the
+  ``git-range`` flags to use.
+
+``-m AMBOX AMBOX, --compare-am-mboxes AMBOX AMBOX``
+  Compares two mbox files prepared by ``git am`` instead of querying
+  the public-inbox server directly.
+
+``-o OUTDIFF, --output-diff OUTDIFF``
+  **(DEPRECATED)** Sends ``range-diff`` output into a file. You should use
+  ``-n`` instead and redirect output from there.
+
+``-c, --color``
+  **(DEPRECATED)** Show colour output even when outputting into a file.
+  You should use ``-n`` instead and modify flags to ``range-diff``.
diff --git a/docs/maintainer/keys.rst b/docs/maintainer/keys.rst
deleted file mode 100644
index 37a2869..0000000
--- a/docs/maintainer/keys.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-Working with contributor keys
-=============================
-
-Stub.
diff --git a/docs/maintainer/kr.rst b/docs/maintainer/kr.rst
new file mode 100644
index 0000000..9f5816e
--- /dev/null
+++ b/docs/maintainer/kr.rst
@@ -0,0 +1,45 @@
+b4 kr: working with contributor keys
+====================================
+This subcommand allows maintaining a local keyring of contributor keys.
+
+.. note::
+
+  This functionality is under active development and the set of
+  available features will be expanded in the near future.
+
+Patatt keyrings
+---------------
+B4 uses the patatt patch attestation library for its purposes, and it
+uses patatt-style keyrings. You can read more information about managing
+patatt keyrings at the following page:
+
+* https://pypi.org/project/patatt/#getting-started-as-a-project-maintainer
+
+b4 kr --show-keys
+-----------------
+At this stage, b4 has limited support for keyring management, but there
+are plans to expand this functionality in one of the future versions. At
+most, you can view what keys were used to sign a set of patches in a
+thread, e.g.::
+
+    $ b4 kr --show-keys <msgid>
+    Grabbing thread from lore.kernel.org/all/<msgid>/t.mbox.gz
+    ---
+    alice.developer@example.org: (unknown)
+        keytype: ed25519
+         pubkey: AbCdzUj91asvincQGOFx6+ZF5AoUuP9GdOtQChs7Mm0=
+         krpath: ed25519/example.org/alice.developer/20211009
+       fullpath: /home/user/.local/share/b4/keyring/ed25519/example.org/alice.developer/20211009
+    ---
+    For ed25519 keys:
+        echo [pubkey] > [fullpath]
+
+At this time, if you want to store this public key in your local
+keyring, you can run the command suggested above::
+
+    echo AbCdzUj91asvincQGOFx6+ZF5AoUuP9GdOtQChs7Mm0= > \
+        /home/user/.local/share/b4/keyring/ed25519/example.org/alice.developer/20211009
+
+Now if you come across a signed set of patches from alice.developer, you
+should be able to view the attestation status in the ``b4 am`` output.
+
diff --git a/docs/maintainer/pr.rst b/docs/maintainer/pr.rst
new file mode 100644
index 0000000..631d31a
--- /dev/null
+++ b/docs/maintainer/pr.rst
@@ -0,0 +1,82 @@
+b4 pr: working with pull requests
+=================================
+In addition to working with patches and patch series, b4 is also able to
+work with pull requests. It provides the following benefits as opposed
+to using git directly:
+
+* it can check if the pull request has already been applied before
+  performing a git fetch
+* it will check the signature on the tag (or tip commit)
+* it can track applied pull requests and send replies to submitters
+  (using ``b4 ty``)
+* it can explode a pull request into a series of patches for code review
+  purposes
+
+Basic usage is very similar to ``b4 am``::
+
+    b4 pr <msgid>
+
+By default, this will fetch the pull request into ``FETCH_HEAD``.
+
+Optional flags
+--------------
+
+``-g GITDIR, --gitdir GITDIR``
+  This specifies (or overrides) the git directory where the pull request
+  should be applied.
+
+``-b BRANCH, --branch BRANCH``
+  After fetching the pull request into ``FETCH_HEAD``, check it out as a
+  new branch with the name specified.
+
+``-c, --check``
+  Check if the specified pull request has already been applied.
+
+Exploding pull requests
+-----------------------
+Pull requests are useful, but if the maintainer needs to do more than
+just accept or reject it, providing code review commentary on a PR can
+be difficult. For this reason, b4 can convert a pull request into a
+mailbox full of patches, as if the pull request was sent as a patch
+series. The exploded pull request will retain the correct author and
+To/Cc headers.
+
+``-e, --explode``
+  Instructs b4 to convert a pull request to a series of patches and save
+  them as a mailbox file.
+
+``-o OUTMBOX, --output-mbox OUTMBOX``
+  If ``-o`` is not provided, the mailbox name will be based on the
+  message-id of the pull request and saved in the local directory. This
+  allows overriding that with a different path and name.
+
+Explode archival features
+~~~~~~~~~~~~~~~~~~~~~~~~~
+.. note::
+
+   These are experimental features that were developed for internal
+   kernel.org use.
+
+The following flags are mostly useful when b4 is used
+for archival purposes. One of the goals of this feature was to make it
+possible to save pull requests, which are transient by nature, into an
+archival public-inbox so they can be analyzed by archivists at a later
+date if necessary.
+
+``-l, --retrieve-links``
+  Will attempt to retrieve URLs specified in Link: trailers, in case
+  they are discussion threads. If successful, they will be compressed
+  and attached to the cover letter as .mbx.gz files.
+
+``-f MAILFROM, --from-addr MAILFROM``
+  **(DEPRECATED)** When exploding pull requests, use this email address
+  in the From header, instead of reusing the same From as in the pull
+  request.
+
+``-s SENDIDENTITY, --send-as-identity SENDIDENTITY``
+  **(DEPRECATED)** When resending pull requests as patch series, use
+  this sendemail identity.
+
+``--dry-run``
+  **(DEPRECATED)** Force a --dry-run on ``git-send-email`` invocation.
+
diff --git a/docs/maintainer/prs.rst b/docs/maintainer/prs.rst
deleted file mode 100644
index 0aeccb4..0000000
--- a/docs/maintainer/prs.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-Working with pull requests
-==========================
-
-Stub.
diff --git a/docs/maintainer/thanks.rst b/docs/maintainer/thanks.rst
deleted file mode 100644
index cc46933..0000000
--- a/docs/maintainer/thanks.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-Sending automated contributor feedback
-======================================
-
-Stub.
diff --git a/docs/maintainer/ty.rst b/docs/maintainer/ty.rst
new file mode 100644
index 0000000..7ca0449
--- /dev/null
+++ b/docs/maintainer/ty.rst
@@ -0,0 +1,125 @@
+b4 ty: sending automated contributor feedback
+=============================================
+B4 makes it easier to send automated developer feedback when you apply
+patches or pull requests to your git tree.
+
+Tracking retrieved patches and PRs
+----------------------------------
+Any patches or pull requests you retrieve with ``b4 am,shazam,pr`` will
+be automatically tracked by b4 in your homedir (usually, in
+``$HOME/.local/share/b4``, but may vary if your ``$XDG_DATA_HOME`` is
+set to a different value). There are three 4 kids of files in that
+directory:
+
+* .am: contain information about patches retrieved with ``b4 am`` or
+  ``b4 shazam``
+* .pr: contain information about pull requests retrieved with ``b4 pr``
+* .sent: either .am or .pr tracked files that were successfully sent
+  using ``b4 ty``
+* .discarded: either .am or .pr tracked files that were deleted using
+  ``b4 ty``
+
+All of these files contain JSON data about the series or pull requests
+being tracked.
+
+Using the --auto thankanator
+----------------------------
+If you've retrieved and applied some patches to your tree, you should be
+able to fire up the "auto-thankanator", which uses patch-id and commit
+subject tracking to figure out which series from those you have
+retrieved were applied to your tree. The process is usually pretty
+fast and fairly accurate.
+
+Manually listing and thanking
+-----------------------------
+If you don't want to use the auto-thankanator, or if it's not finding a
+patch series (e.g. because you've made changes to a commit before
+applying it to your tree), you can use a more manual process. First,
+list all tracked series::
+
+    $ b4 ty -l
+
+Identify the series that you're sure got applied, then generate the
+thank-you message::
+
+    $ b4 ty -t 1
+
+This will write out a .thanks file in the current directory, which you
+can then modify and send out.
+
+Sending out mail vs. writing .thanks files
+------------------------------------------
+By default, ``b4 ty`` will write out .thanks files in the current
+directory, which allows you to edit the body of the message before
+sending it out, e.g. using ``mutt``::
+
+    $ mutt -f foo.thanks
+
+However, if you have a configured ``sendemail`` section, you can also
+tell b4 to send out the thanks message directly::
+
+    $ b4 ty -aS --dry-run
+
+The above command will locate all tracked series that got applied to
+your tree and show the messages that are going to be sent out. If you're
+happy with the results, you can omit the ``--dry-run`` switch to
+actually send the mail.
+
+Editing the templates
+---------------------
+You can edit the default templates that are provided with b4 to
+customize the thank-you message. Once you have your own versions, you
+can specify the path to the template to use via the
+``b4.thanks_am_template`` and ``b4.thanks_pr_template`` configuration
+parameters. See :ref:`ty_settings` for details.
+
+Optional flags
+--------------
+``-g GITDIR, --gitdir GITDIR``
+  The git tree to use instead of the current working directory.
+
+``-o OUTDIR, --outdir OUTDIR``
+  Where to write the .thanks files if not into the current directory.
+  Has no effect when ``-S`` is used.
+
+``-l, --list``
+  Lists all tracked patch series and pull requests.
+
+``-t THANKFOR, --thank-for THANKFOR``
+  From the listing generated by ``--list``, specify which thank-you
+  notes should be sent. This command accepts comma-separated values and
+  ranges, including open-ended ranges, e.g.: ``-t 1,3,5-7,9-``. It also
+  accepts ``all``.
+
+``-d DISCARD, --discard DISCARD``
+  From the listing generated by ``--list``, specify which thank-you
+  notes should be discarded. This command accepts comma-separated values
+  and ranges, including open-ended ranges, e.g.: ``-t 1,3,5-7,9-``. It
+  also accepts ``all``.
+
+``-a, --auto``
+  The auto-thankanator: uses patch-id and commit subject matching to
+  figure out which tracked series or pull request have been applied to
+  your tree.
+
+``-b BRANCH, --branch BRANCH``
+  When using ``--auto``, specify which git branch should be used if not
+  the currently active branch.
+
+``--since SINCE``
+  When using ``--auto``, this lets you adjust how far back b4 will look
+  to find your own commits. Takes the same format as ``--since`` flags
+  passed to git, with the default of ``1.week``.
+
+``-S, --send-email``
+  Instead of writing .thanks files, send the email directly. Requires
+  that the ``sendemail`` section is present in your git configuration.
+
+``--dry-run``
+  When used with ``-S``, will not actually send email, just print them
+  out to stdout.
+
+``--pw-set-state PW_SET_STATE``
+  When patchwork integration is configured, sets the specified patchwork
+  state instead of the default specified in config settings (use with
+  -a, -t or -d). See :ref:`patchwork_settings` for more details.