[elpa] externals/debbugs 69b8627 206/311: Document patching from debbugs, and fix some bugs

[Stefan Monnier]

branch: externals/debbugs
commit 69b8627ddb86336b91bf3e4c58e489d4cb37b7e8
Author: Michael Albinus <michael.albinus@gmx.de>
Commit: Michael Albinus <michael.albinus@gmx.de>

    Document patching from debbugs, and fix some bugs
    
    * packages/debbugs/debbugs-gnu.el (debbugs-gnu-emacs-current-release):
    Change value to "25.2".
    (debbugs-gnu-emacs-blocking-reports): Rename from
    `debbugs-gnu-blocking-reports'.
    (debbugs-gnu-show-all-blocking-reports): Optional argument RELEASE.
    (debbugs-gnu-current-directory): New defvar.
    (debbugs-gnu-apply-patch, debbugs-gnu-find-contributor)
    (debbugs-gnu-change-checkin): Use it.
    
    * packages/debbugs/debbugs-ug.texi (Retrieving Bugs): Precise
    commands to show patches.
    (Presenting Bugs): Rename from "Layout".
    (Tabulated Lists): Mention prefix variants of key strokes.
    (TODO Items, Control Messages): Add index entries.
    (Applying Patches): New section.
    
    * packages/debbugs/debbugs.el (debbugs-search-est): Fix docstring.
---
 debbugs-gnu.el  | 145 ++++++++++++++++++++++++++++++++++++++++++++++----------
 debbugs-ug.info | 134 +++++++++++++++++++++++++++++++++------------------
 debbugs-ug.texi |  64 ++++++++++++++++++++-----
 debbugs.el      |   4 +-
 4 files changed, 265 insertions(+), 82 deletions(-)

diff --git a/debbugs-gnu.el b/debbugs-gnu.el
index e868056..96b0f3a 100644
--- a/debbugs-gnu.el
+++ b/debbugs-gnu.el
@@ -336,7 +336,7 @@ a date, value is the cons cell \(BEFORE . AFTER\).")
 The specification which bugs shall be suppressed is taken from
   `debbugs-gnu-default-suppress-bugs'.")
 
-(defcustom debbugs-gnu-emacs-current-release "25.1"
+(defcustom debbugs-gnu-emacs-current-release "25.2"
   "The current Emacs relase developped for."
   :group 'debbugs-gnu
   :type '(choice (const "24.5")
@@ -344,7 +344,7 @@ The specification which bugs shall be suppressed is taken 
from
                 (const "25.2"))
   :version "25.1")
 
-(defconst debbugs-gnu-blocking-reports
+(defconst debbugs-gnu-emacs-blocking-reports
   '(("24.5" . 19758)
     ("25.1" . 19759)
     ("25.2" . 21966))
@@ -1091,19 +1091,24 @@ The following commands are available:
        (message "Bug %d is not blocking any other bug" id)
       (apply 'debbugs-gnu-bugs (cdr (assq 'blocks status))))))
 
-(defun debbugs-gnu-show-all-blocking-reports ()
-  "Narrow the display to just the reports that are blocking a release."
-  (interactive)
+(defun debbugs-gnu-show-all-blocking-reports (&optional release)
+  "Narrow the display to just the reports that are blocking an Emacs release."
+  (interactive
+   (list
+    (if current-prefix-arg
+       (completing-read
+        "Emacs release: "
+        (mapcar 'identity debbugs-gnu-emacs-blocking-reports)
+        nil t debbugs-gnu-emacs-current-release)
+      debbugs-gnu-emacs-current-release)))
+
   (let ((blockers
         (cdr
          (assq
           'blockedby
           (car
            (debbugs-get-status
-            (cdr
-             (assoc
-              debbugs-gnu-emacs-current-release
-              debbugs-gnu-blocking-reports)))))))
+            (cdr (assoc release debbugs-gnu-emacs-blocking-reports)))))))
        (id (debbugs-gnu-current-id t))
        (inhibit-read-only t)
        status)
@@ -1582,6 +1587,9 @@ The following commands are available:
 (defvar debbugs-gnu-branch-directory "~/src/emacs/emacs-25/"
   "The directory where the previous source tree lives.")
 
+(defvar debbugs-gnu-current-directory nil
+  "The current source tree directory.")
+
 (defun debbugs-gnu-apply-patch (&optional branch)
   "Apply the patch from the current message.
 If given a prefix, patch in the branch directory instead."
@@ -1589,22 +1597,29 @@ If given a prefix, patch in the branch directory 
instead."
   (add-hook 'emacs-lisp-mode-hook 'debbugs-gnu-lisp-mode)
   (add-hook 'diff-mode-hook 'debbugs-gnu-diff-mode)
   (add-hook 'change-log-mode-hook 'debbugs-gnu-change-mode)
-  (let ((rej "/tmp/debbugs-gnu.rej")
+  (let ((rej (expand-file-name "debbugs-gnu.rej" temporary-file-directory))
        (output-buffer (get-buffer-create "*debbugs patch*"))
-       (dir (if branch
-                debbugs-gnu-branch-directory
-              debbugs-gnu-trunk-directory))
        (patch-buffers nil))
     (when (file-exists-p rej)
       (delete-file rej))
     (with-current-buffer output-buffer
       (erase-buffer))
+    (setq debbugs-gnu-current-directory
+         (if branch
+             debbugs-gnu-branch-directory
+           debbugs-gnu-trunk-directory))
+    (unless (file-directory-p debbugs-gnu-current-directory)
+      (setq debbugs-gnu-current-directory
+           (read-file-name
+            "Emacs repository location: "
+            debbugs-gnu-current-directory nil t nil 'file-directory-p)))
     (gnus-summary-select-article nil t)
     ;; The patches are either in MIME attachements or the main article
     ;; buffer.  Determine which.
     (gnus-with-article-buffer
       (dolist (handle (mapcar 'cdr (gnus-article-mime-handles)))
-       (when (string-match "diff\\|patch\\|plain" (mm-handle-media-type 
handle))
+       (when
+           (string-match "diff\\|patch\\|plain" (mm-handle-media-type handle))
          (push (cons (mm-handle-encoding handle)
                      (mm-handle-buffer handle))
                patch-buffers))))
@@ -1619,12 +1634,13 @@ If given a prefix, patch in the branch directory 
instead."
               (base64-decode-region (point-min) (point-max)))
              ((eq (car elem) 'quoted-printable)
               (quoted-printable-decode-region (point-min) (point-max))))
-       (debbugs-gnu-fix-patch dir)
+       (debbugs-gnu-fix-patch debbugs-gnu-current-directory)
        (call-process-region (point-min) (point-max)
                             "patch" nil output-buffer nil
                             "-r" rej "--no-backup-if-mismatch"
                             "-l" "-f"
-                            "-d" (expand-file-name dir)
+                            "-d" (expand-file-name
+                                  debbugs-gnu-current-directory)
                             "-p1")))
     (set-buffer output-buffer)
     (when (file-exists-p rej)
@@ -1634,8 +1650,10 @@ If given a prefix, patch in the branch directory 
instead."
     (save-some-buffers t)
     (require 'compile)
     (mapc 'kill-process compilation-in-progress)
-    (compile (format "cd %s; make -k" (expand-file-name "lisp" dir)))
-    (vc-dir dir)
+    (compile
+     (format
+      "cd %s; make -k" (expand-file-name "lisp" 
debbugs-gnu-current-directory)))
+    (vc-dir debbugs-gnu-current-directory)
     (vc-dir-hide-up-to-date)
     (goto-char (point-min))
     (sit-for 1)
@@ -1691,7 +1709,7 @@ If given a prefix, patch in the branch directory instead."
   (let ((found 0)
        (match (concat "^[0-9].*" string)))
     (dolist (file (directory-files-recursively
-                  debbugs-gnu-trunk-directory "ChangeLog\\(.[0-9]+\\)?$"))
+                  debbugs-gnu-current-directory "ChangeLog\\(.[0-9]+\\)?$"))
       (with-temp-buffer
        (when (file-exists-p file)
          (insert-file-contents file))
@@ -1811,11 +1829,7 @@ If given a prefix, patch in the branch directory 
instead."
   (when (get-buffer "*vc-dir*")
     (kill-buffer (get-buffer "*vc-dir*")))
   (let ((patch-subject debbugs-gnu-patch-subject))
-    (let ((trunk (expand-file-name debbugs-gnu-trunk-directory)))
-      (if (equal (cl-subseq default-directory 0 (length trunk))
-                trunk)
-         (vc-dir debbugs-gnu-trunk-directory)
-       (vc-dir debbugs-gnu-branch-directory)))
+    (vc-dir debbugs-gnu-current-directory)
     (goto-char (point-min))
     (while (not (search-forward "edited" nil t))
       (sit-for 0.01))
@@ -1852,4 +1866,87 @@ If given a prefix, patch in the branch directory 
instead."
 
 ;;; TODO:
 
+;; * Extend SOAP interface to get all bugs modified in a given timeframe.
+
+;; * Add debbugs commands to commit messages.
+;;   It'd be nice if the language would be something along the lines of
+;;
+;;   bug#45 done
+;;   bug#45 tags 25.1 fixed
+;;
+;;   That is, that you could drop arbitrary debbugs commands into
+;;   commit messages.
+
+;; * The bug tracker should be aware of repositories, branches,
+;;   commits, contributors, and ticket links or mentions in commit
+;;   messages.
+;;
+;;   For me personally, if I can *see* the specific code that fixes a
+;;   ticket inside the ticket as a commit, and click my way to the
+;;   wider commit and then diff from before that commit against
+;;   today's state of that code, I've built a mental map of the code
+;;   that would otherwise take me a lot of work. That's one common
+;;   workflow. Another is to view several commits that fix a single
+;;   ticket in one place. So it's not revolutionary, just simpler and
+;;   more straightforward for the user.
+;;
+;;   Being able to close a bug just by mentioning it in a certain way
+;;   in the commit message and pushing that commit is also handy. You
+;;   don't have to switch to the bug discussion and duplicate that
+;;   info there manually.
+
+;; * Contributors should be able to tag and notify each other.
+;;
+;;   You mean to (re)assign bugs to particular persons and things like that?
+
+;;   Yes, plus ping someone or a team specifically: "hey, maybe the
+;;   @gnus team should look at this" in a comment.
+
+;; * Markdown should be well supported.
+
+;; * Inline code comments should be easy, and linked to a commit (so
+;;   an updated commit can resolve the comment). This is just the
+;;   essential stuff.
+
+;;   Rebase or amend+force push would update a branch destructively,
+;;   which in a pull request context should show you that a comment
+;;   was for a commit that's no longer in the branch. Furthermore some
+;;   trackers allow you to mark a comment as resolved (e.g. Github
+;;   recently added reactions, which can be used as ad-hoc markup).
+;;
+;;   Even if you don't rebase, but just push a new commit to the
+;;   branch upon review, IIRC both Github and Gitlab can see that the
+;;   changes that started a particular discussion are no longer there
+;;   (and collapse the comment sub-thread a no longer relevant, while
+;;   allowing the user to expand it again if they so wish).
+;;
+;;   I think I'm starting to see what you mean.  You're talking about
+;;   a tight integration where a pull-request is also itself an issue,
+;;   so the comments can be directly on the patch itself.  As opposed
+;;   to having issues and pull-request be two separate things that can
+;;   refer to each other via an indirection.
+;;
+;;   So this is particularly useful/meaningful when reviewing a
+;;   proposed patch from another developer, rather than when
+;;   interacting with an end-user trying to track down some bugs
+;;   here's experiencing (which is the kind of use-case I've had in
+;;   mind when working on BugIt).
+;;
+;;   But indeed, the two use-cases would best be served by the same
+;;   tool since after the bug is tracked a patch might show up to fix
+;;   it, after which a review process will come up.
+;;
+;;   And on the more basic level, compared to flat discussions in
+;;   mailing lists, having separate subthread for each part of the
+;;   patch the reviewer commented on, is great. You can have
+;;   discussion sub-threads in the mailing list too, but people never
+;;   split their emails in pieces that small.
+;;
+;; * The next link in the chain are CI/CD hooks. You can set up a
+;;   Github repo, for instance, to build every pull request before the
+;;   reviewer ever looks, which saves a lot of time with compiled
+;;   languages. It will run tests and so on, but most important is
+;;   that it keeps the context inside the pull request, you don't have
+;;   to go elsewhere.
+
 ;;; debbugs-gnu.el ends here
diff --git a/debbugs-ug.info b/debbugs-ug.info
index 03da162..b4a768c 100644
--- a/debbugs-ug.info
+++ b/debbugs-ug.info
@@ -51,7 +51,7 @@ Org Mode: (org)Top.).  As backend they use the 'debbugs' 
Emacs library
 
 * Retrieving Bugs::             How to retrieve bugs.
 * Searching Bugs::              How to search in the debbugs database.
-* Layout::                      How the results are presented.
+* Presenting Bugs::             How the results are presented.
 * Minor Mode::                  How to use browse bug URLs.
 
 * Command Index::               Debbugs commands.
@@ -125,7 +125,7 @@ prefix.
      customer options 'debbugs-gnu-default-severities' and
      'debbugs-gnu-default-packages'.
 
-     *note Layout:: for the presentation of the results.
+     *note Presenting Bugs:: for the presentation of the results.
 
  -- Command: debbugs-gnu-bugs &rest bugs
  -- Command: debbugs-org-bugs &rest bugs
@@ -134,21 +134,23 @@ prefix.
      specified by their bug number.  Interactively, the bug numbers
      must be entered as comma-separated list.
 
-     *note Layout:: for the presentation of the results.
+     *note Presenting Bugs:: for the presentation of the results.
 
  -- Command: debbugs-gnu-patches
  -- Command: debbugs-org-patches
 
      The commands 'debbugs-gnu-patches' and 'debbugs-org-patches' show
-     all bugs tagged with '"patch"'.  This is useful for bug triages.
+     all unarchived bugs of the packages declared in
+     'debbugs-gnu-default-packages', and tagged with '"patch"'.  This
+     is useful for bug triages.
 
-     *note Layout:: for the presentation of the results.
+     *note Presenting Bugs:: for the presentation of the results.
 
 
-File: debbugs-ug.info,  Node: Searching Bugs,  Next: Layout,  Prev: Retrieving 
Bugs,  Up: Top
+File: debbugs-ug.info,  Node: Searching Bugs,  Next: Presenting Bugs,  Prev: 
Retrieving Bugs,  Up: Top
 
-2 Searching in the Debbugs Database.
-************************************
+2 Searching in the Debbugs Database
+***********************************
 
 The GNU Debbugs server allows text search in the database in the
 messages submitted to the bugs.  It uses a HyperEstraier based search
@@ -271,10 +273,10 @@ Debbugs server only.
 are not supported.
 
 
-File: debbugs-ug.info,  Node: Layout,  Next: Minor Mode,  Prev: Searching 
Bugs,  Up: Top
+File: debbugs-ug.info,  Node: Presenting Bugs,  Next: Minor Mode,  Prev: 
Searching Bugs,  Up: Top
 
-3 Layout
-********
+3 Presenting Bugs
+*****************
 
 The commands described in the previous chapters generate (a) report
 buffer(s) applicable for navigation.  'debbugs-gnu-*' return a
@@ -286,9 +288,10 @@ tabulated list, and 'debbugs-org-*' return a list of TODO 
items in
 * Tabulated Lists::             Tabulated Lists.
 * TODO Items::                  TODO Items.
 * Control Messages::            Control Messages.
+* Applying Patches::            Applying Patches in the Emacs Repository.
 
 
-File: debbugs-ug.info,  Node: Tabulated Lists,  Next: TODO Items,  Up: Layout
+File: debbugs-ug.info,  Node: Tabulated Lists,  Next: TODO Items,  Up: 
Presenting Bugs
 
 3.1 Tabulated Lists
 ===================
@@ -325,11 +328,16 @@ This enables the following key strokes:
                
 '/'            'debbugs-gnu-narrow-to-status'
                Narrow the list of bugs to the bugs that match the
-               given regex in 'State', 'Submitter' or 'Title'.
+               given regex in 'State', 'Submitter' or 'Title'.  With
+               a prefix argument 'C-u', the list of bugs is narrowed
+               to a match in 'State' only.
                
 'R'            'debbugs-gnu-show-all-blocking-reports'
                Narrow the list of bug reports to the ones that are
-               blocking the current release.
+               blocking the current Emacs release, as specified in
+               'debbugs-gnu-emacs-current-release'.  With a prefix
+               argument 'C-u', the current Emacs release is read from
+               the minibuffer.
                
 'w'            'debbugs-gnu-widen'
                Restore the full list again after narrowing.
@@ -368,7 +376,7 @@ GNUS ephemeral group for that bug will be shown; if its 
value is
 'rmail', the command will present an Rmail folder instead.
 
 
-File: debbugs-ug.info,  Node: TODO Items,  Next: Control Messages,  Prev: 
Tabulated Lists,  Up: Layout
+File: debbugs-ug.info,  Node: TODO Items,  Next: Control Messages,  Prev: 
Tabulated Lists,  Up: Presenting Bugs
 
 3.2 TODO Items
 ==============
@@ -400,7 +408,7 @@ This enables the following key strokes:
 'Messages' which opens a GNUS ephemeral group for that bug.
 
 
-File: debbugs-ug.info,  Node: Control Messages,  Prev: TODO Items,  Up: Layout
+File: debbugs-ug.info,  Node: Control Messages,  Next: Applying Patches,  
Prev: TODO Items,  Up: Presenting Bugs
 
 3.3 Control Messages
 ====================
@@ -514,7 +522,36 @@ be inconvenient, for example when an external interactive 
mail client
 is configured.
 
 
-File: debbugs-ug.info,  Node: Minor Mode,  Next: Command Index,  Prev: Layout, 
 Up: Top
+File: debbugs-ug.info,  Node: Applying Patches,  Prev: Control Messages,  Up: 
Presenting Bugs
+
+3.4 Applying Patches in the Emacs Repository
+============================================
+
+Several bugs carry a proposed patch in one of their messages.
+Usually, those bugs are marked with the with '"patch"' tag.  *note
+Retrieving Bugs:: how to show such bugs.
+
+   If a GNUS ephemeral group for such a bug is opened, it is possible
+to apply the patch directly to the Emacs repository.  Move the cursor
+to the message containing a patch, and hit 'M-m'.  It determines
+whether one or several patches are in the MIME attachments or just
+included in the message, applies them, runs 'make -k' in the 'lisp'
+subdirectory, and shows a '*vc-dir*' buffer of the Emacs repository
+with the changed file(s).
+
+   The Emacs repository is determined via the variables
+'debbugs-gnu-trunk-directory' or 'debbugs-gnu-branch-directory'.  The
+latter one is used, when the patch is applied with the prefixed
+command 'C-u M-m'.  If the predefined directory does not point to an
+existing path, it is read from the minibuffer.
+
+   A further 'M-m' in the corresponding '*vc-diff*' buffer opens the
+modified file.  Here you can apply 'M-m' the next time.  This creates
+a ChangeLog entry with all needed information.  A final 'M-m' in the
+'ChangeLog' buffer commits the patch via '*vc-log*'.
+
+
+File: debbugs-ug.info,  Node: Minor Mode,  Next: Command Index,  Prev: 
Presenting Bugs,  Up: Top
 
 4 Minor Mode
 ************
@@ -564,14 +601,18 @@ Variable Index
 [index]
 * Menu:
 
-* debbugs-browse-function:               Minor Mode.         (line 12)
-* debbugs-gnu-all-packages:              Retrieving Bugs.    (line 36)
-* debbugs-gnu-all-severities:            Retrieving Bugs.    (line 27)
-* debbugs-gnu-default-packages:          Retrieving Bugs.    (line 63)
-* debbugs-gnu-default-severities:        Retrieving Bugs.    (line 63)
-* debbugs-gnu-default-suppress-bugs:     Retrieving Bugs.    (line 44)
-* debbugs-gnu-mail-backend:              Tabulated Lists.    (line 74)
-* debbugs-gnu-suppress-closed:           Tabulated Lists.    (line 71)
+* debbugs-browse-function:               Minor Mode.        (line  12)
+* debbugs-gnu-all-packages:              Retrieving Bugs.   (line  36)
+* debbugs-gnu-all-severities:            Retrieving Bugs.   (line  27)
+* debbugs-gnu-branch-directory:          Applying Patches.  (line  18)
+* debbugs-gnu-default-packages:          Retrieving Bugs.   (line  63)
+* debbugs-gnu-default-severities:        Retrieving Bugs.   (line  63)
+* debbugs-gnu-default-suppress-bugs:     Retrieving Bugs.   (line  44)
+* debbugs-gnu-mail-backend:              Tabulated Lists.   (line  79)
+* debbugs-gnu-send-mail-function:        Control Messages.  (line 108)
+* debbugs-gnu-suppress-closed:           Tabulated Lists.   (line  76)
+* debbugs-gnu-trunk-directory:           Applying Patches.  (line  18)
+* debbugs-org-severity-priority:         TODO Items.        (line  10)
 
 
 File: debbugs-ug.info,  Node: Key Index,  Prev: Variable Index,  Up: Top
@@ -583,39 +624,42 @@ Key Index
 * Menu:
 
 * /:                                     Tabulated Lists.    (line 36)
-* B:                                     Tabulated Lists.    (line 52)
-* b:                                     Tabulated Lists.    (line 53)
-* C:                                     Tabulated Lists.    (line 66)
+* B:                                     Tabulated Lists.    (line 57)
+* b:                                     Tabulated Lists.    (line 58)
+* C:                                     Tabulated Lists.    (line 71)
 * C-c # C:                               TODO Items.         (line 25)
 * C-c # d:                               TODO Items.         (line 19)
 * C-c # t:                               TODO Items.         (line 22)
 * d:                                     Tabulated Lists.    (line 33)
-* g:                                     Tabulated Lists.    (line 47)
+* g:                                     Tabulated Lists.    (line 52)
+* M-m:                                   Applying Patches.   (line 10)
 * <mouse-1>:                             Tabulated Lists.    (line 30)
 * <mouse-2>:                             Tabulated Lists.    (line 31)
-* R:                                     Tabulated Lists.    (line 40)
+* R:                                     Tabulated Lists.    (line 42)
 * <RET>:                                 Tabulated Lists.    (line 29)
-* s:                                     Tabulated Lists.    (line 57)
-* t:                                     Tabulated Lists.    (line 60)
+* <RET> <1>:                             Tabulated Lists.    (line 79)
+* s:                                     Tabulated Lists.    (line 62)
+* t:                                     Tabulated Lists.    (line 65)
 * <TAB>:                                 TODO Items.         (line 16)
-* w:                                     Tabulated Lists.    (line 44)
-* x:                                     Tabulated Lists.    (line 63)
+* w:                                     Tabulated Lists.    (line 49)
+* x:                                     Tabulated Lists.    (line 68)
 
 
 
 Tag Table:
 Node: Top1097
 Node: Retrieving Bugs2635
-Node: Searching Bugs6362
-Ref: Searching Bugs-Footnote-110508
-Ref: Searching Bugs-Footnote-210596
-Node: Layout10687
-Node: Tabulated Lists11162
-Node: TODO Items14520
-Node: Control Messages15567
-Node: Minor Mode18399
-Node: Command Index19338
-Node: Variable Index20127
-Node: Key Index20846
+Node: Searching Bugs6474
+Ref: Searching Bugs-Footnote-110627
+Ref: Searching Bugs-Footnote-210715
+Node: Presenting Bugs10806
+Node: Tabulated Lists11382
+Node: TODO Items15057
+Node: Control Messages16113
+Node: Applying Patches18979
+Node: Minor Mode20342
+Node: Command Index21290
+Node: Variable Index22079
+Node: Key Index23082
 
 End Tag Table
diff --git a/debbugs-ug.texi b/debbugs-ug.texi
index d931c01..6d06ae7 100644
--- a/debbugs-ug.texi
+++ b/debbugs-ug.texi
@@ -62,7 +62,7 @@ Programmer's Manual, debbugs}).
 @menu
 * Retrieving Bugs::             How to retrieve bugs.
 * Searching Bugs::              How to search in the debbugs database.
-* Layout::                      How the results are presented.
+* Presenting Bugs::             How the results are presented.
 * Minor Mode::                  How to use browse bug URLs.
 
 * Command Index::               Debbugs commands.
@@ -139,7 +139,7 @@ Default values for interactive use could be configured in 
the customer
 options @code{debbugs-gnu-default-severities} and
 @code{debbugs-gnu-default-packages}.
 
-@ref{Layout} for the presentation of the results.
+@ref{Presenting Bugs} for the presentation of the results.
 
 @end deffn
 
@@ -151,7 +151,7 @@ The commands @code{debbugs-gnu-bugs} and 
@code{debbugs-org-bugs} show
 bugs specified by their bug number.  Interactively, the bug numbers
 must be entered as comma-separated list.
 
-@ref{Layout} for the presentation of the results.
+@ref{Presenting Bugs} for the presentation of the results.
 
 @end deffn
 
@@ -159,16 +159,18 @@ must be entered as comma-separated list.
 @deffn  {Command} debbugs-gnu-patches
 @deffnx {Command} debbugs-org-patches
 
-The commands @code{debbugs-gnu-patches} and @code{debbugs-org-patches} show
-all bugs tagged with @code{"patch"}.  This is useful for bug triages.
+The commands @code{debbugs-gnu-patches} and @code{debbugs-org-patches}
+show all unarchived bugs of the packages declared in
+@code{debbugs-gnu-default-packages}, and tagged with @code{"patch"}.
+This is useful for bug triages.
 
-@ref{Layout} for the presentation of the results.
+@ref{Presenting Bugs} for the presentation of the results.
 
 @end deffn
 
 
 @node Searching Bugs
-@chapter Searching in the Debbugs Database.
+@chapter Searching in the Debbugs Database
 
 The GNU Debbugs server allows text search in the database in the
 messages submitted to the bugs.  It uses a
@@ -283,8 +285,8 @@ applied only after all bugs have been downloaded.
 @end deffn
 
 
-@node Layout
-@chapter Layout
+@node Presenting Bugs
+@chapter Presenting Bugs
 
 The commands described in the previous chapters generate (a) report
 buffer(s) applicable for navigation.  @code{debbugs-gnu-*} return a
@@ -295,6 +297,7 @@ in @code{org-mode}.
 * Tabulated Lists::             Tabulated Lists.
 * TODO Items::                  TODO Items.
 * Control Messages::            Control Messages.
+* Applying Patches::            Applying Patches in the Emacs Repository.
 @end menu
 
 
@@ -348,14 +351,18 @@ Show all bug attributes.
 @kbd{/} @tab
 @code{debbugs-gnu-narrow-to-status} @*
 Narrow the list of bugs to the bugs that match the given regex in
-@code{State}, @code{Submitter} or @code{Title}.
+@code{State}, @code{Submitter} or @code{Title}.  With a prefix
+argument @kbd{C-u}, the list of bugs is narrowed to a match in
+@code{State} only.
 
 @item
 @kindex @kbd{R}
 @kbd{R} @tab
 @code{debbugs-gnu-show-all-blocking-reports} @*
 Narrow the list of bug reports to the ones that are blocking the
-current release.
+current Emacs release, as specified in
+`debbugs-gnu-emacs-current-release'.  With a prefix argument
+@kbd{C-u}, the current Emacs release is read from the minibuffer.
 
 @item
 @kindex @kbd{w}
@@ -411,6 +418,7 @@ The user option @code{debbugs-gnu-suppress-closed} 
controls, whether
 closed bugs are shown in the initial list.
 
 @vindex debbugs-gnu-mail-backend
+@kindex @kbd{@key{RET}}
 The user option @code{debbugs-gnu-mail-backend} controls the
 presentation of email messages produced by typing @kbd{@key{RET}} or
 by clicking the mouse on a bug: if its value is @code{gnus}, the
@@ -426,6 +434,7 @@ TODO items are offered as usual in @code{org-mode}.  The bug
 attributes are mapped onto properties of these items.  They can be
 shown by the usual navigation in @code{org-mode}.
 
+@vindex debbugs-org-severity-priority
 Bug severities are mapped onto org severities, see
 @code{debbugs-org-severity-priority}.
 
@@ -571,6 +580,7 @@ The username, read interactively, is either a package name 
or an email
 address.  The tag to be set is also read interactively.
 @end table
 
+@vindex debbugs-gnu-send-mail-function
 How the control messages are sent is controlled by the
 @code{debbugs-gnu-send-mail-function} variable.  If it is @code{nil}
 (the default value), the value of @code{send-mail-function} is used.
@@ -578,6 +588,38 @@ This could be inconvenient, for example when an external 
interactive
 mail client is configured.
 
 
+@node Applying Patches
+@section Applying Patches in the Emacs Repository
+
+Several bugs carry a proposed patch in one of their messages.
+Usually, those bugs are marked with the with @code{"patch"} tag.
+@ref{Retrieving Bugs} how to show such bugs.
+
+@kindex @kbd{M-m}
+If a GNUS ephemeral group for such a bug is opened, it is possible to
+apply the patch directly to the Emacs repository.  Move the cursor to
+the message containing a patch, and hit @kbd{M-m}.  It determines
+whether one or several patches are in the MIME attachments or just
+included in the message, applies them, runs @command{make -k} in the
+@file{lisp} subdirectory, and shows a @samp{*vc-dir*} buffer of the
+Emacs repository with the changed file(s).
+
+@vindex debbugs-gnu-trunk-directory
+@vindex debbugs-gnu-branch-directory
+The Emacs repository is determined via the variables
+@code{debbugs-gnu-trunk-directory} or
+@code{debbugs-gnu-branch-directory}.  The latter one is used, when the
+patch is applied with the prefixed command @kbd{C-u M-m}.  If the
+predefined directory does not point to an existing path, it is read
+from the minibuffer.
+
+A further @kbd{M-m} in the corresponding @samp{*vc-diff*} buffer opens
+the modified file.  Here you can apply @kbd{M-m} the next time.  This
+creates a ChangeLog entry with all needed information.  A final
+@kbd{M-m} in the @samp{ChangeLog} buffer commits the patch via
+@samp{*vc-log*}.
+
+
 @node Minor Mode
 @chapter Minor Mode
 
diff --git a/debbugs.el b/debbugs.el
index 3aa6cfd..d31f355 100644
--- a/debbugs.el
+++ b/debbugs.el
@@ -606,8 +606,8 @@ The following conditions are possible:
   :subject, :@title -- The subject of a message or the title of
   the bug, a string.
 
-  :date, :@cdate -- The submission or modification dates of a
-  message, a number.
+  :date, :@cdate -- The submission date of the bug or the
+  modification date of a message, a number.
 
   :@author -- The email address of the author of a message
   belonging to this bug, a string.  It may be different than