Document b4 ty and add template examples

Still a bit slim on documentation, but this is better than nothing. I
need to write a better README file that will introduce maintainers to
most useful functionality aspects of b4.

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

4 files changed, 195 insertions, 12 deletions

diff --git a/man/b4.5 b/man/b4.5
index 3c15e32..54676cf 100644
--- a/man/b4.5
+++ b/man/b4.5
@@ -1,8 +1,8 @@
 .\" Man page generated from reStructuredText.
 .
-.TH B4 5 "2020-03-23" "0.3.4" ""
+.TH B4 5 "2020-04-10" "0.4.0" ""
 .SH NAME
-B4 \- Work with patches in a public-inbox archive
+B4 \- Work with code submissions in a public-inbox archive
 .
 .nr rst2man-indent-level 0
 .
@@ -32,13 +32,13 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH SYNOPSIS
 .sp
-b4 {mbox,am,attest,attverify} [options]
+b4 {mbox,am,attest,pr,ty} [options]
 .SH DESCRIPTION
 .sp
-This is a helper utility to work with patches made available via a
-public\-inbox archive like lore.kernel.org. It is written to make it
-easier to participate in a patch\-based workflows, like those used in
-the Linux kernel development.
+This is a helper utility to work with patches and pull requests made
+available via a public\-inbox archive like lore.kernel.org. It is
+written to make it easier to participate in a patch\-based workflows,
+like those used in the Linux kernel development.
 .sp
 The name "b4" was chosen for ease of typing and because B\-4 was the
 precursor to Lore and Data in the Star Trek universe.
@@ -49,7 +49,11 @@ precursor to Lore and Data in the Star Trek universe.
 .IP \(bu 2
 \fIb4 am\fP: Create an mbox file that is ready to git\-am
 .IP \(bu 2
-\fIb4 attest\fP: Submit cryptographic attestation for patches
+\fIb4 attest\fP: (EXPERIMENTAL) Submit cryptographic attestation for patches
+.IP \(bu 2
+\fIb4 pr\fP: (EXPERIMENTAL) Work with pull requests
+.IP \(bu 2
+\fIb4 ty\fP: (EXPERIMENTAL) Create templated replies for processed patches and pull requests
 .UNINDENT
 .SH OPTIONS
 .INDENT 0.0
@@ -190,6 +194,83 @@ submitting it
 .UNINDENT
 .sp
 \fIExample\fP: b4 attest \-n \-o output/xxxx\-attestation.patch output/*.patch
+.SS b4 pr
+.INDENT 0.0
+.TP
+.B usage:
+command.py pr [\-h] [\-g GITDIR] [\-b BRANCH] [\-c] [\-e] [\-o OUTMBOX] [msgid]
+.TP
+.B positional arguments:
+msgid                 Message ID to process, or pipe a raw message
+.TP
+.B optional arguments:
+.INDENT 7.0
+.TP
+.B \-h\fP,\fB  \-\-help
+show this help message and exit
+.TP
+.BI \-g \ GITDIR\fP,\fB \ \-\-gitdir \ GITDIR
+Operate on this git tree instead of current dir
+.TP
+.BI \-b \ BRANCH\fP,\fB \ \-\-branch \ BRANCH
+Check out FETCH_HEAD into this branch after fetching
+.TP
+.B \-c\fP,\fB  \-\-check
+Check if pull request has already been applied
+.TP
+.B \-e\fP,\fB  \-\-explode
+Convert a pull request into an mbox full of patches
+.TP
+.BI \-o \ OUTMBOX\fP,\fB \ \-\-output\-mbox \ OUTMBOX
+Save exploded messages into this mailbox (default:
+msgid.mbx)
+.UNINDENT
+.UNINDENT
+.sp
+\fIExample\fP: b4 pr \fI\%202003292120.2BDCB41@keescook\fP
+.SS b4 ty
+.INDENT 0.0
+.TP
+.B usage:
+b4 ty [\-h] [\-g GITDIR] [\-o OUTDIR] [\-l] [\-s SEND [SEND ...]] [\-d DISCARD [DISCARD ...]] [\-a] [\-b BRANCH] [\-\-since SINCE]
+.TP
+.B optional arguments:
+.INDENT 7.0
+.TP
+.B \-h\fP,\fB  \-\-help
+show this help message and exit
+.TP
+.BI \-g \ GITDIR\fP,\fB \ \-\-gitdir \ GITDIR
+Operate on this git tree instead of current dir
+.TP
+.BI \-o \ OUTDIR\fP,\fB \ \-\-outdir \ OUTDIR
+Write thanks files into this dir (default=.)
+.TP
+.B \-l\fP,\fB  \-\-list
+List pull requests and patch series you have retrieved
+.TP
+.BI \-s \ SEND\fP,\fB \ \-\-send \ SEND
+Generate thankyous for specified messages (use \-l to
+get the list or "all")
+.TP
+.BI \-d \ DISCARD\fP,\fB \ \-\-discard \ DISCARD
+Discard specified messages (use \-l to get the list, or
+use "all")
+.TP
+.B \-a\fP,\fB  \-\-auto
+Use the Auto\-Thankanator to figure out what got
+applied/merged
+.TP
+.BI \-b \ BRANCH\fP,\fB \ \-\-branch \ BRANCH
+The branch to check against, instead of current
+.TP
+.BI \-\-since \ SINCE
+The \-\-since option to use when auto\-matching patches
+(default=1.week)
+.UNINDENT
+.UNINDENT
+.sp
+\fIExample\fP: b4 ty \-\-auto
 .SH CONFIGURATION
 .sp
 B4 configuration is handled via git\-config(1), so you can store it in
@@ -251,6 +332,15 @@ Default configuration, with explanations:
    #
    # How long to keep downloaded threads in cache (minutes)?
    cache\-expire = 10
+   # Used when creating summaries for b4 ty, and can be set to a value like
+   # thanks\-commit\-url\-mask = https://git.kernel.org/username/c/%.10s
+   # See this page for more info on convenient git.kernel.org shorterners:
+   # https://korg.wiki.kernel.org/userdoc/git\-url\-shorterners
+   thanks\-commit\-url\-mask = None
+   # See thanks\-pr\-template.example. If not set, a default template will be used.
+   thanks\-pr\-template = None
+   # See thanks\-am\-template.example. If not set, a default template will be used.
+   thanks\-am\-template = None
 .ft P
 .fi
 .UNINDENT
diff --git a/man/b4.5.rst b/man/b4.5.rst
index a95a8bd..4938217 100644
--- a/man/b4.5.rst
+++ b/man/b4.5.rst
@@ -5,7 +5,7 @@ Work with code submissions in a public-inbox archive
 ----------------------------------------------------
 
 :Author:    mricon@kernel.org
-:Date:      2020-04-08
+:Date:      2020-04-10
 :Copyright: The Linux Foundation and contributors
 :License:   GPLv2+
 :Version:   0.4.0
@@ -13,7 +13,7 @@ Work with code submissions in a public-inbox archive
 
 SYNOPSIS
 --------
-b4 {mbox,am,attest,attverify} [options]
+b4 {mbox,am,attest,pr,ty} [options]
 
 DESCRIPTION
 -----------
@@ -29,8 +29,9 @@ SUBCOMMANDS
 -----------
 * *b4 mbox*: Download a thread as an mbox file
 * *b4 am*: Create an mbox file that is ready to git-am
-* *b4 attest*: Submit cryptographic attestation for patches
-* *b4 pr*: Work with pull requests
+* *b4 attest*: (EXPERIMENTAL) Submit cryptographic attestation for patches
+* *b4 pr*: (EXPERIMENTAL) Work with pull requests
+* *b4 ty*: (EXPERIMENTAL) Create templated replies for processed patches and pull requests
 
 OPTIONS
 -------
@@ -145,6 +146,33 @@ optional arguments:
 
 *Example*: b4 pr 202003292120.2BDCB41@keescook
 
+b4 ty
+~~~~~
+usage:
+  b4 ty [-h] [-g GITDIR] [-o OUTDIR] [-l] [-s SEND [SEND ...]] [-d DISCARD [DISCARD ...]] [-a] [-b BRANCH] [--since SINCE]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -g GITDIR, --gitdir GITDIR
+                        Operate on this git tree instead of current dir
+  -o OUTDIR, --outdir OUTDIR
+                        Write thanks files into this dir (default=.)
+  -l, --list            List pull requests and patch series you have retrieved
+  -s SEND, --send SEND
+                        Generate thankyous for specified messages (use -l to
+                        get the list or "all")
+  -d DISCARD, --discard DISCARD
+                        Discard specified messages (use -l to get the list, or
+                        use "all")
+  -a, --auto            Use the Auto-Thankanator to figure out what got
+                        applied/merged
+  -b BRANCH, --branch BRANCH
+                        The branch to check against, instead of current
+  --since SINCE         The --since option to use when auto-matching patches
+                        (default=1.week)
+
+*Example*: b4 ty --auto
+
 CONFIGURATION
 -------------
 B4 configuration is handled via git-config(1), so you can store it in
@@ -202,6 +230,15 @@ Default configuration, with explanations::
       #
       # How long to keep downloaded threads in cache (minutes)?
       cache-expire = 10
+      # Used when creating summaries for b4 ty, and can be set to a value like
+      # thanks-commit-url-mask = https://git.kernel.org/username/c/%.10s
+      # See this page for more info on convenient git.kernel.org shorterners:
+      # https://korg.wiki.kernel.org/userdoc/git-url-shorterners
+      thanks-commit-url-mask = None
+      # See thanks-pr-template.example. If not set, a default template will be used.
+      thanks-pr-template = None
+      # See thanks-am-template.example. If not set, a default template will be used.
+      thanks-am-template = None
 
 
 SUPPORT
diff --git a/thanks-am-template.example b/thanks-am-template.example
new file mode 100644
index 0000000..72a8759
--- /dev/null
+++ b/thanks-am-template.example
@@ -0,0 +1,28 @@
+# Lines starting with '#' will be removed
+# You can have two different templates for responding to
+# pull requests and for responding to patch series, though
+# in reality the difference will probably be one word:
+# "merged/pulled" vs. "applied".
+# Keeping it short and sweet is preferred.
+#
+On ${sentdate}, ${fromname} wrote:
+# quote will be limited to 5-6 lines, respecting paragraphs
+${quote}
+
+Applied, thanks!
+
+# for patch series, the summary is a list of each patch with a link
+# to the commit id in your tree, so you probably want to set
+# b4.thanks-commit-url-mask in gitconfig to a value like:
+# [b4]
+#   thanks-commit-url-mask = https://git.kernel.org/username/c/%.10s
+#
+# Check this page for info on convenient URL shorteners:
+# https://korg.wiki.kernel.org/userdoc/git-url-shorterners
+${summary}
+
+Best regards,
+-- 
+# if ~/.signature exists, it will be put here, otherwise
+# the contents will be "user.name <user.email>" from gitconfig
+${signature}
diff --git a/thanks-pr-template.example b/thanks-pr-template.example
new file mode 100644
index 0000000..4994b29
--- /dev/null
+++ b/thanks-pr-template.example
@@ -0,0 +1,28 @@
+# Lines starting with '#' will be removed
+# You can have two different templates for responding to
+# pull requests and for responding to patch series, though
+# in reality the difference will probably be one word:
+# "merged/pulled" vs. "applied".
+# Keeping it short and sweet is preferred.
+#
+On ${sentdate}, ${fromname} wrote:
+# quote will be limited to 5-6 lines, respecting paragraphs
+${quote}
+
+Merged, thanks!
+
+# for pull requests, the summary is a one-liner with the merge commit,
+# so you probably want to set b4.thanks-commit-url-mask in gitconfig
+# to a value like:
+# [b4]
+#   thanks-commit-url-mask = https://git.kernel.org/username/c/%.10s
+#
+# Check this page for info on convenient URL shorteners:
+# https://korg.wiki.kernel.org/userdoc/git-url-shorterners
+${summary}
+
+Best regards,
+-- 
+# if ~/.signature exists, it will be put here, otherwise
+# the contents will be "user.name <user.email>" from gitconfig
+${signature}