[bug#65746] [PATCH] doc: Document mumi command-line interface.

[bug#65746] [PATCH] doc: Document mumi command-line interface.

[Arun Isaac]

* doc/contributing.texi (Debbugs User Interfaces)[Command-line interface]: New
subsubsection.
* doc/guix.texi: Bump copyright year.
---
 doc/contributing.texi | 84 +++++++++++++++++++++++++++++++++++++++++++
 doc/guix.texi         |  2 +-
 2 files changed, 85 insertions(+), 1 deletion(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 69f0327afb..d752838861 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1625,6 +1625,8 @@ Managing Patches and Branches
 @node Debbugs User Interfaces
 @subsection Debbugs User Interfaces
 
+@subsubsection Web interface
+
 A web interface (actually @emph{two} web interfaces!) are available to
 browse issues:
 
@@ -1646,6 +1648,88 @@ Debbugs User Interfaces
 @indicateurl{https://issues.guix.gnu.org/@var{n}} or
 @indicateurl{https://bugs.gnu.org/@var{n}}.
 
+@subsubsection Command-line interface
+
+Mumi also comes with a command-line interface that can be used to search
+existing issues, open new issues and send patches.  You do not need to
+use Emacs to use the mumi command-line client.  You interact with it
+only on the command-line.
+
+To use the mumi command-line interface, navigate to a local clone of the
+guix git repository, and drop into a shell with mumi, git and
+git:send-email installed.
+
+@example
+$ cd guix
+~/guix$ guix shell mumi git git:send-email
+@end example
+
+To search for issues, say all open issues about "zig", run
+
+@example
+~/guix [env]$ mumi search zig is:open
+
+#60889 Add zig-build-system
+opened on 17 Jan 17:37 Z by Ekaitz Zarraga
+#61036 [PATCH 0/3] Update zig to 0.10.1
+opened on 24 Jan 09:42 Z by Efraim Flashner
+#39136 [PATCH] gnu: services: Add endlessh.
+opened on 14 Jan 2020 21:21 by Nicol? Balzarotti
+#60424 [PATCH] gnu: Add python-online-judge-tools
+opened on 30 Dec 2022 07:03 by gemmaro
+#45601 [PATCH 0/6] vlang 0.2 update
+opened on  1 Jan 2021 19:23 by Ryan Prior
+@end example
+
+Pick an issue and make it the "current" issue.
+
+@example
+~/guix [env]$ mumi current 61036
+
+#61036 [PATCH 0/3] Update zig to 0.10.1
+opened on 24 Jan 09:42 Z by Efraim Flashner
+@end example
+
+Once an issue is the current issue, you can easily create and send
+patches to it using
+
+@example
+~/guix [env]$ git format-patch origin/master
+~/guix [env]$ mumi send-email foo.patch bar.patch
+@end example
+
+Note that you do not have to pass in @samp{--to} or @samp{--cc}
+arguments to @command{git format-patch}.  @command{mumi send-email} will
+put them in correctly when sending the patches.
+
+To open a new issue, run
+
+@example
+~/guix [env]$ mumi new
+@end example
+
+and send patches
+
+@example
+~/guix [env]$ mumi send-email foo.patch bar.patch
+@end example
+
+@command{mumi send-email} is really a wrapper around @command{git
+send-email} that automates away all the nitty-gritty of sending patches.
+It uses the current issue state to automatically figure out the correct
+@samp{To} address to send to, other participants to @samp{Cc}, headers
+to add, etc.
+
+Also note that, unlike @command{git send-email}, @command{mumi
+send-email} works perfectly well with single and multiple patches alike.
+It automates away the debbugs dance of sending the first patch, waiting
+for a response from debbugs and sending the remaining patches.  It does
+so by sending the first patch, polling the server for a response, and
+then sending the remaining patches.  This polling can unfortunately take
+a few minutes.  So, please be patient.
+
+@subsubsection Emacs interface
+
 If you use Emacs, you may find it more convenient to interact with
 issues using @file{debbugs.el}, which you can install with:
 
diff --git a/doc/guix.texi b/doc/guix.texi
index 9e79641736..eca9c3c487 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -53,7 +53,7 @@
 Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
 Copyright @copyright{} 2017 George Clemmer@*
 Copyright @copyright{} 2017 Andy Wingo@*
-Copyright @copyright{} 2017, 2018, 2019, 2020 Arun Isaac@*
+Copyright @copyright{} 2017, 2018, 2019, 2020, 2023 Arun Isaac@*
 Copyright @copyright{} 2017 nee@*
 Copyright @copyright{} 2018 Rutger Helling@*
 Copyright @copyright{} 2018, 2021 Oleg Pykhalov@*

base-commit: bedcdf0fb5ac035f696790827679406c7146396c
-- 
2.39.2

bug#65746: [PATCH] doc: Document mumi command-line interface.

[Maxim Cournoyer]

Hi Arun,

Arun Isaac <arunisaac@systemreboot.net> writes:

> * doc/contributing.texi (Debbugs User Interfaces)[Command-line interface]: New
> subsubsection.
> * doc/guix.texi: Bump copyright year.
> ---
>  doc/contributing.texi | 84 +++++++++++++++++++++++++++++++++++++++++++
>  doc/guix.texi         |  2 +-

Great write-up!  I've installed it.

-- 
Thanks,
Maxim

[bug#65746] [PATCH] doc: Document mumi command-line interface.

[Arun Isaac]

Hi Maxim,

Thanks for pushing the patch. I also feel that "(guix) Sending a Patch
Series" should be rewritten. Currently, it mentions that `git
send-email' is the *best* way to send patches. It should now be only
listed as one of two ways with `mumi send-email' being the preferred
option since it is easier and less cognitive overhead to use.

WDYT? Shall I send another patch about this?

Thanks!
Arun

[bug#65746] [PATCH] doc: Document mumi command-line interface.

[Maxim Cournoyer]

Hi Arun,

Arun Isaac <arunisaac@systemreboot.net> writes:

> Hi Maxim,
>
> Thanks for pushing the patch. I also feel that "(guix) Sending a Patch
> Series" should be rewritten. Currently, it mentions that `git
> send-email' is the *best* way to send patches. It should now be only
> listed as one of two ways with `mumi send-email' being the preferred
> option since it is easier and less cognitive overhead to use.
>
> WDYT? Shall I send another patch about this?

I think it'd be beneficial to plug the 'mumi' command there yes; I agree
that it should be preferred to a plain 'git send-email' given it knows
to CC all participants in the conversation (until Debbugs can be taught
to do that itself (i.e. subscribe all participants to new mails sent to
NNNNN@debbugs.gnu.org)).  Maybe our .patman config could changed to use
'mumi send-email' as well, instead of 'git send-email' (or prefer it,
then fall-back to git send-email, maybe with a message).

-- 
Thanks,
Maxim