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

OpenSubmitted by Joshua Branson.
Details
2 participants
  • Joshua Branson
  • Michael Albinus
Owner
unassigned
Severity
normal
J
J
Joshua Branson wrote 6 days ago
(address . guix-patches@gnu.org)(name . Joshua Branson)(address . jbranso@dismail.de)
20220805012310.5999-1-jbranso@dismail.de
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

Toggle diff (149 lines)
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
J
J
Joshua Branson wrote 6 days ago
(address . 56987@debbugs.gnu.org)
87h72rv5k6.fsf@dismail.de
Joshua Branson <jbranso@dismail.de> writes:

Toggle quote (6 lines)
> 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!


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!

Toggle quote (158 lines)
>
> * 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
J
J
Joshua Branson wrote 2 hours ago
(address . 56987@debbugs.gnu.org)
87tu6kp1s7.fsf_-_@dismail.de
Joshua Branson <jbranso@dismail.de> writes:

I emailed the help-gnu-emacs list, to try ask how I would write a
function to only get open guix bugs and got back a pretty good reply. I
am just reposting those messages here:

Toggle quote (25 lines)
>> But you can play with the QUERY argument of
>> debbugs-gnu-search, like (this will get you only open bugs)
>>
>> (debbugs-gnu-search (read-string "Search String: ") '((pending . "open")) nil '("guix" "guix-patches"))

> Are you sure that works?
>
> (debbugs-gnu-search "wterm" '((status . "open")) nil '("guix" "guix-patches"))
>
> returns nothing
>
> (debbugs-gnu-search "wterm" '((pending . "open")) nil '("guix" "guix-patches"))
>
> returns nothing
>
> (debbugs-gnu-search "wterm" nil nil '("guix" "guix-patches"))
>
> returns only closed bugs. odd.
>
> M-x debbugs-gnu-search RET "wterm" RET RET x
>
> correctly returns bug 56965, which is an open bug.
>
> What am I doing wrong?

Michael Albinus <michael.albinus@gmx.de> writes:

Hi Joshua,

Well, I found the time now to check what's up.

Toggle quote (4 lines)
> Hmm, looks like there's an error in debbugs-gnu-search. I'll check, but
> perhaps you might write a bug report about. I don't know whether I can
> handle it just now, due to time constraints.

There's indeed an error. The "status" attribute, when there is non-empty
query string, must be "pending" instead of "open". And it is mapped
internally to the attribute "pending".

All this shouldn't worry you. I've just pushed debbugs 0.33, which will appear
in a couple of hours on GNU ELPA. For the time being, you can apply

(debbugs-gnu-search "wterm" '((pending . "pending")) nil '("guix" "guix-patches"))

If you want to see only closed bugs, then call

(debbugs-gnu-search "wterm" '((pending . "done")) nil '("guix" "guix-patches"))

And if you want to see all bugs with this search string, there is

(debbugs-gnu-search "wterm" nil nil '("guix" "guix-patches"))

Best regards, Michael.


So I will be resubmitting this patch set, with a debbugs-guix-search
function that by default only returns open bug reports.

Thanks,

Joshua
M
M
Michael Albinus wrote 46 minutes ago
(name . Joshua Branson)(address . jbranso@dismail.de)(address . 56987@debbugs.gnu.org)
87sfm4dp4r.fsf@gmx.de
Joshua Branson <jbranso@dismail.de> writes:

Hi Joshua,

just some comments after short reading of the patch.

Toggle quote (4 lines)
> @example
> @kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
> @end example

Alternatively, a user could set debbugs-gnu-default-packages to '("guix" "guix-patches")
Then it won't be necessary to enter the package name(s) again and again.

Toggle quote (2 lines)
> +;; Copyright (C) 2022 Joshua Branson

This would change to FSF, if bundled with the debbugs package.

Toggle quote (2 lines)
> +;; Package-Requires: ((emacs "24.3"))

debbugs.el says

;; Package-Requires: ((emacs "26.1") (soap-client "3.1.5"))

So I guess you might lift up the required Emacs version.

Toggle quote (5 lines)
> +;; 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))

As said the other message, it should be

(debbugs-gnu-search (read-string "Search String: ") '((pending . "pending")) nil '("guix" "guix-patches"))

Toggle quote (4 lines)
> +;; 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. :)

To be more precise, the Hyperestraier search engine on debbugs.gnu.org
makes new indices after that period. New submitted bugs are in the
debbugs database shortly after sending the message. It is just
debbugs-gnu-search, which needs these indices.

Toggle quote (4 lines)
> +;; 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...

debbugs.el uses a cache, which flushes the value after an hour. See the
variable debbugs-cache-expiry.

There is the command debbugs-gnu-rescan, bound to key "g", which rescans
an existing tabulated list. With a prefix argument ("C-u g"), the cache
is ignored, and the data are retrieved directly from debbugs.gnu.el.

However, please be cautious with invalidating the cache. Every action on
the debbugs.gnu.org server causes a workload there, and we don't want to
overuse it.

Best regards, Michael.
?