[bug#56987] [PATCH] etc: guix-debbugs.el: new file.

[Joshua Branson]

Joshua Branson <jbranso@dismail.de> writes:

> New users may find the default debbugs commands a little awkward to use.
> This patch provides three new functions and documentation that may ease
> them into using debbugs and encourages them to close their open bug
> reports.
>

This patch now has an acompany video!

https://video.hardlimit.com/w/gDMR9y2jhB5SkSp8iqEyK8

The video is 13 minutes long, and it explains my motivations for
submitting this patch.  Namely that debbugs can be a little confusing
and hard for new comers to set up.

I also spotted some errors with my debbugs-guix-search function as I was
making the video.  I am not certain what the problem was.  Basically
debbugs-gnu-search found my open wterm related bug, bug
debbugs-guix-search did not.  Weird.

The documentation also helps newbies set up sending email in Emacs,
which is essential to use the emacs' debbugs interface as it was
intended.

I hope others find it helpful!

>
> * etc/guix-debbugs.el (debbugs-guix-search, debbugs-my-open-bugs,
> debbugs-get-bug-by-id): new procedures.
> * doc/contributing.texi (Debbugs User Interfaces): documented the new
> emacs procedures and explained how to modify .emacs.d to use them.
> ---
>  doc/contributing.texi | 57 +++++++++++++++++++++++++++++++++++--
>  etc/guix-debbugs.el   | 65 +++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 120 insertions(+), 2 deletions(-)
>  create mode 100644 etc/guix-debbugs.el
>
> diff --git a/doc/contributing.texi b/doc/contributing.texi
> index 02c7c5ae59..683b9bd9d2 100644
> --- a/doc/contributing.texi
> +++ b/doc/contributing.texi
> @@ -1453,14 +1453,67 @@ issues using @file{debbugs.el}, which you can install 
> with:
>  guix install emacs-debbugs
>  @end example
>  
> -For example, to list all open issues on @code{guix-patches}, hit:
> +Newcomers may find the default debbugs functions awkward to use.  We
> +provide three helper functions that will help you start contributing to
> +guix sooner:
> +
> +@table @asis
> +@item @code{M-x debbugs-guix-search}
> +to search for guix bugs.
> +
> +@item @code{M-x debbugs-my-open-bugs}
> +to search for your open bug reports.  These are reports that you
> +submitted.  Once every six months, run this command, and try to close
> +your open bugs.  Or just update the bug report with something like,
> +'This is still a bug.  Please do not close this bug.'
> +
> +@item @code{M-x debbugs-get-bug-by-id}
> +to search for bugs by the 5 digit bug number.
> +@end table
> +
> +To start using these guix specific functions, define the variable
> +@code{user-mail-address}, and put the following into your
> +@code{.emacs.d} (assuming the guix source is located in ~/src/guix/):
> +
> +@lisp
> +(setq user-mail-address "awesomecoder@@gnu.org")
> +
> +(load-file "~/src/guix/etc/guix-debbugs.el")
> +
> +(setq smtpmail-smtp-user user-mail-address
> +      message-send-mail-function 'smtpmail-send-it
> +      send-mail-function 'smtpmail-send-it
> +      ;; customize this variable to suit your smtp email server.
> +      smtpmail-smtp-server "smtp.gnu.org"
> +      ;; customize this variable to suit your email server's port.
> +      smtpmail-smtp-service 587)
> +@end lisp
> +
> +Emacs' debbugs interface is awesome, but in order to use it to its
> +fullest potential, you need to set up emacs to send email.  Luckily, the
> +previous lines of code set up Emacs to use email for you! Now, go ahead
> +and test Emacs' email sending ablities via @code{C-x m}.  For testing
> +purposes, send a test email to a friend or to yourself.  To send the
> +message, type in @code{C-c C-c}.  Emacs will ask you for your email
> +password and optionally offer to save it in the unencrypted file
> +@code{~/.authinfo}.  If you would rather save the password to an
> +encrypted file (@code{~/.authinfo.gpg}), then please see
> +@xref{Overview,,, auth, Emacs auth-source} and optionally set up GPG
> +@comment I cannot get the below link to work.  Why?
> +agent (@xref{gnupg, gnupg, gnupg, Invoking GPG-AGENT}). If you can send
> +the email, then you should be all set to use Emacs's debbugs interface!
> +
> +Finally, we encourage all potential contributers to occassionally review
> +some pending patches. There's quite a few!  You can test to see if the
> +patch works for you, and reply to the open bug report.  Here is how you
> +might get started finding the pending patches:
>  
>  @example
>  @kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n 
> y
>  @end example
>  
>  @xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
> -this nifty tool!
> +this nifty tool, like how to close, tag, and merge bug reports!
>  
>  @node Debbugs Usertags
>  @subsection Debbugs Usertags
> diff --git a/etc/guix-debbugs.el b/etc/guix-debbugs.el
> new file mode 100644
> index 0000000000..794489b671
> --- /dev/null
> +++ b/etc/guix-debbugs.el
> @@ -0,0 +1,65 @@
> +;;; package --- Summary -*- lexical-binding: t; -*-
> +;;; guix-debbugs.el Helpful Debbugs Functions for guix
> +;;
> +;; Copyright (C) 2022 Joshua Branson
> +;;
> +;; Author: Joshua Branson <jbranso@dismail.de>
> +;; Maintainer: Joshua Branson <jbranso@dismail.de>
> +;; Created: August 04, 2022
> +;; Modified: August 04, 2022
> +;; Version: 0.0.1
> +;; Keywords: guix debbugs
> +;; Homepage: https://git.savannah.gnu.org/git/guix.git
> +;; Package-Requires: ((emacs "24.3"))
> +;;
> +;; This file is not part of GNU Emacs.
> +;;
> +;;; Commentary:
> +;;
> +;; The debbugs functions are a little awkward to use.  This file provides
> +;; better and easier to use functions for the guix project.  Specifically it
> +;; provides two new functions:
> +;;
> +;; M-x debbugs-guix-search to search for guix bugs
> +;; M-x debbugs-my-open-bugs to search for my open bug reports.
> +;; M-x debbugs-get-buy-by-id to open a specific bug by its ID.
> +;;
> +;;; Code:
> +
> +;; setting up debbugs
> +(require 'debbugs-autoloads)
> +
> +;; Users need to set up send-mail-function.  Otherwise "C" in 
> debbugs-gnu-mode WILL NOT work.
> +;; eg:
> +;;
> +;;     (setq user-mail-address "awesomecoder@gnu.org")
> +;;     (load-file "~/src/guix/etc/guix-debbugs.el")
> +;;     (setq message-send-mail-function 'smtpmail-send-it
> +;;           smtpmail-smtp-user user-mail-address
> +;;           ;; customize this variable to suit your smtp email server.
> +;;           smtpmail-smtp-server "smtp.gnu.org"
> +;;           ;; customize this variable to suit your email server's port.
> +;;           smtpmail-smtp-service 587)
> +
> +;; TODO make this by default only search open bugs AND NOT closed bugs.
> +(defun debbugs-guix-search ()
> +  (interactive)
> +  (debbugs-gnu-search (read-string "Search String: ") nil nil '("guix" 
> "guix-patches") nil))
> +
> +;; the bugs that I submitted and that are still open
> +;; The debbugs database runs once a day.  So after I send a bug report
> +;; and run this command, my latest bug report might not be here.  No worries,
> +;; just wait one day, and it will be there.  :)
> +;;
> +;; I have noticed that this function works 80% of the time.  But after I 
> close bug reports,
> +;; it seems to stop working for about 1/2 hour.  I'm guessing the server's 
> database
> +;; resets itself after every time that I close a bug report...
> +(defun debbugs-my-open-bugs ()
> +  (require 'debbugs)
> +  (interactive)
> +  (apply #'debbugs-gnu-bugs (debbugs-get-bugs :submitter "me" :status 
> "open")))
> +
> +(defalias 'debbugs-get-bug-by-id 'debbugs-gnu-bugs)
> +
> +(provide 'guix-debbugs)
> +;;; guix-debbugs.el ends here
>
> base-commit: d6be56cd09bb6286b51d1efc8981993be2525d87