[bug#58648] [PATCH v2] doc: contributing: Expand "Sending a Patch Series".

["\( via Guix-patches" via <guix-patches@gnu.org>]

* doc/contributing.texi: Expand on sending patches and using
  git send-email.
---
 doc/contributing.texi | 120 ++++++++++++++++++++++++++++++------------
 1 file changed, 86 insertions(+), 34 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 4b1eed1cb1..650d3430fb 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1149,15 +1149,6 @@ Before submitting a patch that adds or modifies a package definition,
 please run through this check list:
 
 @enumerate
-@cindex @code{git format-patch}
-@cindex @code{git-format-patch}
-@item
-When generating your patches with @code{git format-patch} or @code{git
-send-email}, we recommend using the option @code{--base=}, perhaps with
-the value @code{auto}.  This option adds a note to the patch stating
-which commit the patch is based on.  This helps reviewers understand how
-to apply and review your patches.
-
 @item
 If the authors of the packaged software provide a cryptographic
 signature for the release tarball, make an effort to verify the
@@ -1343,18 +1334,6 @@ a subject, if your patch is to be applied on a branch other than
 @code{master}, say @code{core-updates}, specify it in the subject like
 @samp{[PATCH core-updates] @dots{}}.
 
-@quotation Tip
-To add a prefix to the subject of your patch, you may use the
-@option{--subject-prefix} option of the @command{git format-patch} or
-@command{git send-email} commands, for example:
-@example
-git send-email --subject-prefix='PATCH core-updates' \
-  --to=guix-patches@@gnu.org -1
-@end example
-For more information, run @samp{man git-format-patch} and @samp{man
-git-send-email}.
-@end quotation
-
 You may use your email client or the @command{git send-email} command
 (@pxref{Sending a Patch Series}).  We prefer to get patches in plain
 text messages, either inline or as MIME attachments.  You are advised to
@@ -1409,19 +1388,92 @@ git config --local sendemail.thread no
 @anchor{Sending a Patch Series}
 @cindex patch series
 @cindex @code{git send-email}
+The @command{git send-email} and @command{git format-patch} commands allow
+you to send your commits in email form to a mailing list, to be reviewed
+and applied, and they are the recommended way to submit contributions to
+Guix. When you send the first revision of a patch series, it's best to use
+@command{git format-patch --cover-letter}.
+
+@example
+$ git format-patch -$N -o outgoing --cover-letter --base=HEAD~$N
+@end example
+
+@quotation Note
+The @command{git send-email} command is provided by the @code{send-email}
+output of the @code{git} package, i.e. @code{git:send-email}.
+@end quotation
+
+This command makes patches out of the last @var{N} commits, and writes
+them to @file{*.patch} files in @file{outgoing/}, along with an
+automatically generated cover letter.  The @option{--base=HEAD~$N} option
+adds @code{base-commit: @var{COMMIT}} to the bottom of the first email.
+
+We can now send the cover letter to the Guix mailing list, using
+@command{git send-email}.
+
+@example
+$ git send-email outgoing/0000-cover-letter.patch -a --to guix-patches@@gnu.org
+@end example
+
+Note the @option{-a} flag; this pops up your editor so that you can fill
+in the patchset subject line and blurb with whatever explanatory text you
+feel is appropriate.  Note the automatically generated shortlog and
+diffstat below the blurb, which help to give potential reviewers an
+overview of the patchset.
+
+@quotation Tip
+To add a prefix to the subject of your patch, you may use the
+@option{--subject-prefix} option.
+
+@example
+git format-patch -$N -o outgoing \
+    --subject-prefix='PATCH core-updates' \
+    --base=auto --cover-letter
+@end example
+@end quotation
+
+The use of the @file{etc/teams.scm} script to notify the appropriate team
+members (@pxref{Teams}) is recommended when submitting patches, to maximize
+the chances of your patch series being reviewed quickly.
+
+At some point, the Debbugs mailer will reply to your cover letter mail
+with an acknowledgement, which contains the issue number of your patchset.
+You should now send the rest of the patches to this issue thread, using
+the @email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address.
+
+@example
+$ rm outgoing/0000-cover-letter.patch # Don't resend the cover letter!
+$ git send-email outgoing/*.patch --to ISSUE_NUMBER@@debbugs.gnu.org
+$ rm -rf outgoing # We're done with the patch files now.
+@end example
+
+After a moment, your patches should appear at
+@url{https://issues.guix.gnu.org/@var{ISSUE_NUMBER}} and
+@url{https://debbugs.gnu.org/@var{ISSUE_NUMBER}}.
+
+@quotation Note
+You should @strong{never} send all your patches to
+@email{guix-patches@@gnu.org} at once, as this will create an issue for
+each individual patch you send!  If you do accidentally do this, though,
+it's not a massive problem, as Debbugs supports merging issues.
+@end quotation
+
+To incorporate a reviewer's suggestions, use @command{git rebase -i} to
+amendthe commits, as demonstrated @url{https://git-rebase.io, here}, and
+send a second patch series with a @option{-v2} tag.
+
+@example
+$ git send-email -$N -v2 --base=auto --to ISSUE_NUMBER@@debbugs.gnu.org
+@end example
 
-When sending a patch series (e.g., using @code{git send-email}), please
-first send one message to @email{guix-patches@@gnu.org}, and then send
-subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
-they are kept together.  See
-@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
-for more information.  You can install @command{git send-email} with
-@command{guix install git:send-email}.
-@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
+Note that since we already have an issue on Debbugs for our patchset,
+there's no need for the intermediate @command{git format-patch} step. Of
+course, to send a third patchset, you amy use @option{-v3}, to send a
+fourth, @option{-v4}, and so on.
 
-To maximize the chances that you patch series is reviewed, the preferred
-submission way is to use the @code{etc/teams.scm} script to notify the
-appropriate team members (@pxref{Teams}).
+If need be, you may use @option{--cover-letter -a} to send another cover
+letter, e.g. for explaining what's changed since the last revision, and
+these changes are necessary.
 
 @unnumberedsubsec Teams
 @anchor{Teams}
@@ -1448,7 +1500,7 @@ You can run the following command to have the @code{Mentors} team put in
 CC of a patch series:
 
 @example
-$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
+$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
 @end example
 
 The appropriate team or teams can also be inferred from the modified
@@ -1457,7 +1509,7 @@ current Git repository to review, you can run:
 
 @example
 $ guix shell -D guix
-[env]$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
+[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
 @end example
 
 @node Tracking Bugs and Patches

base-commit: 88746cd80bc56212ae7922c0fa1cd9a18e44c3bb
-- 
2.38.0