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

[Joshua Branson]

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.

* 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
-- 
2.37.1