Subject: [bug#68414] [PATCH v1] doc: Improve documentation for submitting patches

From: Ale Abdo <[email-masked]>
Date: Wed, 21 Feb 2024 23:05:11 +0100

Change-Id: Ice47f1f4a54bf930bdff94b6a1e47ce84e8fabc7
---
 doc/contributing.texi | 273 +++++++++++++++++++++++-------------------
 doc/guix.texi         |   4 +-
 2 files changed, 155 insertions(+), 122 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index a7d91724fb..6e08d381d4 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1376,23 +1376,25 @@ Formatting Code
 
 @node Submitting Patches
 @section Submitting Patches
+@cindex patch submission
 
-Development is done using the Git distributed version control system.
-Thus, access to the repository is not strictly necessary.  We welcome
-contributions in the form of patches as produced by @code{git
-format-patch} sent to the @email{guix-patches@@gnu.org} mailing list
+Guix is developed using the Git distributed version control system.  Special
+access to the official repository is not necessary in order to contribute.  We
+welcome contributions in the form of patches, as produced by @code{git
+format-patch}, sent to the @email{guix-patches@@gnu.org} mailing list
 (@pxref{Submitting patches to a project,,, git, Git User Manual}).
-Contributors are encouraged to take a moment to set some Git repository
-options (@pxref{Configuring Git}) first, which can improve the
-readability of patches.  Seasoned Guix developers may also want to look
-at the section on commit access (@pxref{Commit Access}).
-
-This mailing list is backed by a Debbugs instance, which allows us to
-keep track of submissions (@pxref{Tracking Bugs and Changes}).
-Each message sent to that mailing list gets a new tracking number
-assigned; people can then follow up on the submission by sending email
-to @code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER}
-is the tracking number (@pxref{Sending a Patch Series}).
+
+Contributors are encouraged to take a moment to set some Git repository options
+(@pxref{Configuring Git}) first, which can improve the readability of patches.
+Seasoned Guix developers may also want to look at the section on commit access
+(@pxref{Commit Access}).
+
+The @email{guix-patches@@gnu.org} mailing list is backed by a Debbugs instance,
+which allows us to keep track of submissions (@pxref{Tracking Bugs and
+Changes}).  Each message sent to that mailing list gets a new tracking number
+assigned; people can then follow up on the submission by sending email to
+@code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} is the
+tracking number (@pxref{Sending a Patch Series}).
 
 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
 standards, GNU Coding Standards}); you can check the commit history for
@@ -1408,6 +1410,10 @@ Submitting Patches
 what questions a reviewer will ask, and answer those questions in
 advance.
 
+
+@node Patch quality
+@subsection Patch quality
+
 Before submitting a patch that adds or modifies a package definition,
 please run through this check list:
 
@@ -1553,36 +1559,11 @@ Submitting Patches
 
 @end enumerate
 
-When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
-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{}}.
-
-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
-pay attention if your email client changes anything like line breaks or
-indentation which could potentially break the patches.
-
-Expect some delay when you submit your very first patch to
-@email{guix-patches@@gnu.org}. You have to wait until you get an
-acknowledgement with the assigned tracking number. Future acknowledgements
-should not be delayed.
-
-When a bug is resolved, please close the thread by sending an email to
-@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}.
-
-@menu
-* Configuring Git::
-* Sending a Patch Series::
-* Teams::
-@end menu
 
 @node Configuring Git
 @subsection Configuring Git
 @cindex git configuration
-@cindex @code{git format-patch}
-@cindex @code{git send-email}
+@cindex @code{git config}
 
 If you have not done so already, you may wish to set a name and email
 that will be associated with your commits (@pxref{telling git your name,
@@ -1602,35 +1583,82 @@ Configuring Git
 @file{commit-msg} hook of your own you would like to use with Guix, you
 can place it under the @file{.git/hooks/commit-msg.d/} directory.
 
+
+@node Posting a patch
+@subsection Posting a patch
+@cindex @code{git format-patch}
+
+When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as a
+subject.  In case 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{}}.
+
+You may use the @command{git send-email} command or your email client to post a
+patch.
+
+Using @command{git send-email} has several advantages, such as automatically
+CC'ing the appropriate teams, avoiding formatting issues, being
+@url{https://git-scm.com/docs/git-send-email#_examples, easy to configure}, and
+convenient to use. Usage is often as simple as @command{git send-email -1} to
+post a single commit.  @xref{Sending a Patch Series} for further details.
+
+Should you still prefer to use your email client, make sure to send patches
+produced by @command{git format-patch} as MIME attachments in plain text
+messages.  For a series with multiple patches, it is possible to send them as
+multiple attachments in a single message.  Beware that multi-attachment messages
+will not display correctly on the @url{https://issues.guix.gnu.org, Guix issue
+tracker}, though they will work fine with Debbugs.  Finally, should you want to
+notify a team to review your patch, you'll have to figure out the appropriate
+members and CC them manually (@pxref{Teams}).
+
+Expect some delay when you submit your very first patch to
+@email{guix-patches@@gnu.org}.  You have to wait until you get an
+acknowledgement with the assigned tracking number.  Future acknowledgements
+should not be delayed.
+
+When a bug is resolved, please close the thread by sending an email to
+@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}.
+
+
 @node Sending a Patch Series
 @subsection Sending a Patch Series
 @cindex patch series
 @cindex @code{git send-email}
 @cindex @code{git format-patch}
 
-@unnumberedsubsubsec Single Patches
-@anchor{Single Patches}
-The @command{git send-email} command is the best way to send both single
-patches and patch series (@pxref{Multiple Patches}) to the Guix mailing
-list.  Sending patches as email attachments may make them difficult to
-review in some mail clients, and @command{git diff} does not store commit
-metadata.
+The @command{git send-email} command is the best way to send both single patches
+and patch series to the Guix mailing list.
 
 @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}.
+The @command{git send-email} command is provided by the @code{send-email} output
+of the @code{git} package.  You may install it with @code{guix install
+git:send-email}, and see @url{https://git-scm.com/docs/git-send-email#_examples,
+its documentation} for an example configuration.
 @end quotation
 
-The following command will create a patch email from the latest commit,
-open it in your @var{EDITOR} or @var{VISUAL} for editing, and send it to
-the Guix mailing list to be reviewed and merged.  Assuming you have
-already configured Git according to @xref{Configuring Git}, you can
-simply use:
+@unnumberedsubsubsec Single Commit Patches
+@anchor{Single Commit Patches}
+
+Once you have configured Git (@pxref{Configuring Git}) and @command{git
+send-email}, you can use the following command to create a patch email from the
+latest commit and send it to the Guix mailing list to be reviewed and merged.
+
+@example
+$ git send-email -1
+@end example
+
+If you wish to review the patch before sending, adding the @option{--annotate}
+option will open the patch in your @var{EDITOR} or @var{VISUAL} for editing
+before it gets sent.
 
 @example
 $ git send-email --annotate -1
 @end example
 
+The patch email contains a three-dash separator line after the commit
+message.  You may ``annotate'' the patch with explanatory text by adding
+it under this line.
+
 @quotation Tip
 To add a prefix to the subject of your patch, you may use the
 @option{--subject-prefix} option.  The Guix project uses this to
@@ -1643,17 +1671,12 @@ Sending a Patch Series
 @end example
 @end quotation
 
-The patch email contains a three-dash separator line after the commit
-message.  You may ``annotate'' the patch with explanatory text by adding
-it under this line.  If you do not wish to annotate the email, you may
-drop the @option{--annotate} option.
-
-If you need to send a revised patch, don't resend it like this or send
-a ``fix'' patch to be applied on top of the last one; instead, use
-@command{git commit --amend} or @url{https://git-rebase.io,
-@command{git rebase}} to modify the commit, and use the
-@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v}
-flag with @command{git send-email}.
+If you need to send a revised patch, don't resend it like the above, nor send a
+``fix'' patch to be applied on top of the previous one; instead, use
+@command{git commit --amend} or @url{https://git-rebase.io, @command{git
+rebase}} to modify the commit, then call @command{git send-email} with the
+@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v} flag to
+give the revision a number.
 
 @example
 $ git commit --amend
@@ -1662,47 +1685,44 @@ Sending a Patch Series
 @end example
 
 @quotation Note
-Due to an apparent bug in @command{git send-email},
-@option{-v @var{REVISION}} (with the space) will not work; you
-@emph{must} use @option{-v@var{REVISION}}.
+@command{git send-email} syntax for patch versions is @option{-v@var{REVISION}}.
+Using @option{-v @var{REVISION}} (with a space) will not work.
 @end quotation
 
-You can find out @var{ISSUE_NUMBER} either by searching on the mumi
-interface at @url{https://issues.guix.gnu.org} for the name of your patch or
-reading the acknowledgement email sent automatically by Debbugs in
-reply to incoming bugs and patches, which contains the bug number.
+You can find out @var{ISSUE_NUMBER} either by searching on the Guix issue
+tracker at @url{https://issues.guix.gnu.org} for the name of your patch or by
+reading the acknowledgement email sent automatically by Debbugs in reply to
+incoming bugs and patches, which contains the bug number.
 
 @unnumberedsubsubsec Notifying Teams
 @anchor{Notifying Teams}
 @cindex teams
-If your git checkout has been correctly configured (@pxref{Configuring
-Git}), the @command{git send-email} command will automatically notify
-the appropriate team members, based on the scope of your changes.  This
-relies on the @file{etc/teams.scm} script, which can also be invoked
-manually if you do not use the preferred @command{git send-email}
-command to submit patches.  To list the available actions of the script,
-you can invoke it via the @command{etc/teams.scm help} command.  For
-more information regarding teams, @pxref{Teams}.
+If your git checkout has been correctly configured (@pxref{Configuring Git}),
+the @command{git send-email} command will automatically notify the appropriate
+team members, based on the scope of your changes.  This relies on the
+@file{etc/teams.scm} script, which can also be invoked manually if you do not
+use the preferred @command{git send-email} command to submit patches.  For more
+information regarding teams and @file{etc/teams.scm}, @pxref{Teams}.
 
 @quotation Note
-On foreign distros, you might have to use @command{./pre-inst-env git
-send-email} for @file{etc/teams.scm} to work.
+When using Guix as a package manager on foreign distros, you might have to use
+@command{./pre-inst-env git send-email} for @file{etc/teams.scm} to work.
 @end quotation
 
-@unnumberedsubsubsec Multiple Patches
-@anchor{Multiple Patches}
+@unnumberedsubsubsec Multiple Commit Patches
+@anchor{Multiple Commit Patches}
 @cindex cover letter
-While @command{git send-email} alone will suffice for a single
-patch, an unfortunate flaw in Debbugs means you need to be more
-careful when sending multiple patches: if you send them all to the
-@email{guix-patches@@gnu.org} address, a new issue will be created
-for each patch!
-
-When sending a series of patches, it's best to send a Git ``cover
-letter'' first, to give reviewers an overview of the patch series.
-We can create a directory called @file{outgoing} containing both
-our patch series and a cover letter called @file{0000-cover-letter.patch}
-with @command{git format-patch}.
+While @command{git send-email} alone will suffice for a single patch, you need
+to be more careful when sending multiple patches: if you send them all to the
+@email{guix-patches@@gnu.org} address, a new issue will be created for each
+patch!
+
+When sending a series of patches, it's best to send a Git ``cover letter''
+first, to give reviewers an overview of the patch series and create a single
+issue to send them to.  We can create a directory called @file{outgoing}
+containing both a cover letter called @file{0000-cover-letter.patch} and a patch
+series for the @var{NUMBER_COMMITS} last commits with @command{git
+format-patch}.
 
 @example
 $ git format-patch -@var{NUMBER_COMMITS} -o outgoing \
@@ -1710,29 +1730,32 @@ Sending a Patch Series
 @end example
 
 We can now send @emph{just} the cover letter to the
-@email{guix-patches@@gnu.org} address, which will create an issue
-that we can send the rest of the patches to.
+@email{guix-patches@@gnu.org} address, thus creating an issue to which we can
+send the patches.
 
 @example
 $ git send-email outgoing/0000-cover-letter.patch --annotate
 $ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
 @end example
 
-Ensure you edit the email to add an appropriate subject line and
-blurb before sending it.  Note the automatically generated shortlog
-and diffstat below the blurb.
+The command will open the cover letter for editing so you can add an appropriate
+subject line and blurb before sending it.  Note the automatically generated
+shortlog and diffstat below the blurb.
 
-Once the Debbugs mailer has replied to your cover letter email, you
-can send the actual patches to the newly-created issue address.
+Once the Debbugs mailer has replied to your cover letter email, with the
+@var{ISSUE_NUMBER} in the reply, you can send the actual patches to the
+newly-created issue address.
 
 @example
 $ git send-email outgoing/*.patch --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
 $ rm -rf outgoing # we don't need these anymore
 @end example
 
+And you're done!
+
 Thankfully, this @command{git format-patch} dance is not necessary
 to send an amended patch series, since an issue already exists for
-the patchset.
+the patchset.  Calling @command{git send-email} directly will do.
 
 @example
 $ git send-email -@var{NUMBER_COMMITS} -v@var{REVISION} \
@@ -1741,45 +1764,55 @@ Sending a Patch Series
 
 If need be, you may use @option{--cover-letter --annotate} to send
 another cover letter, e.g. for explaining what's changed since the last
-revision, and these changes are necessary.
+revision, and why these changes are necessary.
 
 @node Teams
 @subsection Teams
 @cindex teams
 
-There are several teams mentoring different parts of the Guix source
-code.  To list all those teams, you can run from a Guix checkout:
+There are several teams mentoring different parts of the Guix source code.  The
+script @file{etc/teams.scm} provides information about them.
+
+To list all teams with their members and the files under their scope, you can
+run from a Guix checkout:
 
 @example
 $ ./etc/teams.scm list-teams
+@end example
+
+To list the scope and members of a single team, for example the team `mentors'
+(which has no file scope):
+
+@example
+$ ./etc/teams.scm show mentors
 id: mentors
 name: Mentors
 description: A group of mentors who chaperone contributions by newcomers.
 members:
 + Christopher Baines <mail@@cbaines.net>
-+ Ricardo Wurmus <rekado@@elephly.net>
++ Ludovic Courtès <ludo@@gnu.org>
 + Mathieu Othacehe <othacehe@@gnu.org>
++ Ricardo Wurmus <rekado@@elephly.net>
 + jgart <jgart@@dismail.de>
-+ Ludovic Courtès <ludo@@gnu.org>
-@dots{}
 @end example
 
-You can run the following command to have the @code{Mentors} team put in
-CC of a patch series:
+@file{etc/teams.scm} can also infer the appropriate team or teams to notify
+about a patch series, and output option strings to be used with @command{git
+send-email} as well as @command{git format-patch}.  If Git was properly
+configured (@pxref{Configuring Git}), this is handled automatically by
+@command{git send-email} as explained in @ref{Notifying Teams}.
+
+As an example, you can run the following command to have the @code{Mentors} team
+put in CC of a seires of patch files to be sent with @command{git send-email}:
 
 @example
 $ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
   --header-cmd='etc/teams.scm cc-mentors-header-cmd' *.patch
 @end example
 
-The appropriate team or teams can also be inferred from the modified
-files.  For instance, if you want to send the two latest commits of the
-current Git repository to review, you can run:
+To list the available actions of the script, you can invoke it via the
+@file{etc/teams.scm help} command.
 
-@example
-$ guix shell -D guix
-[env]$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2
-@end example
 
 @node Tracking Bugs and Changes
 @section Tracking Bugs and Changes
@@ -2221,7 +2254,7 @@ Commit Access
 
 To avoid accidentally pushing unsigned or signed with the wrong key
 commits to Savannah, make sure to configure Git according to
-@xref{Configuring Git}.
+@ref{Configuring Git}.
 
 @subsection Commit Policy
 
diff --git a/doc/guix.texi b/doc/guix.texi
index 34aa3545da..bb5a145f5c 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7857,7 +7857,7 @@ Defining Packages
 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
 hash} (@pxref{Invoking guix hash}).
 
-@cindex patches
+@cindex patches, for packages
 When needed, the @code{origin} form can also have a @code{patches} field
 listing patches to be applied, and a @code{snippet} field giving a
 Scheme expression to modify the source code.
@@ -8586,7 +8586,7 @@ Defining Package Variants
 and in your own package collection
 (@pxref{Creating a Channel}), among others!
 
-@cindex inherit, for package definitions
+@cindex inherit, for packages
 As discussed earlier, packages are first-class objects in the Scheme
 language.  The @code{(guix packages)} module provides the @code{package}
 construct to define new package objects (@pxref{package Reference}).

base-commit: 8073a26022111c38808c1a803d59229288db0839
-- 
2.41.0