Merge branch 'master' into emacs-team

1 files changed, 75 insertions, 6 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index a0da871f1a..ce4b9db366 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -77,6 +77,12 @@ hack on Guix:
 guix shell -D guix --pure
 @end example
 
+or even, from within a Git worktree for Guix:
+
+@example
+guix shell --pure
+@end example
+
 @xref{Invoking guix shell}, for more information on that command.
 
 If you are unable to use Guix when building Guix from a checkout, the
@@ -204,12 +210,11 @@ To that end, all the command-line tools can be used even if you have not
 run @code{make install}.  To do that, you first need to have an
 environment with all the dependencies available (@pxref{Building from
 Git}), and then simply prefix each command with @command{./pre-inst-env}
-(the @file{pre-inst-env} script lives in the top build tree of Guix; it
-is generated by running @command{./bootstrap} followed by
-@command{./configure}).  As an example, here is how you would build the
-@code{hello} package as defined in your working tree (this assumes
-@command{guix-daemon} is already running on your system; it's OK if it's
-a different version):
+(the @file{pre-inst-env} script lives in the top build tree of Guix;
+@pxref{Building from Git} to generate it).  As an example, here is how you
+would build the @code{hello} package as defined in your working tree (this
+assumes @command{guix-daemon} is already running on your system; it's OK if
+it's a different version):
 
 @example
 $ ./pre-inst-env guix build hello
@@ -379,6 +384,70 @@ copyright-update}.  If you want to do it automatically after each buffer
 save then add @code{(add-hook 'after-save-hook 'copyright-update)} in
 Emacs.
 
+@subsection Viewing Bugs within Emacs
+
+Emacs has a nice minor mode called @code{bug-reference}, which, when
+combined with @samp{emacs-debbugs} (the Emacs package), can be used to
+open links such as @samp{<https://bugs.gnu.org/58697>} or
+@samp{<https://issues.guix.gnu.org/58697>} as bug report buffers.  From
+there you can easily consult the email thread via the Gnus interface,
+reply or modify the bug status, all without leaving the comfort of
+Emacs!  Below is a sample configuration to add to your @file{~/.emacs}
+configuration file:
+
+@lisp
+;;; Bug references.
+(add-hook 'prog-mode-hook #'bug-reference-prog-mode)
+(add-hook 'gnus-mode-hook #'bug-reference-mode)
+(add-hook 'erc-mode-hook #'bug-reference-mode)
+(add-hook 'bug-reference-mode-hook 'debbugs-browse-mode)
+(add-hook 'bug-reference-prog-mode-hook 'debbugs-browse-mode)
+(add-hook 'gnus-summary-mode-hook 'bug-reference-mode)
+(add-hook 'gnus-article-mode-hook 'bug-reference-mode)
+
+;;; This extends the default expression (the top-most, first expression
+;;; provided to 'or') to also match URLs such as
+;;; <https://issues.guix.gnu.org/58697> or <https://bugs.gnu.org/58697>.
+;;; It is also extended to detect "Fixes: #NNNNN" git trailers.
+(setq bug-reference-bug-regexp
+      (rx (group (or (seq word-boundary
+                          (or (seq (char "Bb") "ug"
+                                   (zero-or-one " ")
+                                   (zero-or-one "#"))
+                              (seq (char "Pp") "atch"
+                                   (zero-or-one " ")
+                                   "#")
+                              (seq (char "Ff") "ixes"
+                                   (zero-or-one ":")
+                                   (zero-or-one " ") "#")
+                              (seq "RFE"
+                                   (zero-or-one " ") "#")
+                              (seq "PR "
+                                   (one-or-more (char "a-z+-")) "/"))
+                          (group (one-or-more (char "0-9"))
+                                 (zero-or-one
+                                  (seq "#" (one-or-more
+                                            (char "0-9"))))))
+                     (seq "<https://bugs.gnu.org/"
+                          (group-n 2 (one-or-more (char "0-9")))
+                          ">")))))
+
+;; The following allows Emacs Debbugs user to open the issue directly within
+;; Emacs.
+(setq debbugs-browse-url-regexp
+      (rx line-start
+          "http" (zero-or-one "s") "://"
+          (or "debbugs" "issues.guix" "bugs")
+          ".gnu.org" (one-or-more "/")
+          (group (zero-or-one "cgi/bugreport.cgi?bug="))
+          (group-n 3 (one-or-more digit))
+          line-end))
+@end lisp
+
+For more information, refer to @ref{Bug Reference,,, emacs, The GNU
+Emacs Manual} and @ref{Minor Mode,,, debbugs-ug, The Debbugs User
+Guide}.
+
 @node Packaging Guidelines
 @section Packaging Guidelines