From 4be04f0af9a22087d0052838e013ef2de1ce2ac3 Mon Sep 17 00:00:00 2001 From: Konstantin Ryabitsev Date: Fri, 10 Apr 2020 16:18:17 -0400 Subject: 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 --- man/b4.5 | 106 +++++++++++++++++++++++++++++++++++++++++---- man/b4.5.rst | 45 +++++++++++++++++-- thanks-am-template.example | 28 ++++++++++++ thanks-pr-template.example | 28 ++++++++++++ 4 files changed, 195 insertions(+), 12 deletions(-) create mode 100644 thanks-am-template.example create mode 100644 thanks-pr-template.example 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 " 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 " from gitconfig +${signature} -- cgit v1.2.3