bug#35362: 26.2; [debbugs.el] Automate commit -> debbugs flow (posting patches, closing bugs after pushing)

[Noam Postavsky]

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

> All your defcustoms miss a :version tag. I guess, "27.1" is proper.

Oh, hmm.  Shouldn't the version correspond to the debbugs.el package
version, since it's not tied to the Emacs version as such?

>>    ;; Use Gnus.
>>    (gnus-read-ephemeral-emacs-bug-group
>>     (cons id (if (listp merged) merged (list merged)))
>> +   This doesn't work, gives wrong-type-argument listp when quitting.
>
> Comment chars are missing. Leftover from editing?

Sorry, this hunk was supposed to be dropped completely.

>> +(defun debbugs-gnus-jump-to-bug (bugid)
>> +  "Display buffer associated with BUGID with `pop-to-buffer'.
>> +Use `gnus-read-ephemeral-emacs-bug-group' instead if there is no such 
>> buffer."
>
> debbugs-gnu.el supports both gnus and rmail. Do we miss something for
> rmail then?
>
> (I'm not an rmail user, but Eli is.)

Possibly yes, I haven't used rmail so I'm not sure how to test that out.

>> +(defun debbugs-gnu--git-insert (&rest args)
>> +  "Insert output of running git with ARGS.
>> +Throws error if git returns non-zero.  Uses `debbugs-gnu-git-program'."
>> +  (unless (eql 0 (apply #'process-file
>> +                        debbugs-gnu-git-program nil '(t t) nil
>> +                        args))
>> +    (error "git %s failed: %s" (car args) (buffer-string))))
>
> Why not `vc-git--call'?

I thought relying on a function marked as internal would not be a good
idea for an ELPA package which should potentially work across multiple
versions of Emacs.  Otherwise vc-git--call should work fine too.

>> +    (debbugs-gnu--git-insert "remote" "-v")
>
>> +            (debbugs-gnu--git-insert
>> +             ;; %H: commit hash.
>> +             "log" "-1" "--format=%H" commit-range)
>
>> +        (apply
>> +         #'debbugs-gnu--git-insert
>> +         "branch" "--remote" "--contains" last-commit
>> +         (mapcar (lambda (glob) (concat remote glob))
>> +                 ref-globs))
>
>> +    (debbugs-gnu--git-insert
>> +     "show" "--no-patch"
>> +     (concat "--format=" debbugs-gnu-commit-description-format
>> +             "\n" (cdr (assq 'commit-url remote-info)) "\n")
>> +     commit-range)
>
>
>> +      (apply #'debbugs-gnu--git-insert
>> +             "format-patch" (concat "--output-directory=" dir)
>> +             (append format-patch-args
>> +                     (list commit-range))))
>
>> +      (debbugs-gnu--git-insert
>> +       ;; %B: raw body (unwrapped subject and body).
>> +       "show" "--no-patch" "--format=%B" commit-range)
>
> Aren't there respective vc-git functions we could reuse?

No, I don't see any.

>> +@node Posting Patches
>> +@section Posting Patches to Debbugs from the Emacs Repository
>> +
>> +Once you have committed a patch fixing a bug you usually want to post
>> +it to the bug thread for review and testing.  And when the patch is
>> +deemed satisfactory and pushed to the official GNU Emacs repository,
>> +the bug should be marked closed.
>
> Currently, you are supporting both Emacs and ELPA repositories, aren't
> you? Please sday so.

Yes.

>> +@findex debbugs-gnu-pick-commits
>> +The command @code{debbugs-gnu-pick-commits} helps automate both these
[...]
> Reading this doesn't give me a clear picture what happens. Could you add
> an example?
>
> Also, pls describe at least `debbugs-gnu-git-remote-info-alist'. Other
> projects but Emacs might profit from.

Okay, I've expanded the manual section (inlined below) maybe it gives
you a more clear picture (or maybe a less clear one :/).

@node Posting Patches
@section Posting Patches to Debbugs from the Emacs Repository

Once you have committed a patch fixing a bug you usually want to post
it to the bug thread for review and testing.  And when the patch is
deemed satisfactory and pushed to the official repository, the bug
should be marked closed.

@findex debbugs-gnu-pick-commits
The command @code{debbugs-gnu-pick-commits} helps automate both these
processes: it queries for a commit (or commit range), and a bug number
(defaulting to the bug number mentioned in the commit message).  It
then jumps you to a buffer associated with the bug.  When you reply to
a message in the bug thread, you are asked whether to post the commits
as patches (optionally tagging the bug with @code{"patch"}), or
announce that the bug has been fixed by the selected commits
(optionally closing the bug and marking as closed in the Emacs version
corresponding to the patch).

For example, suppose you are reading the message of ``Bug#1234:
foo-mode fails to call frobnicate on startup'' in a message buffer.
You decide to fix it, so you switch to the source code, add in the
missing call and commit locally, with the commit message ``*
lisp/foo-mode.el (foo-mode): Call frobnicate (Bug#1234).''  Use
@kbd{C-x v l} to run @code{vc-print-log}, and navigate to the new
commit.  Invoke the command @code{debbugs-gnu-pick-commits} and press
@kbd{RET} to accept the default bug number (which will be 1234 since
it's in the commit message) in response to the prompt.  You are then
popped to the message buffer, and when you reply to the message, press
@kbd{p} to post the git formatted patch as an attachment for review,
and then answer @kbd{y} to tag the bug with @code{"patch"} when the
message is sent.  Assuming you get favorable reviews, you then push
it, and again call @code{debbugs-gnu-pick-commits} but this time press
@kbd{a} (for ``announce'') after replying to the relevant bug thread
message.  This will insert some text describing the commit and where
it was pushed to, and answering @kbd{y} will arrange for the bug to be
closed when the message is sent.

@node Customizing debbugs-gnu-pick-commits
@subsection Customizing debbugs-gnu-pick-commits

@vindex debbugs-gnu-read-commit-range-hook
The query for commit (or commit range) to use is controlled by
@code{debbugs-gnu-read-commit-range-hook}.  Initially it has an entry
which operates in @samp{*vc-change-log*} buffers: the default will be
the commit under point, or the commit range contained in the region if
it is active.

@vindex debbugs-gnu-commit-description-format
@vindex debbugs-gnu-git-remote-info-alist
The string inserted to describe an announced commit is controlled by
the variable @code{debbugs-gnu-commit-description-format}, it is a
format string passed to the @code{--format} argument of @code{git
show}.  Additionally, if the remote url matches an entry in
@code{debbugs-gnu-git-remote-info-alist}, then its @code{commit-url}
subitem is appended to the commit description.  By default this
variable is configured for the GNU Emacs and GNU ELPA repositories.