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

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

[Ale Abdo]

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

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 5707ff5cde..685d936a16 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,87 @@ 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, the surest way is to send
+patches produced by @command{git format-patch} as MIME attachments in plain text
+messages.  Using @command{git diff} instead of @command{git format-patch} is not
+advised as it will not include commit metadata.  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.  You may also send patches inline, as each patch file
+generated by @command{git format-patch} is a single valid email message, but
+you'd be advised to pay attention if your email client changes anything like
+line breaks or indentation, which could potentially break the patches.  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 +1676,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 +1690,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 +1735,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 +1769,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
@@ -2215,7 +2253,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 395545bed7..b2b7557742 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7847,7 +7847,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.
@@ -8576,7 +8576,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: c4fa3e945eee84f0459760f3ba8232dec49bd1ba
-- 
2.41.0

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

[Clément Lassieur]

On Sat, Jan 13 2024, Ale Abdo wrote:

>...     You may also send patches inline, as each patch file
> +generated by @command{git format-patch} is a single valid email message, but
> +you'd be advised to pay attention if your email client changes anything like
> +line breaks or indentation, which could potentially break the patches.

Hi, I haven't read all your patch, but this is wrong, I'm sorry.
Sending patches inline without using git send-email mostly doesn't work
for technical issues and is a waste of time for reviewers who try to
figure out why the patch doesn't apply.  We should not encourage this.

Thanks,
Clément

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

[Alexandre Hannud Abdo]

Ni! Thank you, we're actually in good agreement.

The possibility of sending inline patches is already there in the current documentation. The excerpt you cite is mostly collage of existing text that was spread in different sections.

I sought to articulate the possibilities and their preferred order more clearly so people can better weight the consequences. And I actually tried to word it in a way that would discourage inline patches more strongly than the current text. I have sent inline patches in the past, after reading the current text, and I'm sure I would not have sent them with the text I propose.

The only thing is that I did not feel authorized to exclude a possibility when rewriting the doc. But if you tell me I can, I'll happily change the wording to strictly discourage sending inline patches with an email client.

Best,

ale

.~´

Le 13/01/2024 à 12:27, Clément Lassieur a écrit :
> On Sat, Jan 13 2024, Ale Abdo wrote:
>
>> ...     You may also send patches inline, as each patch file
>> +generated by @command{git format-patch} is a single valid email message, but
>> +you'd be advised to pay attention if your email client changes anything like
>> +line breaks or indentation, which could potentially break the patches.
> Hi, I haven't read all your patch, but this is wrong, I'm sorry.
> Sending patches inline without using git send-email mostly doesn't work
> for technical issues and is a waste of time for reviewers who try to
> figure out why the patch doesn't apply.  We should not encourage this.
>
> Thanks,
> Clément

-- 
If wars can be started by lies, peace can be started by truth.
https://www.democracynow.org/live/watch_live_the_belmarsh_tribunal_on

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

[Clément Lassieur]

Hello Alexandre,

On Mon, Jan 15 2024, Alexandre Hannud Abdo wrote:

> Ni! Thank you, we're actually in good agreement.
>
> The possibility of sending inline patches is already there in the current documentation. The excerpt you cite is mostly collage of existing text that was spread in different sections.
>
> I sought to articulate the possibilities and their preferred order more
> clearly so people can better weight the consequences. And I actually tried to
> word it in a way that would discourage inline patches more strongly than the
> current text. I have sent inline patches in the past, after reading the
> current text, and I'm sure I would not have sent them with the text I propose.

The new version goes like: "You may also...".  But the truth is: "you
must not." (because inline patches just don't work without git
send-email).  It's a bit harsh, so I believe the best is to avoid
talking about things that we don't want.

> The only thing is that I did not feel authorized to exclude a possibility when
> rewriting the doc. But if you tell me I can, I'll happily change the wording
> to strictly discourage sending inline patches with an email client.

Rather than discourage, I think it's fine to not talk about it.  We
don't need to add rules for each use case.

Thanks,
Clément

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

[Alexandre Hannud Abdo]

Ni! Hi Clément,

I understand. The current version doesn't even make a distinction between inline patches and attached patches, so "you may …, but …" was just the weakest compatible form I found that didn't fundamentally change the message.

But since you're telling me it's fine to suppress it, that's all good and gone. I do have a thought about mentioning things that people could do out of convenience or habit, but won't work. But I'm fine with not talking about it.

One last question, following this reasoning, should I also remove the note about not using "git diff"? It's a similar situation, where just saying "send patches produced by format-patch" should suffice (and I would change "surest way" to "recommended way" or even better "make sure to send", which leaves no ground for doubt about either thing, without being too "rule-y").

Thank you,

ale

.~´

Le 15/01/2024 à 19:12, Clément Lassieur a écrit :
> Hello Alexandre,
>
> On Mon, Jan 15 2024, Alexandre Hannud Abdo wrote:
>
>> Ni! Thank you, we're actually in good agreement.
>>
>> The possibility of sending inline patches is already there in the current documentation. The excerpt you cite is mostly collage of existing text that was spread in different sections.
>>
>> I sought to articulate the possibilities and their preferred order more
>> clearly so people can better weight the consequences. And I actually tried to
>> word it in a way that would discourage inline patches more strongly than the
>> current text. I have sent inline patches in the past, after reading the
>> current text, and I'm sure I would not have sent them with the text I propose.
> The new version goes like: "You may also...".  But the truth is: "you
> must not." (because inline patches just don't work without git
> send-email).  It's a bit harsh, so I believe the best is to avoid
> talking about things that we don't want.
>
>> The only thing is that I did not feel authorized to exclude a possibility when
>> rewriting the doc. But if you tell me I can, I'll happily change the wording
>> to strictly discourage sending inline patches with an email client.
> Rather than discourage, I think it's fine to not talk about it.  We
> don't need to add rules for each use case.
>
> Thanks,
> Clément

-- 
If wars can be started by lies, peace can be started by truth.
https://www.democracynow.org/live/watch_live_the_belmarsh_tribunal_on

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

[Ale Abdo]

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