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

[(]

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

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 4b1eed1cb1..c7a2dd09e7 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1409,19 +1409,78 @@ git config --local sendemail.thread no
 @anchor{Sending a Patch Series}
 @cindex patch series
 @cindex @code{git send-email}
+The @code{git send-email} and @code{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
+@code{git format-patch --cover-letter}.
 
-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
-
-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}).
+@example
+$ git format-patch -$N -o outgoing --cover-letter
+@end example
+
+@quotation Note
+The @code{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 @code{.patch} files in @code{outgoing/}, along with an automatically
+generated cover letter.  We can then send the cover letter to the Guix
+mailing list.
+
+@example
+$ git send-email outgoing/0000-cover-letter.patch -a --to guix-patches@@gnu.org
+@end example
+
+Note the @code{-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.
+
+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 @code{@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
+@code{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
+
+The use of the @code{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.
+
+To incorporate a reviewer's suggestions, use @code{git rebase -i} to amend
+the commits, as demonstrated @url{https://git-rebase.io, here}, and send a
+second patch series with a @code{-v2} tag.
+
+@example
+$ git send-email -$N -v2 --to ISSUE_NUMBER@@debbugs.gnu.org
+@end example
+
+Note that since we already have an issue on Debbugs for our patchset,
+there's no need for the intermediate @code{git format-patch} step. Of
+course, to send a third patchset, you amy use @code{-v3}, to send a fourth,
+@code{-v4}, and so on.
+
+If need be, you may use @code{--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}
-- 
2.38.0