[PATCH] docs: recommend using contrib/contacts/git-contacts

[PATCH] docs: recommend using contrib/contacts/git-contacts

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Although we've had this script since 4d06402b1b (contrib: add
git-contacts helper, 2013-07-21), we don't mention it in our
introductory docs. Do so now.

Signed-off-by: Linus Arver <linusa@google.com>
---
    docs: recommend using contrib/contacts/git-contacts

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1704%2Flistx%2Freviewers-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1704/listx/reviewers-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1704

 Documentation/MyFirstContribution.txt | 3 +++
 Documentation/SubmittingPatches       | 4 ++++
 2 files changed, 7 insertions(+)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index f06563e9817..eb1e27a82df 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1116,6 +1116,9 @@ $ git send-email --to=target@example.com psuh/*.patch
 NOTE: Check `git help send-email` for some other options which you may find
 valuable, such as changing the Reply-to address or adding more CC and BCC lines.
 
+NOTE: Use `contrib/contacts/git-contacts` to get a list of reviewers you should
+include in the CC list.
+
 NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
 please don't send your patchset from the tutorial to the real mailing list! For
 now, you can send it to yourself, to make sure you understand how it will look.
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index e734a3f0f17..52d11ff510b 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -459,6 +459,10 @@ an explanation of changes between each iteration can be kept in
 Git-notes and inserted automatically following the three-dash
 line via `git format-patch --notes`.
 
+[[suggested-reviewers]]
+Use `contrib/contacts/git-contacts` to get a list of reviewers you should
+include in the CC list.
+
 [[attachment]]
 Do not attach the patch as a MIME attachment, compressed or not.
 Do not let your e-mail client send quoted-printable.  Do not let

base-commit: c2cbfbd2e28cbe27c194d62183b42f27a6a5bb87
-- 
gitgitgadget

Re: [PATCH] docs: recommend using contrib/contacts/git-contacts

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 2557 bytes --]

On Tue, Apr 02, 2024 at 12:20:05AM +0000, Linus Arver via GitGitGadget wrote:
> From: Linus Arver <linusa@google.com>
> 
> Although we've had this script since 4d06402b1b (contrib: add
> git-contacts helper, 2013-07-21), we don't mention it in our
> introductory docs. Do so now.
> 
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>     docs: recommend using contrib/contacts/git-contacts
> 
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1704%2Flistx%2Freviewers-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1704/listx/reviewers-v1
> Pull-Request: https://github.com/gitgitgadget/git/pull/1704
> 
>  Documentation/MyFirstContribution.txt | 3 +++
>  Documentation/SubmittingPatches       | 4 ++++
>  2 files changed, 7 insertions(+)
> 
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index f06563e9817..eb1e27a82df 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -1116,6 +1116,9 @@ $ git send-email --to=target@example.com psuh/*.patch
>  NOTE: Check `git help send-email` for some other options which you may find
>  valuable, such as changing the Reply-to address or adding more CC and BCC lines.
>  
> +NOTE: Use `contrib/contacts/git-contacts` to get a list of reviewers you should
> +include in the CC list.
> +

Should we mention that the script can be passed to git-send-email(1) via
`--cc-cmd=`?

Thanks!

Patrick

>  NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
>  please don't send your patchset from the tutorial to the real mailing list! For
>  now, you can send it to yourself, to make sure you understand how it will look.
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index e734a3f0f17..52d11ff510b 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -459,6 +459,10 @@ an explanation of changes between each iteration can be kept in
>  Git-notes and inserted automatically following the three-dash
>  line via `git format-patch --notes`.
>  
> +[[suggested-reviewers]]
> +Use `contrib/contacts/git-contacts` to get a list of reviewers you should
> +include in the CC list.
> +
>  [[attachment]]
>  Do not attach the patch as a MIME attachment, compressed or not.
>  Do not let your e-mail client send quoted-printable.  Do not let
> 
> base-commit: c2cbfbd2e28cbe27c194d62183b42f27a6a5bb87
> -- 
> gitgitgadget
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] docs: recommend using contrib/contacts/git-contacts

[Linus Arver]

Patrick Steinhardt <ps@pks.im> writes:

> On Tue, Apr 02, 2024 at 12:20:05AM +0000, Linus Arver via GitGitGadget wrote:
>> From: Linus Arver <linusa@google.com>
>> 
>> Although we've had this script since 4d06402b1b (contrib: add
>> git-contacts helper, 2013-07-21), we don't mention it in our
>> introductory docs. Do so now.
>> 
>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>>     docs: recommend using contrib/contacts/git-contacts
>> 
>> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1704%2Flistx%2Freviewers-v1
>> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1704/listx/reviewers-v1
>> Pull-Request: https://github.com/gitgitgadget/git/pull/1704
>> 
>>  Documentation/MyFirstContribution.txt | 3 +++
>>  Documentation/SubmittingPatches       | 4 ++++
>>  2 files changed, 7 insertions(+)
>> 
>> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
>> index f06563e9817..eb1e27a82df 100644
>> --- a/Documentation/MyFirstContribution.txt
>> +++ b/Documentation/MyFirstContribution.txt
>> @@ -1116,6 +1116,9 @@ $ git send-email --to=target@example.com psuh/*.patch
>>  NOTE: Check `git help send-email` for some other options which you may find
>>  valuable, such as changing the Reply-to address or adding more CC and BCC lines.
>>  
>> +NOTE: Use `contrib/contacts/git-contacts` to get a list of reviewers you should
>> +include in the CC list.
>> +
>
> Should we mention that the script can be passed to git-send-email(1) via
> `--cc-cmd=`?

Ack, will do. I think I can just copy/paste the existing guidance from
git-contact.txt which has this example:

    git send-email --cc-cmd='git contacts' feature/*.patch

Re: [PATCH] docs: recommend using contrib/contacts/git-contacts

[Matthias Aßhauer]

On Tue, 2 Apr 2024, Linus Arver via GitGitGadget wrote:

> From: Linus Arver <linusa@google.com>
>
> Although we've had this script since 4d06402b1b (contrib: add
> git-contacts helper, 2013-07-21), we don't mention it in our
> introductory docs. Do so now.
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>    docs: recommend using contrib/contacts/git-contacts
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1704%2Flistx%2Freviewers-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1704/listx/reviewers-v1
> Pull-Request: https://github.com/gitgitgadget/git/pull/1704
>
> Documentation/MyFirstContribution.txt | 3 +++
> Documentation/SubmittingPatches       | 4 ++++
> 2 files changed, 7 insertions(+)
>
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index f06563e9817..eb1e27a82df 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -1116,6 +1116,9 @@ $ git send-email --to=target@example.com psuh/*.patch
> NOTE: Check `git help send-email` for some other options which you may find
> valuable, such as changing the Reply-to address or adding more CC and BCC lines.
>
> +NOTE: Use `contrib/contacts/git-contacts` to get a list of reviewers you should
> +include in the CC list.
> +
> NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
> please don't send your patchset from the tutorial to the real mailing list! For
> now, you can send it to yourself, to make sure you understand how it will look.
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index e734a3f0f17..52d11ff510b 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -459,6 +459,10 @@ an explanation of changes between each iteration can be kept in
> Git-notes and inserted automatically following the three-dash
> line via `git format-patch --notes`.
>
> +[[suggested-reviewers]]
> +Use `contrib/contacts/git-contacts` to get a list of reviewers you should
> +include in the CC list.
> +

There is already a paragraph about this in Documentation/SubmittingPatches 
just a few paragraphs below.

> Send your patch with "To:" set to the mailing list, with "cc:" listing
> people who are involved in the area you are touching (the `git
> contacts` command in `contrib/contacts/` can help to
> identify them), to solicit comments and reviews.  Also, when you made
> trial merges of your topic to `next` and `seen`, you may have noticed
> work by others conflicting with your changes.  There is a good possibility
> that these people may know the area you are touching well.

Could we improve the existing paragraph instead of duplicating this 
information?

> [[attachment]]
> Do not attach the patch as a MIME attachment, compressed or not.
> Do not let your e-mail client send quoted-printable.  Do not let
>
> base-commit: c2cbfbd2e28cbe27c194d62183b42f27a6a5bb87
> -- 
> gitgitgadget
>

Re: [PATCH] docs: recommend using contrib/contacts/git-contacts

[Junio C Hamano]

Matthias Aßhauer <mha1993@live.de> writes:

> There is already a paragraph about this in
> Documentation/SubmittingPatches just a few paragraphs below.
>
>> Send your patch with "To:" set to the mailing list, with "cc:" listing
>> people who are involved in the area you are touching (the `git
>> contacts` command in `contrib/contacts/` can help to
>> identify them), to solicit comments and reviews.  Also, when you made
>> trial merges of your topic to `next` and `seen`, you may have noticed
>> work by others conflicting with your changes.  There is a good possibility
>> that these people may know the area you are touching well.
>
> Could we improve the existing paragraph instead of duplicating this
> information?

Absolutely.  I am glad that you were paying attention to the
question that triggered this patch ;-)

We may want to add to coding guidelines to try avoiding to word wrap
a line in the middle of a multi-word phrase.  If such a rule were
followed,

    $ git grep git.contacts Documentation

would easily had found the existing passage.

Thanks.

Re: [PATCH] docs: recommend using contrib/contacts/git-contacts

[Linus Arver]

Matthias Aßhauer <mha1993@live.de> writes:

> On Tue, 2 Apr 2024, Linus Arver via GitGitGadget wrote:
>
>> From: Linus Arver <linusa@google.com>
>>
>> Although we've had this script since 4d06402b1b (contrib: add
>> git-contacts helper, 2013-07-21), we don't mention it in our
>> introductory docs. Do so now.
>>
>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>>    docs: recommend using contrib/contacts/git-contacts
>>
>> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1704%2Flistx%2Freviewers-v1
>> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1704/listx/reviewers-v1
>> Pull-Request: https://github.com/gitgitgadget/git/pull/1704
>>
>> Documentation/MyFirstContribution.txt | 3 +++
>> Documentation/SubmittingPatches       | 4 ++++
>> 2 files changed, 7 insertions(+)
>>
>> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
>> index f06563e9817..eb1e27a82df 100644
>> --- a/Documentation/MyFirstContribution.txt
>> +++ b/Documentation/MyFirstContribution.txt
>> @@ -1116,6 +1116,9 @@ $ git send-email --to=target@example.com psuh/*.patch
>> NOTE: Check `git help send-email` for some other options which you may find
>> valuable, such as changing the Reply-to address or adding more CC and BCC lines.
>>
>> +NOTE: Use `contrib/contacts/git-contacts` to get a list of reviewers you should
>> +include in the CC list.
>> +
>> NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
>> please don't send your patchset from the tutorial to the real mailing list! For
>> now, you can send it to yourself, to make sure you understand how it will look.
>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
>> index e734a3f0f17..52d11ff510b 100644
>> --- a/Documentation/SubmittingPatches
>> +++ b/Documentation/SubmittingPatches
>> @@ -459,6 +459,10 @@ an explanation of changes between each iteration can be kept in
>> Git-notes and inserted automatically following the three-dash
>> line via `git format-patch --notes`.
>>
>> +[[suggested-reviewers]]
>> +Use `contrib/contacts/git-contacts` to get a list of reviewers you should
>> +include in the CC list.
>> +
>
> There is already a paragraph about this in Documentation/SubmittingPatches 
> just a few paragraphs below.
>
>> Send your patch with "To:" set to the mailing list, with "cc:" listing
>> people who are involved in the area you are touching (the `git
>> contacts` command in `contrib/contacts/` can help to
>> identify them), to solicit comments and reviews.  Also, when you made
>> trial merges of your topic to `next` and `seen`, you may have noticed
>> work by others conflicting with your changes.  There is a good possibility
>> that these people may know the area you are touching well.
>
> Could we improve the existing paragraph instead of duplicating this 
> information?

Ah, yes of course (somehow I missed that existing guidance). Will update.

[RFC] git-contacts: exclude list (was: Re: [PATCH] docs: recommend using contrib/contacts/git-contacts)

[Matthias Aßhauer]

On Wed, 3 Apr 2024, Matthias Aßhauer wrote:

>

After sending my previous message I've noticed that all of the 
etu.univ-lyon1.fr recipients bounced with the 
message

> 550 5.5.0 Requested actions not taken as the mailbox is unavailable

After running https://etu.univ-lyon1.fr/ through a machine translation 
service it seems like that subdomain is used for mailboxes of current 
students, whereas staff like Matthieu get a mailbox on the main domain.
With Corentin, Nathan and Pablo presumably being former students, it's 
probably unlikely that these mailboxes will become active again.

Would it make sense to have a way to teach `git-contacts` to exclude a 
user defined list of known-bad recipient adresses? This could potentiallly 
be an extension of mailmap or a separate file.

>
> On Tue, 2 Apr 2024, Linus Arver via GitGitGadget wrote:
>
>> From: Linus Arver <linusa@google.com>
>> 
>> Although we've had this script since 4d06402b1b (contrib: add
>> git-contacts helper, 2013-07-21), we don't mention it in our
>> introductory docs. Do so now.
>> 
>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>>    docs: recommend using contrib/contacts/git-contacts
>> 
>> Published-As: 
>> https://github.com/gitgitgadget/git/releases/tag/pr-1704%2Flistx%2Freviewers-v1
>> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git 
>> pr-1704/listx/reviewers-v1
>> Pull-Request: https://github.com/gitgitgadget/git/pull/1704
>> 
>> Documentation/MyFirstContribution.txt | 3 +++
>> Documentation/SubmittingPatches       | 4 ++++
>> 2 files changed, 7 insertions(+)
>> 
>> diff --git a/Documentation/MyFirstContribution.txt 
>> b/Documentation/MyFirstContribution.txt
>> index f06563e9817..eb1e27a82df 100644
>> --- a/Documentation/MyFirstContribution.txt
>> +++ b/Documentation/MyFirstContribution.txt
>> @@ -1116,6 +1116,9 @@ $ git send-email --to=target@example.com psuh/*.patch
>> NOTE: Check `git help send-email` for some other options which you may find
>> valuable, such as changing the Reply-to address or adding more CC and BCC 
>> lines.
>> 
>> +NOTE: Use `contrib/contacts/git-contacts` to get a list of reviewers you 
>> should
>> +include in the CC list.
>> +
>> NOTE: When you are sending a real patch, it will go to git@vger.kernel.org 
>> - but
>> please don't send your patchset from the tutorial to the real mailing list! 
>> For
>> now, you can send it to yourself, to make sure you understand how it will 
>> look.
>> diff --git a/Documentation/SubmittingPatches 
>> b/Documentation/SubmittingPatches
>> index e734a3f0f17..52d11ff510b 100644
>> --- a/Documentation/SubmittingPatches
>> +++ b/Documentation/SubmittingPatches
>> @@ -459,6 +459,10 @@ an explanation of changes between each iteration can 
>> be kept in
>> Git-notes and inserted automatically following the three-dash
>> line via `git format-patch --notes`.
>> 
>> +[[suggested-reviewers]]
>> +Use `contrib/contacts/git-contacts` to get a list of reviewers you should
>> +include in the CC list.
>> +
>
> There is already a paragraph about this in Documentation/SubmittingPatches 
> just a few paragraphs below.
>
>> Send your patch with "To:" set to the mailing list, with "cc:" listing
>> people who are involved in the area you are touching (the `git
>> contacts` command in `contrib/contacts/` can help to
>> identify them), to solicit comments and reviews.  Also, when you made
>> trial merges of your topic to `next` and `seen`, you may have noticed
>> work by others conflicting with your changes.  There is a good possibility
>> that these people may know the area you are touching well.
>
> Could we improve the existing paragraph instead of duplicating this 
> information?
>
>> [[attachment]]
>> Do not attach the patch as a MIME attachment, compressed or not.
>> Do not let your e-mail client send quoted-printable.  Do not let
>> 
>> base-commit: c2cbfbd2e28cbe27c194d62183b42f27a6a5bb87
>> -- 
>> gitgitgadget
>> 
>

Re: [RFC] git-contacts: exclude list

[Junio C Hamano]

Matthias Aßhauer <mha1993@live.de> writes:

> Would it make sense to have a way to teach `git-contacts` to exclude a
> user defined list of known-bad recipient adresses? This could
> potentiallly be an extension of mailmap or a separate file.

The contacts script already uses "check-mailmap".  

Unfortunately it only uses the default mailmap, which may not be
suitable for our purpose here, but it shouldn't be too hard to run
"git -c mailmap.file=<custom> check-mailmap", ship a custom mailmap
file with the contacts script to map defunct addresses to something
that is clearly invalid, and then filter them out from the output.

We want to add a mechanism to allow "including" another mailmap, so
that "../../.mailmap" is included from contrib/contacts/mailmap or
something like that.

On the other hand, if we want to use our primary mailmap to also
mark the defunct addresses, then we do not have to do anything
special.  Mark these defunct addresses to the primary mailmap to
map them to "$HumanReadableName <$name@defunct.invalid>" and then
doing something like the attached.

diff --git i/contrib/contacts/git-contacts w/contrib/contacts/git-contacts
index 85ad732fc0..00e77c4125 100755
--- i/contrib/contacts/git-contacts
+++ w/contrib/contacts/git-contacts
@@ -197,6 +197,7 @@ $contacts = mailmap_contacts($contacts);
 
 my $ncommits = scalar(keys %commits);
 for my $contact (keys %$contacts) {
+	next if $contact =~ /\@defunct.invalid>$/;
 	my $percent = $contacts->{$contact} * 100 / $ncommits;
 	next if $percent < $min_percent;
 	print "$contact\n";

Re: [RFC] git-contacts: exclude list

[Matthieu Moy]

On 4/3/24 12:11, Matthias Aßhauer wrote:
> 
> 
> On Wed, 3 Apr 2024, Matthias Aßhauer wrote:
> 
> After sending my previous message I've noticed that all of the etu.univ-lyon1.fr recipients bounced with the
> message
> 
>> 550 5.5.0 Requested actions not taken as the mailbox is unavailable
> 
> After running etu.univ-lyon1.fr&through a machine translation
> service it seems like that subdomain is used for mailboxes of current
> students,

Indeed. These are former students, who contributed to Git under my 
supervision (as teacher in the same university). I don't have their 
current email address.

> Would it make sense to have a way to teach `git-contacts` to exclude a
> user defined list of known-bad recipient adresses? This could potentiallly
> be an extension of mailmap or a separate file.

Sounds like a good idea, yes. At least, the current thread would be a 
good use-case for such feature.

-- 
Matthieu Moy

[PATCH v2 0/8] docs: recommend using contrib/contacts/git-contacts

[Linus Arver via GitGitGadget]

Make git-contacts more prominent in our docs.


Notable changes in v2
=====================

 * Improve existing mention of git-contacts in SubmittingPatches (instead of
   adding a separate, entirely new paragraph)
 * Add example usage of integrating git-contacts with git-send-email with
   the latter's --cc-cmd flag.
 * Various smaller fixes to SubmittingPatches

Linus Arver (8):
  MyFirstContribution: mention contrib/contacts/git-contacts
  SubmittingPatches: make 'git contacts' grep-friendly
  SubmittingPatches: mention GitGitGadget
  SubmittingPatches: quote commands
  SubmittingPatches: discuss reviewers first
  SubmittingPatches: dedupe discussion of security patches
  SubmittingPatches: add heading for format-patch and send-email
  SubmittingPatches: demonstrate using git-contacts with git-send-email

 Documentation/MyFirstContribution.txt |  5 ++
 Documentation/SubmittingPatches       | 68 +++++++++++++++------------
 2 files changed, 43 insertions(+), 30 deletions(-)


base-commit: c2cbfbd2e28cbe27c194d62183b42f27a6a5bb87
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1704%2Flistx%2Freviewers-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1704/listx/reviewers-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1704

Range-diff vs v1:

 1:  7f1ac742008 ! 1:  3817e7f3cd0 docs: recommend using contrib/contacts/git-contacts
     @@ Metadata
      Author: Linus Arver <linusa@google.com>
      
       ## Commit message ##
     -    docs: recommend using contrib/contacts/git-contacts
     +    MyFirstContribution: mention contrib/contacts/git-contacts
      
          Although we've had this script since 4d06402b1b (contrib: add
          git-contacts helper, 2013-07-21), we don't mention it in our
     @@ Documentation/MyFirstContribution.txt: $ git send-email --to=target@example.com
       valuable, such as changing the Reply-to address or adding more CC and BCC lines.
       
      +NOTE: Use `contrib/contacts/git-contacts` to get a list of reviewers you should
     -+include in the CC list.
     ++include in the CC list. In addition, you can do `git send-email --cc-cmd='git
     ++contacts' feature/*.patch` to automatically pass this list of emails to
     ++`send-email`.
      +
       NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
       please don't send your patchset from the tutorial to the real mailing list! For
       now, you can send it to yourself, to make sure you understand how it will look.
     -
     - ## Documentation/SubmittingPatches ##
     -@@ Documentation/SubmittingPatches: an explanation of changes between each iteration can be kept in
     - Git-notes and inserted automatically following the three-dash
     - line via `git format-patch --notes`.
     - 
     -+[[suggested-reviewers]]
     -+Use `contrib/contacts/git-contacts` to get a list of reviewers you should
     -+include in the CC list.
     -+
     - [[attachment]]
     - Do not attach the patch as a MIME attachment, compressed or not.
     - Do not let your e-mail client send quoted-printable.  Do not let
 -:  ----------- > 2:  82e5e05288d SubmittingPatches: make 'git contacts' grep-friendly
 -:  ----------- > 3:  6e6950afa6e SubmittingPatches: mention GitGitGadget
 -:  ----------- > 4:  fb06d5ce247 SubmittingPatches: quote commands
 -:  ----------- > 5:  a8abcf45881 SubmittingPatches: discuss reviewers first
 -:  ----------- > 6:  326afe13315 SubmittingPatches: dedupe discussion of security patches
 -:  ----------- > 7:  09f4e7ad123 SubmittingPatches: add heading for format-patch and send-email
 -:  ----------- > 8:  b35748f0cf8 SubmittingPatches: demonstrate using git-contacts with git-send-email

-- 
gitgitgadget

[PATCH v2 1/8] MyFirstContribution: mention contrib/contacts/git-contacts

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Although we've had this script since 4d06402b1b (contrib: add
git-contacts helper, 2013-07-21), we don't mention it in our
introductory docs. Do so now.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/MyFirstContribution.txt | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index f06563e9817..ad3989f53e5 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1116,6 +1116,11 @@ $ git send-email --to=target@example.com psuh/*.patch
 NOTE: Check `git help send-email` for some other options which you may find
 valuable, such as changing the Reply-to address or adding more CC and BCC lines.
 
+NOTE: Use `contrib/contacts/git-contacts` to get a list of reviewers you should
+include in the CC list. In addition, you can do `git send-email --cc-cmd='git
+contacts' feature/*.patch` to automatically pass this list of emails to
+`send-email`.
+
 NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
 please don't send your patchset from the tutorial to the real mailing list! For
 now, you can send it to yourself, to make sure you understand how it will look.
-- 
gitgitgadget

Re: [PATCH v2 1/8] MyFirstContribution: mention contrib/contacts/git-contacts

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> Although we've had this script since 4d06402b1b (contrib: add
> git-contacts helper, 2013-07-21), we don't mention it in our
> introductory docs. Do so now.
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/MyFirstContribution.txt | 5 +++++
>  1 file changed, 5 insertions(+)
>
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index f06563e9817..ad3989f53e5 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -1116,6 +1116,11 @@ $ git send-email --to=target@example.com psuh/*.patch
>  NOTE: Check `git help send-email` for some other options which you may find
>  valuable, such as changing the Reply-to address or adding more CC and BCC lines.
>  
> +NOTE: Use `contrib/contacts/git-contacts` to get a list of reviewers you should
> +include in the CC list. In addition, you can do `git send-email --cc-cmd='git
> +contacts' feature/*.patch` to automatically pass this list of emails to
> +`send-email`.
> +
>  NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
>  please don't send your patchset from the tutorial to the real mailing list! For
>  now, you can send it to yourself, to make sure you understand how it will look.

Nice.  

I personally find "you should" a bit too strong and authoritative,
though.  Is the tool precise enough that we are confident that we do
not end up spamming those who are not actively helping others?

As I prefer not to be too assertive, something like

    The `contrib/contacts/git-contacts` script may help you coming
    up people you may want to ask to review your patch by adding
    them to the Cc: header.

is as far as I would go, but for those who are not familiar enough
with the project, perhaps it would be OK to assume that the script
would do a much better job than these contributors would do
themselves, I guess.

Thanks.

Re: [PATCH v2 1/8] MyFirstContribution: mention contrib/contacts/git-contacts

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Linus Arver <linusa@google.com>
>>
>> Although we've had this script since 4d06402b1b (contrib: add
>> git-contacts helper, 2013-07-21), we don't mention it in our
>> introductory docs. Do so now.
>>
>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>>  Documentation/MyFirstContribution.txt | 5 +++++
>>  1 file changed, 5 insertions(+)
>>
>> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
>> index f06563e9817..ad3989f53e5 100644
>> --- a/Documentation/MyFirstContribution.txt
>> +++ b/Documentation/MyFirstContribution.txt
>> @@ -1116,6 +1116,11 @@ $ git send-email --to=target@example.com psuh/*.patch
>>  NOTE: Check `git help send-email` for some other options which you may find
>>  valuable, such as changing the Reply-to address or adding more CC and BCC lines.
>>  
>> +NOTE: Use `contrib/contacts/git-contacts` to get a list of reviewers you should
>> +include in the CC list. In addition, you can do `git send-email --cc-cmd='git
>> +contacts' feature/*.patch` to automatically pass this list of emails to
>> +`send-email`.
>> +
>>  NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
>>  please don't send your patchset from the tutorial to the real mailing list! For
>>  now, you can send it to yourself, to make sure you understand how it will look.
>
> Nice.  
>
> I personally find "you should" a bit too strong and authoritative,
> though.  Is the tool precise enough that we are confident that we do
> not end up spamming those who are not actively helping others?

TBH I had the same question, but brushed it off because I figured that
getting people to still use the tool would help make it better (find
additional areas of improvement, etc).

> As I prefer not to be too assertive, something like
>
>     The `contrib/contacts/git-contacts` script may help you coming
>     up people you may want to ask to review your patch by adding
>     them to the Cc: header.
>
> is as far as I would go, but for those who are not familiar enough
> with the project, perhaps it would be OK to assume that the script
> would do a much better job than these contributors would do
> themselves, I guess.

Yeah for newcomers the tool would probably do a better job. Perhaps
wording it like "If you're not sure who to CC, use
`contrib/contacts/git-contacts` to ..."  would be better?

Re: [PATCH v2 1/8] MyFirstContribution: mention contrib/contacts/git-contacts

[Junio C Hamano]

Linus Arver <linusa@google.com> writes:

>> As I prefer not to be too assertive, something like
>>
>>     The `contrib/contacts/git-contacts` script may help you coming
>>     up people you may want to ask to review your patch by adding
>>     them to the Cc: header.
>>
>> is as far as I would go, but for those who are not familiar enough
>> with the project, perhaps it would be OK to assume that the script
>> would do a much better job than these contributors would do
>> themselves, I guess.
>
> Yeah for newcomers the tool would probably do a better job. Perhaps
> wording it like "If you're not sure who to CC, use
> `contrib/contacts/git-contacts` to ..."  would be better?

Sounds reasonable.  Thanks.

[PATCH v2 2/8] SubmittingPatches: make 'git contacts' grep-friendly

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Avoid splitting up the command over two lines. This way, a command like

    $ git grep git.contacts Documentation

will return a positive hit for this location.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index e734a3f0f17..a33fe7e11f6 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -494,8 +494,8 @@ mentioned below, but should instead be sent privately to the Git
 Security mailing list{security-ml-ref}.
 
 Send your patch with "To:" set to the mailing list, with "cc:" listing
-people who are involved in the area you are touching (the `git
-contacts` command in `contrib/contacts/` can help to
+people who are involved in the area you are touching (the `git contacts`
+command in `contrib/contacts/` can help to
 identify them), to solicit comments and reviews.  Also, when you made
 trial merges of your topic to `next` and `seen`, you may have noticed
 work by others conflicting with your changes.  There is a good possibility
-- 
gitgitgadget

Re: [PATCH v2 2/8] SubmittingPatches: make 'git contacts' grep-friendly

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> Avoid splitting up the command over two lines. This way, a command like
>
>     $ git grep git.contacts Documentation
>
> will return a positive hit for this location.
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/SubmittingPatches | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index e734a3f0f17..a33fe7e11f6 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -494,8 +494,8 @@ mentioned below, but should instead be sent privately to the Git
>  Security mailing list{security-ml-ref}.
>  
>  Send your patch with "To:" set to the mailing list, with "cc:" listing
> -people who are involved in the area you are touching (the `git
> -contacts` command in `contrib/contacts/` can help to
> +people who are involved in the area you are touching (the `git contacts`
> +command in `contrib/contacts/` can help to
>  identify them), to solicit comments and reviews.  Also, when you made
>  trial merges of your topic to `next` and `seen`, you may have noticed
>  work by others conflicting with your changes.  There is a good possibility

Sure.  But I think a general rule to avoid writing documentation pages
that require a fix-up like this patch would be more valuable in the
longer term.

Or investing in a better "grep" command ;-)

In any case, this is an improvement, so let's queue it as-is.

[PATCH v2 3/8] SubmittingPatches: mention GitGitGadget

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index a33fe7e11f6..48b270b4c48 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -408,6 +408,10 @@ are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
 type e-mails) might render your patches unusable.
 
+NOTE: You can also use GitGitGadget (https://gitgitgadget.github.io/) to send in
+your patches. The discussion here focuses on using `format-patch` and
+`send-email`.
+
 People on the Git mailing list need to be able to read and
 comment on the changes you are submitting.  It is important for
 a developer to be able to "quote" your changes, using standard
-- 
gitgitgadget

Re: [PATCH v2 3/8] SubmittingPatches: mention GitGitGadget

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/SubmittingPatches | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index a33fe7e11f6..48b270b4c48 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -408,6 +408,10 @@ are optimized for the workflow of sending patches, avoiding many ways
>  your existing e-mail client (often optimized for "multipart/*" MIME
>  type e-mails) might render your patches unusable.
>  
> +NOTE: You can also use GitGitGadget (https://gitgitgadget.github.io/) to send in
> +your patches. The discussion here focuses on using `format-patch` and
> +`send-email`.
> +
>  People on the Git mailing list need to be able to read and
>  comment on the changes you are submitting.  It is important for
>  a developer to be able to "quote" your changes, using standard

Rather than giving the URL and have the readers figure out how to
use it for themselves, it would be more helpful to readers to refer
them to MyFirstContrib document.

    Note: we outline the procedure using `format-patch` plus
    `send-email`, but you can also use GitGitGadget to send in your
    patches (see MyFirstContribution document).

Re: [PATCH v2 3/8] SubmittingPatches: mention GitGitGadget

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Linus Arver <linusa@google.com>
>>
>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>>  Documentation/SubmittingPatches | 4 ++++
>>  1 file changed, 4 insertions(+)
>>
>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
>> index a33fe7e11f6..48b270b4c48 100644
>> --- a/Documentation/SubmittingPatches
>> +++ b/Documentation/SubmittingPatches
>> @@ -408,6 +408,10 @@ are optimized for the workflow of sending patches, avoiding many ways
>>  your existing e-mail client (often optimized for "multipart/*" MIME
>>  type e-mails) might render your patches unusable.
>>  
>> +NOTE: You can also use GitGitGadget (https://gitgitgadget.github.io/) to send in
>> +your patches. The discussion here focuses on using `format-patch` and
>> +`send-email`.
>> +
>>  People on the Git mailing list need to be able to read and
>>  comment on the changes you are submitting.  It is important for
>>  a developer to be able to "quote" your changes, using standard
>
> Rather than giving the URL and have the readers figure out how to
> use it for themselves, it would be more helpful to readers to refer
> them to MyFirstContrib document.
>
>     Note: we outline the procedure using `format-patch` plus
>     `send-email`, but you can also use GitGitGadget to send in your
>     patches (see MyFirstContribution document).

Ah, of course. Will update.

Re: [PATCH v2 3/8] SubmittingPatches: mention GitGitGadget

[Junio C Hamano]

Linus Arver <linusa@google.com> writes:

>>     Note: we outline the procedure using `format-patch` plus
>>     `send-email`, but you can also use GitGitGadget to send in your
>>     patches (see MyFirstContribution document).
>
> Ah, of course. Will update.

Sure. "can also" -> "can instead", I think.

[PATCH v2 4/8] SubmittingPatches: quote commands

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 48b270b4c48..24c7041a06f 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -403,7 +403,7 @@ Before sending any patches, please note that patches that may be
 security relevant should be submitted privately to the Git Security
 mailing list{security-ml}, instead of the public mailing list.
 
-Learn to use format-patch and send-email if possible.  These commands
+Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
 type e-mails) might render your patches unusable.
-- 
gitgitgadget

[PATCH v2 5/8] SubmittingPatches: discuss reviewers first

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

No matter how well someone configures their email tooling, understanding
who to send the patches to is something that must always be considered.
So discuss it first instead of at the end.

In the following commit we will clean up the (now redundant) discussion
about sending security patches to the Git Security mailing list.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 58 +++++++++++++++++----------------
 1 file changed, 30 insertions(+), 28 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 24c7041a06f..17db961bac4 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -397,6 +397,36 @@ letter.
 [[send-patches]]
 === Sending your patches.
 
+==== Choosing your reviewers
+
+:security-ml-ref: footnoteref:[security-ml]
+
+As mentioned at the beginning of the section, patches that may be
+security relevant should not be submitted to the public mailing list
+mentioned below, but should instead be sent privately to the Git
+Security mailing list{security-ml-ref}.
+
+Send your patch with "To:" set to the mailing list, with "cc:" listing
+people who are involved in the area you are touching (the `git contacts`
+command in `contrib/contacts/` can help to
+identify them), to solicit comments and reviews.  Also, when you made
+trial merges of your topic to `next` and `seen`, you may have noticed
+work by others conflicting with your changes.  There is a good possibility
+that these people may know the area you are touching well.
+
+:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
+:git-ml: footnote:[The mailing list: git@vger.kernel.org]
+
+After the list reached a consensus that it is a good idea to apply the
+patch, re-send it with "To:" set to the maintainer{current-maintainer}
+and "cc:" the list{git-ml} for inclusion.  This is especially relevant
+when the maintainer did not heavily participate in the discussion and
+instead left the review to trusted others.
+
+Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
+`Tested-by:` lines as necessary to credit people who helped your
+patch, and "cc:" them when sending such a final version for inclusion.
+
 :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
 
 Before sending any patches, please note that patches that may be
@@ -490,34 +520,6 @@ patch, format it as "multipart/signed", not a text/plain message
 that starts with `-----BEGIN PGP SIGNED MESSAGE-----`.  That is
 not a text/plain, it's something else.
 
-:security-ml-ref: footnoteref:[security-ml]
-
-As mentioned at the beginning of the section, patches that may be
-security relevant should not be submitted to the public mailing list
-mentioned below, but should instead be sent privately to the Git
-Security mailing list{security-ml-ref}.
-
-Send your patch with "To:" set to the mailing list, with "cc:" listing
-people who are involved in the area you are touching (the `git contacts`
-command in `contrib/contacts/` can help to
-identify them), to solicit comments and reviews.  Also, when you made
-trial merges of your topic to `next` and `seen`, you may have noticed
-work by others conflicting with your changes.  There is a good possibility
-that these people may know the area you are touching well.
-
-:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
-:git-ml: footnote:[The mailing list: git@vger.kernel.org]
-
-After the list reached a consensus that it is a good idea to apply the
-patch, re-send it with "To:" set to the maintainer{current-maintainer}
-and "cc:" the list{git-ml} for inclusion.  This is especially relevant
-when the maintainer did not heavily participate in the discussion and
-instead left the review to trusted others.
-
-Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
-`Tested-by:` lines as necessary to credit people who helped your
-patch, and "cc:" them when sending such a final version for inclusion.
-
 == Subsystems with dedicated maintainers
 
 Some parts of the system have dedicated maintainers with their own
-- 
gitgitgadget

[PATCH v2 6/8] SubmittingPatches: dedupe discussion of security patches

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 17db961bac4..311f306394b 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -399,12 +399,11 @@ letter.
 
 ==== Choosing your reviewers
 
-:security-ml-ref: footnoteref:[security-ml]
+:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
 
-As mentioned at the beginning of the section, patches that may be
-security relevant should not be submitted to the public mailing list
-mentioned below, but should instead be sent privately to the Git
-Security mailing list{security-ml-ref}.
+NOTE: Patches that may be
+security relevant should be submitted privately to the Git Security
+mailing list{security-ml}, instead of the public mailing list.
 
 Send your patch with "To:" set to the mailing list, with "cc:" listing
 people who are involved in the area you are touching (the `git contacts`
@@ -427,12 +426,6 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
 `Tested-by:` lines as necessary to credit people who helped your
 patch, and "cc:" them when sending such a final version for inclusion.
 
-:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
-
-Before sending any patches, please note that patches that may be
-security relevant should be submitted privately to the Git Security
-mailing list{security-ml}, instead of the public mailing list.
-
 Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
-- 
gitgitgadget

[PATCH v2 7/8] SubmittingPatches: add heading for format-patch and send-email

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 311f306394b..48224e745ff 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -426,6 +426,8 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
 `Tested-by:` lines as necessary to credit people who helped your
 patch, and "cc:" them when sending such a final version for inclusion.
 
+==== `format-patch` and `send-email`
+
 Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
-- 
gitgitgadget

[PATCH v2 8/8] SubmittingPatches: demonstrate using git-contacts with git-send-email

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 48224e745ff..11c3e94d4a5 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -413,6 +413,13 @@ trial merges of your topic to `next` and `seen`, you may have noticed
 work by others conflicting with your changes.  There is a good possibility
 that these people may know the area you are touching well.
 
+If you are using `send-email`, you can feed it the output of `git contacts` like
+this:
+
+....
+	git send-email --cc-cmd='git contacts' feature/*.patch
+....
+
 :current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
 :git-ml: footnote:[The mailing list: git@vger.kernel.org]
 
-- 
gitgitgadget

Re: [PATCH v2 0/8] docs: recommend using contrib/contacts/git-contacts

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> Make git-contacts more prominent in our docs.

Thanks.  Overall all patches look improvements.  I left some
comments on a few patches, though.

[PATCH v3 0/8] docs: recommend using contrib/contacts/git-contacts

[Linus Arver via GitGitGadget]

Make git-contacts more prominent in our docs.


Notable changes in v3
=====================

 * Refer to GitGitGadget via a link to MyFirstContribution (instead of
   sending readers to GGG's homepage directly)
 * Soften the advice for using git-contacts


Notable changes in v2
=====================

 * Improve existing mention of git-contacts in SubmittingPatches (instead of
   adding a separate, entirely new paragraph)
 * Add example usage of integrating git-contacts with git-send-email with
   the latter's --cc-cmd flag.
 * Various smaller fixes to SubmittingPatches

Linus Arver (8):
  MyFirstContribution: mention contrib/contacts/git-contacts
  SubmittingPatches: make 'git contacts' grep-friendly
  SubmittingPatches: mention GitGitGadget
  SubmittingPatches: quote commands
  SubmittingPatches: discuss reviewers first
  SubmittingPatches: dedupe discussion of security patches
  SubmittingPatches: add heading for format-patch and send-email
  SubmittingPatches: demonstrate using git-contacts with git-send-email

 Documentation/MyFirstContribution.txt |  5 ++
 Documentation/SubmittingPatches       | 68 +++++++++++++++------------
 2 files changed, 43 insertions(+), 30 deletions(-)


base-commit: c2cbfbd2e28cbe27c194d62183b42f27a6a5bb87
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1704%2Flistx%2Freviewers-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1704/listx/reviewers-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1704

Range-diff vs v2:

 1:  3817e7f3cd0 ! 1:  1f65dc5ba3d MyFirstContribution: mention contrib/contacts/git-contacts
     @@ Documentation/MyFirstContribution.txt: $ git send-email --to=target@example.com
       NOTE: Check `git help send-email` for some other options which you may find
       valuable, such as changing the Reply-to address or adding more CC and BCC lines.
       
     -+NOTE: Use `contrib/contacts/git-contacts` to get a list of reviewers you should
     -+include in the CC list. In addition, you can do `git send-email --cc-cmd='git
     -+contacts' feature/*.patch` to automatically pass this list of emails to
     -+`send-email`.
     ++NOTE: If you're not sure who to CC, use `contrib/contacts/git-contacts` to get a
     ++list of reviewers you should include in the CC list. In addition, you can do
     ++`git send-email --cc-cmd='git contacts' feature/*.patch` to automatically pass
     ++this list of emails to `send-email`.
      +
       NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
       please don't send your patchset from the tutorial to the real mailing list! For
 2:  82e5e05288d = 2:  6e8b1b50ac5 SubmittingPatches: make 'git contacts' grep-friendly
 3:  6e6950afa6e ! 3:  7f8fdc053f7 SubmittingPatches: mention GitGitGadget
     @@ Documentation/SubmittingPatches: are optimized for the workflow of sending patch
       your existing e-mail client (often optimized for "multipart/*" MIME
       type e-mails) might render your patches unusable.
       
     -+NOTE: You can also use GitGitGadget (https://gitgitgadget.github.io/) to send in
     -+your patches. The discussion here focuses on using `format-patch` and
     -+`send-email`.
     ++NOTE: Here we outline the procedure using `format-patch` and
     ++`send-email`, but you can instead use GitGitGadget to send in your
     ++patches (see link:MyFirstContribution.html[MyFirstContribution]).
      +
       People on the Git mailing list need to be able to read and
       comment on the changes you are submitting.  It is important for
 4:  fb06d5ce247 = 4:  ef26bdb75c5 SubmittingPatches: quote commands
 5:  a8abcf45881 = 5:  6f71b1731f2 SubmittingPatches: discuss reviewers first
 6:  326afe13315 = 6:  f5e44f69941 SubmittingPatches: dedupe discussion of security patches
 7:  09f4e7ad123 = 7:  e64fc5c888a SubmittingPatches: add heading for format-patch and send-email
 8:  b35748f0cf8 = 8:  4fcab0d3319 SubmittingPatches: demonstrate using git-contacts with git-send-email

-- 
gitgitgadget

[PATCH v3 1/8] MyFirstContribution: mention contrib/contacts/git-contacts

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Although we've had this script since 4d06402b1b (contrib: add
git-contacts helper, 2013-07-21), we don't mention it in our
introductory docs. Do so now.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/MyFirstContribution.txt | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index f06563e9817..00f4c63cb9f 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1116,6 +1116,11 @@ $ git send-email --to=target@example.com psuh/*.patch
 NOTE: Check `git help send-email` for some other options which you may find
 valuable, such as changing the Reply-to address or adding more CC and BCC lines.
 
+NOTE: If you're not sure who to CC, use `contrib/contacts/git-contacts` to get a
+list of reviewers you should include in the CC list. In addition, you can do
+`git send-email --cc-cmd='git contacts' feature/*.patch` to automatically pass
+this list of emails to `send-email`.
+
 NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
 please don't send your patchset from the tutorial to the real mailing list! For
 now, you can send it to yourself, to make sure you understand how it will look.
-- 
gitgitgadget

Re: [PATCH v3 1/8] MyFirstContribution: mention contrib/contacts/git-contacts

[Linus Arver]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> Although we've had this script since 4d06402b1b (contrib: add
> git-contacts helper, 2013-07-21), we don't mention it in our
> introductory docs. Do so now.
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/MyFirstContribution.txt | 5 +++++
>  1 file changed, 5 insertions(+)
>
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index f06563e9817..00f4c63cb9f 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -1116,6 +1116,11 @@ $ git send-email --to=target@example.com psuh/*.patch
>  NOTE: Check `git help send-email` for some other options which you may find
>  valuable, such as changing the Reply-to address or adding more CC and BCC lines.
>  
> +NOTE: If you're not sure who to CC, use `contrib/contacts/git-contacts` to get a
> +list of reviewers you should include in the CC list. In addition, you can do

I just realized that I could also do s/should/could here, but I assume
you'd prefer to modify in-place instead of me rerolling for a v4 just
for this change. Thanks.

Re: [PATCH v3 1/8] MyFirstContribution: mention contrib/contacts/git-contacts

[Junio C Hamano]

Linus Arver <linusa@google.com> writes:

>> +NOTE: If you're not sure who to CC, use `contrib/contacts/git-contacts` to get a
>> +list of reviewers you should include in the CC list. In addition, you can do
>
> I just realized that I could also do s/should/could here, but I assume
> you'd prefer to modify in-place instead of me rerolling for a v4 just
> for this change. Thanks.

We do not even know if there are other things people find issues
with in this iteration, so it is a bit too early to say that.  In a
case like this, if you do not feel so strongly about it (which I am
guessing from your "I could also") either way, staying mum would
probably be the best.  If you feel more strongly than that, saying
"I plan to update 'should' -> 'could' if I end up doing v4" right
now would be fine.  Then when there are other things you'd need to
update after waiting for others' input, you could keep that promise.
If there are no other things you'd want to update after waiting,
that would be the good time to say "Here is a fixup! commit; squash
into topic X. There is no other changes".

For now, I inserted this extra commit between [1/8] and [2/8].
Thanks.

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 00f4c63cb9..bb7e4174e8 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1116,8 +1116,8 @@ $ git send-email --to=target@example.com psuh/*.patch
 NOTE: Check `git help send-email` for some other options which you may find
 valuable, such as changing the Reply-to address or adding more CC and BCC lines.
 
-NOTE: If you're not sure who to CC, use `contrib/contacts/git-contacts` to get a
-list of reviewers you should include in the CC list. In addition, you can do
+NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts`
+can list potential reviewers to put on the CC list. In addition, you can do
 `git send-email --cc-cmd='git contacts' feature/*.patch` to automatically pass
 this list of emails to `send-email`.
 

Re: [PATCH v3 1/8] MyFirstContribution: mention contrib/contacts/git-contacts

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> Linus Arver <linusa@google.com> writes:
>
>>> +NOTE: If you're not sure who to CC, use `contrib/contacts/git-contacts` to get a
>>> +list of reviewers you should include in the CC list. In addition, you can do
>>
>> I just realized that I could also do s/should/could here, but I assume
>> you'd prefer to modify in-place instead of me rerolling for a v4 just
>> for this change. Thanks.
>
> We do not even know if there are other things people find issues
> with in this iteration, so it is a bit too early to say that.

True.

FTR I should have added "I don't want to reroll this right now so soon
to correct just this error, seems a bit premature" because that's what I
meant to convey.

> In a
> case like this, if you do not feel so strongly about it (which I am
> guessing from your "I could also") either way, staying mum would
> probably be the best.

Ack.

> If you feel more strongly than that, saying
> "I plan to update 'should' -> 'could' if I end up doing v4" right
> now would be fine.

In hindsight this is what I shoould have said.

> Then when there are other things you'd need to
> update after waiting for others' input, you could keep that promise.
> If there are no other things you'd want to update after waiting,
> that would be the good time to say "Here is a fixup! commit; squash
> into topic X. There is no other changes".

Makes sense, thanks. I need to set up `send-email` so that I can start
sending individual patches like in your hypothetical scenario (I don't
know how to do that with GGG, or if it is even possible).

> For now, I inserted this extra commit between [1/8] and [2/8].
> Thanks.
>
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index 00f4c63cb9..bb7e4174e8 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -1116,8 +1116,8 @@ $ git send-email --to=target@example.com psuh/*.patch
>  NOTE: Check `git help send-email` for some other options which you may find
>  valuable, such as changing the Reply-to address or adding more CC and BCC lines.
>  
> -NOTE: If you're not sure who to CC, use `contrib/contacts/git-contacts` to get a
> -list of reviewers you should include in the CC list. In addition, you can do
> +NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts`
> +can list potential reviewers to put on the CC list. In addition, you can do

Nice. I think you can also remove the trailing "to put on the CC list"
clause because it's somewehat redundant.

Re: [PATCH v3 1/8] MyFirstContribution: mention contrib/contacts/git-contacts

[Linus Arver]

Linus Arver <linusa@google.com> writes:

> Junio C Hamano <gitster@pobox.com> writes:
> [...]
>> For now, I inserted this extra commit between [1/8] and [2/8].
>> Thanks.
>>
>> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
>> index 00f4c63cb9..bb7e4174e8 100644
>> --- a/Documentation/MyFirstContribution.txt
>> +++ b/Documentation/MyFirstContribution.txt
>> @@ -1116,8 +1116,8 @@ $ git send-email --to=target@example.com psuh/*.patch
>>  NOTE: Check `git help send-email` for some other options which you may find
>>  valuable, such as changing the Reply-to address or adding more CC and BCC lines.
>>  
>> -NOTE: If you're not sure who to CC, use `contrib/contacts/git-contacts` to get a
>> -list of reviewers you should include in the CC list. In addition, you can do
>> +NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts`
>> +can list potential reviewers to put on the CC list. In addition, you can do
>
> Nice. I think you can also remove the trailing "to put on the CC list"
> clause because it's somewehat redundant.

I will incorporate this into the next reroll.

[PATCH v3 2/8] SubmittingPatches: make 'git contacts' grep-friendly

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Avoid splitting up the command over two lines. This way, a command like

    $ git grep git.contacts Documentation

will return a positive hit for this location.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index e734a3f0f17..a33fe7e11f6 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -494,8 +494,8 @@ mentioned below, but should instead be sent privately to the Git
 Security mailing list{security-ml-ref}.
 
 Send your patch with "To:" set to the mailing list, with "cc:" listing
-people who are involved in the area you are touching (the `git
-contacts` command in `contrib/contacts/` can help to
+people who are involved in the area you are touching (the `git contacts`
+command in `contrib/contacts/` can help to
 identify them), to solicit comments and reviews.  Also, when you made
 trial merges of your topic to `next` and `seen`, you may have noticed
 work by others conflicting with your changes.  There is a good possibility
-- 
gitgitgadget

[PATCH v3 3/8] SubmittingPatches: mention GitGitGadget

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index a33fe7e11f6..c1933c97cb7 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -408,6 +408,10 @@ are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
 type e-mails) might render your patches unusable.
 
+NOTE: Here we outline the procedure using `format-patch` and
+`send-email`, but you can instead use GitGitGadget to send in your
+patches (see link:MyFirstContribution.html[MyFirstContribution]).
+
 People on the Git mailing list need to be able to read and
 comment on the changes you are submitting.  It is important for
 a developer to be able to "quote" your changes, using standard
-- 
gitgitgadget

[PATCH v3 4/8] SubmittingPatches: quote commands

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index c1933c97cb7..8594a3dda36 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -403,7 +403,7 @@ Before sending any patches, please note that patches that may be
 security relevant should be submitted privately to the Git Security
 mailing list{security-ml}, instead of the public mailing list.
 
-Learn to use format-patch and send-email if possible.  These commands
+Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
 type e-mails) might render your patches unusable.
-- 
gitgitgadget

[PATCH v3 5/8] SubmittingPatches: discuss reviewers first

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

No matter how well someone configures their email tooling, understanding
who to send the patches to is something that must always be considered.
So discuss it first instead of at the end.

In the following commit we will clean up the (now redundant) discussion
about sending security patches to the Git Security mailing list.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 58 +++++++++++++++++----------------
 1 file changed, 30 insertions(+), 28 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 8594a3dda36..392bbccc452 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -397,6 +397,36 @@ letter.
 [[send-patches]]
 === Sending your patches.
 
+==== Choosing your reviewers
+
+:security-ml-ref: footnoteref:[security-ml]
+
+As mentioned at the beginning of the section, patches that may be
+security relevant should not be submitted to the public mailing list
+mentioned below, but should instead be sent privately to the Git
+Security mailing list{security-ml-ref}.
+
+Send your patch with "To:" set to the mailing list, with "cc:" listing
+people who are involved in the area you are touching (the `git contacts`
+command in `contrib/contacts/` can help to
+identify them), to solicit comments and reviews.  Also, when you made
+trial merges of your topic to `next` and `seen`, you may have noticed
+work by others conflicting with your changes.  There is a good possibility
+that these people may know the area you are touching well.
+
+:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
+:git-ml: footnote:[The mailing list: git@vger.kernel.org]
+
+After the list reached a consensus that it is a good idea to apply the
+patch, re-send it with "To:" set to the maintainer{current-maintainer}
+and "cc:" the list{git-ml} for inclusion.  This is especially relevant
+when the maintainer did not heavily participate in the discussion and
+instead left the review to trusted others.
+
+Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
+`Tested-by:` lines as necessary to credit people who helped your
+patch, and "cc:" them when sending such a final version for inclusion.
+
 :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
 
 Before sending any patches, please note that patches that may be
@@ -490,34 +520,6 @@ patch, format it as "multipart/signed", not a text/plain message
 that starts with `-----BEGIN PGP SIGNED MESSAGE-----`.  That is
 not a text/plain, it's something else.
 
-:security-ml-ref: footnoteref:[security-ml]
-
-As mentioned at the beginning of the section, patches that may be
-security relevant should not be submitted to the public mailing list
-mentioned below, but should instead be sent privately to the Git
-Security mailing list{security-ml-ref}.
-
-Send your patch with "To:" set to the mailing list, with "cc:" listing
-people who are involved in the area you are touching (the `git contacts`
-command in `contrib/contacts/` can help to
-identify them), to solicit comments and reviews.  Also, when you made
-trial merges of your topic to `next` and `seen`, you may have noticed
-work by others conflicting with your changes.  There is a good possibility
-that these people may know the area you are touching well.
-
-:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
-:git-ml: footnote:[The mailing list: git@vger.kernel.org]
-
-After the list reached a consensus that it is a good idea to apply the
-patch, re-send it with "To:" set to the maintainer{current-maintainer}
-and "cc:" the list{git-ml} for inclusion.  This is especially relevant
-when the maintainer did not heavily participate in the discussion and
-instead left the review to trusted others.
-
-Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
-`Tested-by:` lines as necessary to credit people who helped your
-patch, and "cc:" them when sending such a final version for inclusion.
-
 == Subsystems with dedicated maintainers
 
 Some parts of the system have dedicated maintainers with their own
-- 
gitgitgadget

Re: [PATCH v3 5/8] SubmittingPatches: discuss reviewers first

[Eric Sunshine]

On Tue, Apr 9, 2024 at 5:57 PM Linus Arver via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> No matter how well someone configures their email tooling, understanding
> who to send the patches to is something that must always be considered.
> So discuss it first instead of at the end.
>
> In the following commit we will clean up the (now redundant) discussion
> about sending security patches to the Git Security mailing list.
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> @@ -397,6 +397,36 @@ letter.
> +After the list reached a consensus that it is a good idea to apply the
> +patch, re-send it with "To:" set to the maintainer{current-maintainer}
> +and "cc:" the list{git-ml} for inclusion.  This is especially relevant
> +when the maintainer did not heavily participate in the discussion and
> +instead left the review to trusted others.

This isn't a new problem since you're merely relocating this text
(thus, very likely may be outside the scope of this series), but is
this recommendation still accurate? Although I'm unable to locate it
in the mailing list, I have some vague recollection of Junio
relatively recently wondering why a patch series had been resent with
no changes and why he had been made the direct To: recipient. It
turned out that the author was following the above instructions.

Generally speaking, Junio is quite good at picking up a patch series
without the author having to follow these instructions to resend a
patch series with no changes other than the To: header, so such
instructions place unnecessary burden upon both submitters as well as
reviewers (who have to spend extra cycles wondering why a series was
rerolled and whether any changes were made).

It would probably be more helpful (and less wasteful of reviewer time)
to instruct the patch submitter to monitor "What's Cooking" and
Junio's "seen" branch, and to ping the list (after a week or two) if
the patch series hasn't been picked up or seen any response.

> +Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
> +`Tested-by:` lines as necessary to credit people who helped your
> +patch, and "cc:" them when sending such a final version for inclusion.

Again, not a new problem introduced by this patch, but it seems like
all of these are actively wrong. In every case, these trailers are
_given_ by reviewers _after_ a series has been submitted (thus, too
late for the author to add them), and Junio typically is the one who
latches the Reviewed-by:, Acked-by:, etc. by adding the trailer to the
patches already in his tree.

Instead of the above, much more useful trailers that a patch author
can add are Helped-by: and Reported-by:.

Re: [PATCH v3 5/8] SubmittingPatches: discuss reviewers first

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

>> +Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
>> +`Tested-by:` lines as necessary to credit people who helped your
>> +patch, and "cc:" them when sending such a final version for inclusion.
>
> Again, not a new problem introduced by this patch, but it seems like
> all of these are actively wrong. In every case, these trailers are
> _given_ by reviewers _after_ a series has been submitted (thus, too
> late for the author to add them), ...

Well, this is another instance that I may be trying to be too
helpful and over extending myself, which does not make the process
scale well (the other one being the "one final resend after the
list reached a consensus").

If the authors collect Acks and Reviewed-by's and resend after the
list reached the concensus, it may take one extra iteration, but I
no longer have to keep track of these trailers myself, which could
be a big win.

So, I dunno.

Re: [PATCH v3 5/8] SubmittingPatches: discuss reviewers first

[Linus Arver]

Eric Sunshine <sunshine@sunshineco.com> writes:

> On Tue, Apr 9, 2024 at 5:57 PM Linus Arver via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>> No matter how well someone configures their email tooling, understanding
>> who to send the patches to is something that must always be considered.
>> So discuss it first instead of at the end.
>>
>> In the following commit we will clean up the (now redundant) discussion
>> about sending security patches to the Git Security mailing list.
>>
>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
>> @@ -397,6 +397,36 @@ letter.
>> +After the list reached a consensus that it is a good idea to apply the
>> +patch, re-send it with "To:" set to the maintainer{current-maintainer}
>> +and "cc:" the list{git-ml} for inclusion.  This is especially relevant
>> +when the maintainer did not heavily participate in the discussion and
>> +instead left the review to trusted others.
>
> This isn't a new problem since you're merely relocating this text
> (thus, very likely may be outside the scope of this series), but is
> this recommendation still accurate?

I don't have much history on this list to know one way or the other, but
it would certainly help to double-check all of the advice contained in
here for accuracy. 

I also think that we need to add some more structure to the
SubmittingPatches doc. It is currently pretty long and could use some
help in being broken up a bit more. 

One thing I noticed while drafting this series was that we don't really
separate minutiae from what is _really_ important. For example even the
advice around adding "Acked-by:" and other trailers --- is it really
critical? Other than the "Signed-off-by: " of the patch author (required
for legal reasons), it's not the end of the world if someone forgot to
add a "Reviewed-by: ". We should do a better job of separating
absolutely critical things that must be done correctly to ensure smooth
function of the review process, from the rest that are not so important.

[PATCH v3 6/8] SubmittingPatches: dedupe discussion of security patches

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 392bbccc452..98ec8170aeb 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -399,12 +399,11 @@ letter.
 
 ==== Choosing your reviewers
 
-:security-ml-ref: footnoteref:[security-ml]
+:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
 
-As mentioned at the beginning of the section, patches that may be
-security relevant should not be submitted to the public mailing list
-mentioned below, but should instead be sent privately to the Git
-Security mailing list{security-ml-ref}.
+NOTE: Patches that may be
+security relevant should be submitted privately to the Git Security
+mailing list{security-ml}, instead of the public mailing list.
 
 Send your patch with "To:" set to the mailing list, with "cc:" listing
 people who are involved in the area you are touching (the `git contacts`
@@ -427,12 +426,6 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
 `Tested-by:` lines as necessary to credit people who helped your
 patch, and "cc:" them when sending such a final version for inclusion.
 
-:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
-
-Before sending any patches, please note that patches that may be
-security relevant should be submitted privately to the Git Security
-mailing list{security-ml}, instead of the public mailing list.
-
 Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
-- 
gitgitgadget

[PATCH v3 7/8] SubmittingPatches: add heading for format-patch and send-email

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 98ec8170aeb..bafb1ee0157 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -426,6 +426,8 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
 `Tested-by:` lines as necessary to credit people who helped your
 patch, and "cc:" them when sending such a final version for inclusion.
 
+==== `format-patch` and `send-email`
+
 Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
-- 
gitgitgadget

[PATCH v3 8/8] SubmittingPatches: demonstrate using git-contacts with git-send-email

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index bafb1ee0157..57953898cee 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -413,6 +413,13 @@ trial merges of your topic to `next` and `seen`, you may have noticed
 work by others conflicting with your changes.  There is a good possibility
 that these people may know the area you are touching well.
 
+If you are using `send-email`, you can feed it the output of `git contacts` like
+this:
+
+....
+	git send-email --cc-cmd='git contacts' feature/*.patch
+....
+
 :current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
 :git-ml: footnote:[The mailing list: git@vger.kernel.org]
 
-- 
gitgitgadget

Re: [PATCH v3 8/8] SubmittingPatches: demonstrate using git-contacts with git-send-email

[Kipras Melnikovas]

I don't think `git contacts` is available by default?

...
$ git contacts
git: 'contacts' is not a git command. See 'git --help'.
...

...
$ git send-email --to=kipras@kipras.org --cc-cmd='git contacts' 0001-TEMP.patch
0001-TEMP.patch
git: 'contacts' is not a git command. See 'git --help'.
(cc-cmd) failed to close pipe to 'git contacts' at /opt/homebrew/opt/git/libexec/git-core/git-send-email line 2021.
...

Re: [PATCH v3 8/8] SubmittingPatches: demonstrate using git-contacts with git-send-email

[Linus Arver]

Kipras Melnikovas <kipras@kipras.org> writes:

> I don't think `git contacts` is available by default?

Correct. It's a Perl script that lives under contrib/ in the git repo
(it's not part of the core set of default Git subcommands that the "git"
binary is built with). On Ubuntu it lives under
/usr/share/doc/git/contrib/contacts/git-contacts [1].

[1] https://packages.ubuntu.com/focal/amd64/git/filelist

I could add a blurb about this to avoid confusion. Will update.

> ...
> $ git contacts
> git: 'contacts' is not a git command. See 'git --help'.
> ...
>
> ...
> $ git send-email --to=kipras@kipras.org --cc-cmd='git contacts' 0001-TEMP.patch
> 0001-TEMP.patch
> git: 'contacts' is not a git command. See 'git --help'.
> (cc-cmd) failed to close pipe to 'git contacts' at /opt/homebrew/opt/git/libexec/git-core/git-send-email line 2021.
> ...

Re: [PATCH v3 8/8] SubmittingPatches: demonstrate using git-contacts with git-send-email

[Kipras Melnikovas]

>> I don't think `git contacts` is available by default?

> I could add a blurb about this to avoid confusion. Will update.

Thanks, v4 looks good to me.

[PATCH v4 0/8] docs: recommend using contrib/contacts/git-contacts

[Linus Arver via GitGitGadget]

Make git-contacts more prominent in our docs.


Notable changes in v4
=====================

 * Avoid using "should" for guidance around using "git-contacts"
 * Clarify where to find the "git-contacts" script (because it's not a
   default builtin command)


Notable changes in v3
=====================

 * Refer to GitGitGadget via a link to MyFirstContribution (instead of
   sending readers to GGG's homepage directly)
 * Soften the advice for using git-contacts


Notable changes in v2
=====================

 * Improve existing mention of git-contacts in SubmittingPatches (instead of
   adding a separate, entirely new paragraph)
 * Add example usage of integrating git-contacts with git-send-email with
   the latter's --cc-cmd flag.
 * Various smaller fixes to SubmittingPatches

Linus Arver (8):
  MyFirstContribution: mention contrib/contacts/git-contacts
  SubmittingPatches: clarify 'git-contacts' location
  SubmittingPatches: mention GitGitGadget
  SubmittingPatches: quote commands
  SubmittingPatches: discuss reviewers first
  SubmittingPatches: dedupe discussion of security patches
  SubmittingPatches: add heading for format-patch and send-email
  SubmittingPatches: demonstrate using git-contacts with git-send-email

 Documentation/MyFirstContribution.txt | 12 +++++
 Documentation/SubmittingPatches       | 75 ++++++++++++++++-----------
 2 files changed, 57 insertions(+), 30 deletions(-)


base-commit: c2cbfbd2e28cbe27c194d62183b42f27a6a5bb87
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1704%2Flistx%2Freviewers-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1704/listx/reviewers-v4
Pull-Request: https://github.com/gitgitgadget/git/pull/1704

Range-diff vs v3:

 1:  1f65dc5ba3d ! 1:  ad469e4e6db MyFirstContribution: mention contrib/contacts/git-contacts
     @@ Commit message
          git-contacts helper, 2013-07-21), we don't mention it in our
          introductory docs. Do so now.
      
     +    Helped-by: Junio C Hamano <gitster@pobox.com>
          Signed-off-by: Linus Arver <linusa@google.com>
      
       ## Documentation/MyFirstContribution.txt ##
     @@ Documentation/MyFirstContribution.txt: $ git send-email --to=target@example.com
       NOTE: Check `git help send-email` for some other options which you may find
       valuable, such as changing the Reply-to address or adding more CC and BCC lines.
       
     -+NOTE: If you're not sure who to CC, use `contrib/contacts/git-contacts` to get a
     -+list of reviewers you should include in the CC list. In addition, you can do
     -+`git send-email --cc-cmd='git contacts' feature/*.patch` to automatically pass
     -+this list of emails to `send-email`.
     ++:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     ++part of the core `git` binary and must be called separately. Consult your +
     ++package manager to determine where it is located. For example&#44; on Ubuntu-based +
     ++systems it could be installed under +
     ++`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
     ++with `perl ...` if it does not have the executable bit set.]
     ++
     ++NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can
     ++list potential reviewers. In addition, you can do `git send-email
     ++--cc-cmd='/path/to/git-contacts' feature/*.patch`{contrib-scripts} to
     ++automatically pass this list of emails to `send-email`.
      +
       NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
       please don't send your patchset from the tutorial to the real mailing list! For
 2:  6e8b1b50ac5 ! 2:  c43de19d867 SubmittingPatches: make 'git contacts' grep-friendly
     @@ Metadata
      Author: Linus Arver <linusa@google.com>
      
       ## Commit message ##
     -    SubmittingPatches: make 'git contacts' grep-friendly
     +    SubmittingPatches: clarify 'git-contacts' location
      
     -    Avoid splitting up the command over two lines. This way, a command like
     +    Use a dash ("git-contacts", not "git contacts") because the script
     +    is not a core builtin command that is compiled into the `git` binary.
     +    This also puts the script on one line, which should make it easier to
     +    grep for with a loose search query, such as
      
              $ git grep git.contacts Documentation
      
     -    will return a positive hit for this location.
     +    . Also add a footnote to describe where the script could actually be
     +    located, to help readers who may not be familiar with such "contrib"
     +    scripts (and how they are not accessible with the usual "git
     +    <subcommand>" syntax).
      
          Signed-off-by: Linus Arver <linusa@google.com>
      
       ## Documentation/SubmittingPatches ##
     -@@ Documentation/SubmittingPatches: mentioned below, but should instead be sent privately to the Git
     +@@ Documentation/SubmittingPatches: security relevant should not be submitted to the public mailing list
     + mentioned below, but should instead be sent privately to the Git
       Security mailing list{security-ml-ref}.
       
     ++:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     ++part of the core `git` binary and must be called separately. Consult your +
     ++package manager to determine where it is located. For example&#44; on Ubuntu-based +
     ++systems it could be installed under +
     ++`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
     ++with `perl ...` if it does not have the executable bit set.]
     ++
       Send your patch with "To:" set to the mailing list, with "cc:" listing
      -people who are involved in the area you are touching (the `git
      -contacts` command in `contrib/contacts/` can help to
     -+people who are involved in the area you are touching (the `git contacts`
     -+command in `contrib/contacts/` can help to
     ++people who are involved in the area you are touching (the `git-contacts`
     ++script in `contrib/contacts/`{contrib-scripts} can help to
       identify them), to solicit comments and reviews.  Also, when you made
       trial merges of your topic to `next` and `seen`, you may have noticed
       work by others conflicting with your changes.  There is a good possibility
 3:  7f8fdc053f7 = 3:  cd941704176 SubmittingPatches: mention GitGitGadget
 4:  ef26bdb75c5 = 4:  44470a5d70e SubmittingPatches: quote commands
 5:  6f71b1731f2 ! 5:  15f9356ff97 SubmittingPatches: discuss reviewers first
     @@ Documentation/SubmittingPatches: letter.
      +mentioned below, but should instead be sent privately to the Git
      +Security mailing list{security-ml-ref}.
      +
     ++:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     ++part of the core `git` binary and must be called separately. Consult your +
     ++package manager to determine where it is located. For example&#44; on Ubuntu-based +
     ++systems it could be installed under +
     ++`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
     ++with `perl ...` if it does not have the executable bit set.]
     ++
      +Send your patch with "To:" set to the mailing list, with "cc:" listing
     -+people who are involved in the area you are touching (the `git contacts`
     -+command in `contrib/contacts/` can help to
     ++people who are involved in the area you are touching (the `git-contacts`
     ++script in `contrib/contacts/`{contrib-scripts} can help to
      +identify them), to solicit comments and reviews.  Also, when you made
      +trial merges of your topic to `next` and `seen`, you may have noticed
      +work by others conflicting with your changes.  There is a good possibility
     @@ Documentation/SubmittingPatches: patch, format it as "multipart/signed", not a t
      -mentioned below, but should instead be sent privately to the Git
      -Security mailing list{security-ml-ref}.
      -
     +-:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     +-part of the core `git` binary and must be called separately. Consult your +
     +-package manager to determine where it is located. For example&#44; on Ubuntu-based +
     +-systems it could be installed under +
     +-`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
     +-with `perl ...` if it does not have the executable bit set.]
     +-
      -Send your patch with "To:" set to the mailing list, with "cc:" listing
     --people who are involved in the area you are touching (the `git contacts`
     --command in `contrib/contacts/` can help to
     +-people who are involved in the area you are touching (the `git-contacts`
     +-script in `contrib/contacts/`{contrib-scripts} can help to
      -identify them), to solicit comments and reviews.  Also, when you made
      -trial merges of your topic to `next` and `seen`, you may have noticed
      -work by others conflicting with your changes.  There is a good possibility
 6:  f5e44f69941 ! 6:  e889e64bd45 SubmittingPatches: dedupe discussion of security patches
     @@ Documentation/SubmittingPatches: letter.
      +security relevant should be submitted privately to the Git Security
      +mailing list{security-ml}, instead of the public mailing list.
       
     - Send your patch with "To:" set to the mailing list, with "cc:" listing
     - people who are involved in the area you are touching (the `git contacts`
     + :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     + part of the core `git` binary and must be called separately. Consult your +
      @@ Documentation/SubmittingPatches: Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
       `Tested-by:` lines as necessary to credit people who helped your
       patch, and "cc:" them when sending such a final version for inclusion.
 7:  e64fc5c888a = 7:  81556298599 SubmittingPatches: add heading for format-patch and send-email
 8:  4fcab0d3319 = 8:  84b1cf3f914 SubmittingPatches: demonstrate using git-contacts with git-send-email

-- 
gitgitgadget

[PATCH v4 1/8] MyFirstContribution: mention contrib/contacts/git-contacts

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Although we've had this script since 4d06402b1b (contrib: add
git-contacts helper, 2013-07-21), we don't mention it in our
introductory docs. Do so now.

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/MyFirstContribution.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index f06563e9817..de60b3a4fa1 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1116,6 +1116,18 @@ $ git send-email --to=target@example.com psuh/*.patch
 NOTE: Check `git help send-email` for some other options which you may find
 valuable, such as changing the Reply-to address or adding more CC and BCC lines.
 
+:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
+part of the core `git` binary and must be called separately. Consult your +
+package manager to determine where it is located. For example&#44; on Ubuntu-based +
+systems it could be installed under +
+`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
+with `perl ...` if it does not have the executable bit set.]
+
+NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can
+list potential reviewers. In addition, you can do `git send-email
+--cc-cmd='/path/to/git-contacts' feature/*.patch`{contrib-scripts} to
+automatically pass this list of emails to `send-email`.
+
 NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
 please don't send your patchset from the tutorial to the real mailing list! For
 now, you can send it to yourself, to make sure you understand how it will look.
-- 
gitgitgadget

[PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Use a dash ("git-contacts", not "git contacts") because the script
is not a core builtin command that is compiled into the `git` binary.
This also puts the script on one line, which should make it easier to
grep for with a loose search query, such as

    $ git grep git.contacts Documentation

. Also add a footnote to describe where the script could actually be
located, to help readers who may not be familiar with such "contrib"
scripts (and how they are not accessible with the usual "git
<subcommand>" syntax).

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index e734a3f0f17..8b6e4bf0300 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -493,9 +493,16 @@ security relevant should not be submitted to the public mailing list
 mentioned below, but should instead be sent privately to the Git
 Security mailing list{security-ml-ref}.
 
+:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
+part of the core `git` binary and must be called separately. Consult your +
+package manager to determine where it is located. For example&#44; on Ubuntu-based +
+systems it could be installed under +
+`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
+with `perl ...` if it does not have the executable bit set.]
+
 Send your patch with "To:" set to the mailing list, with "cc:" listing
-people who are involved in the area you are touching (the `git
-contacts` command in `contrib/contacts/` can help to
+people who are involved in the area you are touching (the `git-contacts`
+script in `contrib/contacts/`{contrib-scripts} can help to
 identify them), to solicit comments and reviews.  Also, when you made
 trial merges of your topic to `next` and `seen`, you may have noticed
 work by others conflicting with your changes.  There is a good possibility
-- 
gitgitgadget

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> Use a dash ("git-contacts", not "git contacts") because the script
> is not a core builtin command that is compiled into the `git` binary.

Pedantic, but "git mergetool" is how it is spelled even though it is
not a core builtin command and is not compiled into the binary.  The
reason why "git-contacts" is better is because we do not install it
to be usable by user's "git".

    ... because the script is not installed as part of "git"
    toolset.

An obvious alternative of course is to promote "contacts" out of
"contrib/" and install it as part of the standard toolset.  I gave a
brief scan of the script and did not find anything (other than "only
the recent 5 years worth of history matters") that is too specific
to our project and I suspect it should do a reasonable job when run
in any repository/working tree of a git-managed project.

But it is outside the scope of this series.  I'd still welcome the
thought to do that after the dust settles, though.

> This also puts the script on one line, which should make it easier to
> grep for with a loose search query, such as
>
>     $ git grep git.contacts Documentation
>
> . Also add a footnote to describe where the script could actually be

Let's drop ". "; it may leave the previous sentence appear hanging
unterminated, but the capital A that begins a new sentence is a good
enough sign that we finished the previous sentence, isn't it?

> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index e734a3f0f17..8b6e4bf0300 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -493,9 +493,16 @@ security relevant should not be submitted to the public mailing list
>  mentioned below, but should instead be sent privately to the Git
>  Security mailing list{security-ml-ref}.
>  
> +:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
> +part of the core `git` binary and must be called separately. Consult your +
> +package manager to determine where it is located. For example&#44; on Ubuntu-based +
> +systems it could be installed under +
> +`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
> +with `perl ...` if it does not have the executable bit set.]

I wouldn't call anything in /usr/share/doc/ "installed", though.

In the context of _this_ document where the user is working on _git_
project towards submitting patches to _us_, it is far simpler to
drop the above paragraph and tell them how to run the script in
contrib/, e.g.

    $ perl contrib/contacts/git-contacts <args>...

without hinting there is anything platform/distro specific, and
instead to have them all work from our sources.

I am assuming that any user who are reading this part of the
document would have a reasonably recent version of our sources
checked out (after all, they already have a patch or two to send but
they are learning the way to find whom to send them to).

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Eric Sunshine]

On Fri, Apr 12, 2024 at 1:09 PM Junio C Hamano <gitster@pobox.com> wrote:
> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
> > Use a dash ("git-contacts", not "git contacts") because the script
> > is not a core builtin command that is compiled into the `git` binary.
>
> Pedantic, but "git mergetool" is how it is spelled even though it is
> not a core builtin command and is not compiled into the binary.  The
> reason why "git-contacts" is better is because we do not install it
> to be usable by user's "git".
>
>     ... because the script is not installed as part of "git"
>     toolset.
>
> An obvious alternative of course is to promote "contacts" out of
> "contrib/" and install it as part of the standard toolset.  I gave a
> brief scan of the script and did not find anything (other than "only
> the recent 5 years worth of history matters") that is too specific
> to our project and I suspect it should do a reasonable job when run
> in any repository/working tree of a git-managed project.
>
> But it is outside the scope of this series.  I'd still welcome the
> thought to do that after the dust settles, though.

An alternative would be to deprecate and/or remove `git-contacts` from
"contrib" and instead point people at Felipe's `git-related`[1], which
is the direct parent[2] of `git-contacts`, as well as a more
functional drop-in replacement for `git-contacts`.

[1]: https://github.com/felipec/git-related
[2]: https://lore.kernel.org/git/1372590512-21341-1-git-send-email-sunshine@sunshineco.com/

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> An alternative would be to deprecate and/or remove `git-contacts` from
> "contrib" and instead point people at Felipe's `git-related`[1], which
> is the direct parent[2] of `git-contacts`, as well as a more
> functional drop-in replacement for `git-contacts`.

I am not sure it is wise to add an external dependency on a tool
that is not very well known ([1] has only 68 stars), not packaged
for distros [*] and is more or less dormant (the last update was
April last year).

Unless the one we locally carry is vastly inadequate in comparison,
I somehow doubt that it is a better alternative to ask our target
audience to use it, than letting them use git-contacts from in-tree.


[Footnote]

 * "git imerge" and "tig" are what I compare with to use as a
   yardstick, when trying to judge how well-known and easily
   obtainable a package related to us is.

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Linus Arver <linusa@google.com>
>>
>> Use a dash ("git-contacts", not "git contacts") because the script
>> is not a core builtin command that is compiled into the `git` binary.
>
> Pedantic, but "git mergetool" is how it is spelled even though it is
> not a core builtin command and is not compiled into the binary.  The
> reason why "git-contacts" is better is because we do not install it
> to be usable by user's "git".
>
>     ... because the script is not installed as part of "git"
>     toolset.

Noted; I will use this wording.

> An obvious alternative of course is to promote "contacts" out of
> "contrib/" and install it as part of the standard toolset.  I gave a
> brief scan of the script and did not find anything (other than "only
> the recent 5 years worth of history matters") that is too specific
> to our project and I suspect it should do a reasonable job when run
> in any repository/working tree of a git-managed project.
>
> But it is outside the scope of this series.  I'd still welcome the
> thought to do that after the dust settles, though.

Ack. Ideally we would translate it to C (or, dare I say, into a C lib +
some other higher level language, Perl or otherwise), but I agree that's
for another series.

>> This also puts the script on one line, which should make it easier to
>> grep for with a loose search query, such as
>>
>>     $ git grep git.contacts Documentation
>>
>> . Also add a footnote to describe where the script could actually be
>
> Let's drop ". "

Will do.

> ; it may leave the previous sentence appear hanging
> unterminated, but the capital A that begins a new sentence is a good
> enough sign that we finished the previous sentence, isn't it?

In hindsight I agree. From a quick Google search [1] it looks like your
style is what's preferred in academia also.

>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
>> index e734a3f0f17..8b6e4bf0300 100644
>> --- a/Documentation/SubmittingPatches
>> +++ b/Documentation/SubmittingPatches
>> @@ -493,9 +493,16 @@ security relevant should not be submitted to the public mailing list
>>  mentioned below, but should instead be sent privately to the Git
>>  Security mailing list{security-ml-ref}.
>>  
>> +:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
>> +part of the core `git` binary and must be called separately. Consult your +
>> +package manager to determine where it is located. For example&#44; on Ubuntu-based +
>> +systems it could be installed under +
>> +`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
>> +with `perl ...` if it does not have the executable bit set.]
>
> I wouldn't call anything in /usr/share/doc/ "installed", though.
>
> In the context of _this_ document where the user is working on _git_
> project towards submitting patches to _us_, it is far simpler to
> drop the above paragraph and tell them how to run the script in
> contrib/, e.g.
>
>     $ perl contrib/contacts/git-contacts <args>...
>
> without hinting there is anything platform/distro specific, and
> instead to have them all work from our sources.

Indeed. One small change is that the script already has the execute bit
set so I can drop `perl` as $0 (the execute bit is removed when it is
copied into /usr/share/... on my system).

> I am assuming that any user who are reading this part of the
> document would have a reasonably recent version of our sources
> checked out (after all, they already have a patch or two to send but
> they are learning the way to find whom to send them to).

Agreed.

[1] https://camosun.libguides.com/Chicago-17thEd/quotations

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Junio C Hamano]

Linus Arver <linusa@google.com> writes:

>> In the context of _this_ document where the user is working on _git_
>> project towards submitting patches to _us_, it is far simpler to
>> drop the above paragraph and tell them how to run the script in
>> contrib/, e.g.
>>
>>     $ perl contrib/contacts/git-contacts <args>...
>>
>> without hinting there is anything platform/distro specific, and
>> instead to have them all work from our sources.
>
> Indeed. One small change is that the script already has the execute bit
> set so I can drop `perl` as $0 (the execute bit is removed when it is
> copied into /usr/share/... on my system).

We want to be a bit careful here, though.

The script begins with "#!/usr/bin/perl", but on some systems ther
eis no such command (but /usr/local/bin is on user's PATH and perl
exists there).

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> Linus Arver <linusa@google.com> writes:
>
>>> In the context of _this_ document where the user is working on _git_
>>> project towards submitting patches to _us_, it is far simpler to
>>> drop the above paragraph and tell them how to run the script in
>>> contrib/, e.g.
>>>
>>>     $ perl contrib/contacts/git-contacts <args>...
>>>
>>> without hinting there is anything platform/distro specific, and
>>> instead to have them all work from our sources.
>>
>> Indeed. One small change is that the script already has the execute bit
>> set so I can drop `perl` as $0 (the execute bit is removed when it is
>> copied into /usr/share/... on my system).
>
> We want to be a bit careful here, though.
>
> The script begins with "#!/usr/bin/perl", but on some systems ther
> eis no such command (but /usr/local/bin is on user's PATH and perl
> exists there).

Doh, I already sent a v5. Sorry about that. <wears cone of shame>

Anyway, should I do something like "#!/usr/bin/env perl" or similar as
another patch? It should be more portable than the hardcoded path we
have to /usr/bin/perl.

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Junio C Hamano]

Linus Arver <linusa@google.com> writes:

> Anyway, should I do something like "#!/usr/bin/env perl" or similar as
> another patch? It should be more portable than the hardcoded path we
> have to /usr/bin/perl.

The project preference always has been to replace #!/usr/bin/$prog
when installing to match the system's path, without having to assume
that "env" is available and is installed in /usr/bin/

We are not installing this thing (yet), so how about giving an
instruction to run "perl contrib/contacts/git-contacts", only
assuming that the user is intelligent enough to be able to react to
"perl: not found" by installing it on their path?

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> We are not installing this thing (yet), so how about giving an
> instruction to run "perl contrib/contacts/git-contacts", only
> assuming that the user is intelligent enough to be able to react to
> "perl: not found" by installing it on their path?

That is, something like this, perhaps.

As the string given to --cc-cmd is stored in $cc_cmd, and is used in
this call:

	push @cc, recipients_cmd("cc-cmd", "cc", $cc_cmd, $t, $quiet)

where recipients_cmd takes ($prefix, $what, $cmd, $file, $quiet) and
runs execute_cmd($prefix, $cmd, $file).  execute_cmd in turn takes
($prefix, $cmd, $file) and does this:

	open my $fh, "-|", "$cmd \Q$file\E"
		or die sprintf(__("(%s) Could not execute '%s'"), $prefix, $cmd);

IOW, $cmd is just an early part of a shell command line that takes a
filename as its last argument, so I think it would be fine for $cmd
to be "perl contrib/contacts/git-contacts".  I did not test it, and
it would be appreciated if people can test it.



 Documentation/MyFirstContribution.txt | 6 +++---
 Documentation/SubmittingPatches       | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git c/Documentation/MyFirstContribution.txt w/Documentation/MyFirstContribution.txt
index 9665951aeb..9eb6b98a82 100644
--- c/Documentation/MyFirstContribution.txt
+++ w/Documentation/MyFirstContribution.txt
@@ -1118,12 +1118,12 @@ valuable, such as changing the Reply-to address or adding more CC and BCC lines.
 
 :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
 not part of the core `git` binary and must be called directly. Clone the Git +
-codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
-in your system).]
+codebase and run `perl contrib/contacts/git-contacts` (you must have Perl +
+installed in your system).]
 
 NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can
 list potential reviewers. In addition, you can do `git send-email
---cc-cmd='contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to
+--cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to
 automatically pass this list of emails to `send-email`.
 
 NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
diff --git c/Documentation/SubmittingPatches w/Documentation/SubmittingPatches
index b616422197..1099040d7e 100644
--- c/Documentation/SubmittingPatches
+++ w/Documentation/SubmittingPatches
@@ -407,8 +407,8 @@ mailing list{security-ml}, instead of the public mailing list.
 
 :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
 not part of the core `git` binary and must be called directly. Clone the Git +
-codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
-in your system).]
+codebase and run `perl contrib/contacts/git-contacts` (you must have Perl +
+installed in your system).]
 
 Send your patch with "To:" set to the mailing list, with "cc:" listing
 people who are involved in the area you are touching (the `git-contacts`
@@ -422,7 +422,7 @@ If you are using `send-email`, you can feed it the output of `git-contacts` like
 this:
 
 ....
-	git send-email --cc-cmd='contrib/contacts/git-contacts' feature/*.patch
+	git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch
 ....
 
 :current-maintainer: footnote:[The current maintainer: gitster@pobox.com]

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Eric Sunshine]

On Wed, Apr 17, 2024 at 1:38 AM Junio C Hamano <gitster@pobox.com> wrote:
> IOW, $cmd is just an early part of a shell command line that takes a
> filename as its last argument, so I think it would be fine for $cmd
> to be "perl contrib/contacts/git-contacts".  I did not test it, and
> it would be appreciated if people can test it.
>
> diff --git c/Documentation/MyFirstContribution.txt w/Documentation/MyFirstContribution.txt
> @@ -1118,12 +1118,12 @@ valuable, such as changing the Reply-to address or adding more CC and BCC lines.
> -codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
> -in your system).]
> +codebase and run `perl contrib/contacts/git-contacts` (you must have Perl +
> +installed in your system).]

I wonder if we really need to hand-hold so much to tell people that
they must have Perl installed, especially since the command being run
_is_ `perl`. It might be sufficient simply to say:

    ... codebase and run `perl contrib/contacts/git-contacts`.]

Anyhow, it's a minor point.

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

>> @@ -1118,12 +1118,12 @@ valuable, such as changing the Reply-to address or adding more CC and BCC lines.
>> -codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
>> -in your system).]
>> +codebase and run `perl contrib/contacts/git-contacts` (you must have Perl +
>> +installed in your system).]
>
> I wonder if we really need to hand-hold so much to tell people that
> they must have Perl installed, especially since the command being run
> _is_ `perl`. It might be sufficient simply to say:
>
>     ... codebase and run `perl contrib/contacts/git-contacts`.]
>
> Anyhow, it's a minor point.

True.  In the original it was a good idea, but once we show the
invocation that is explicitly done with 'perl', we no longer need to
say that.

Thanks.

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> Eric Sunshine <sunshine@sunshineco.com> writes:
>
>>> @@ -1118,12 +1118,12 @@ valuable, such as changing the Reply-to address or adding more CC and BCC lines.
>>> -codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
>>> -in your system).]
>>> +codebase and run `perl contrib/contacts/git-contacts` (you must have Perl +
>>> +installed in your system).]
>>
>> I wonder if we really need to hand-hold so much to tell people that
>> they must have Perl installed, especially since the command being run
>> _is_ `perl`. It might be sufficient simply to say:
>>
>>     ... codebase and run `perl contrib/contacts/git-contacts`.]
>>
>> Anyhow, it's a minor point.
>
> True.  In the original it was a good idea, but once we show the
> invocation that is explicitly done with 'perl', we no longer need to
> say that.
>

Agreed. Will update (but will first try to test the 'perl ...' arg to
--cc-cmd).

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> We are not installing this thing (yet), so how about giving an
>> instruction to run "perl contrib/contacts/git-contacts", only
>> assuming that the user is intelligent enough to be able to react to
>> "perl: not found" by installing it on their path?
>
> That is, something like this, perhaps.
>
> As the string given to --cc-cmd is stored in $cc_cmd, and is used in
> this call:
>
> 	push @cc, recipients_cmd("cc-cmd", "cc", $cc_cmd, $t, $quiet)
>
> where recipients_cmd takes ($prefix, $what, $cmd, $file, $quiet) and
> runs execute_cmd($prefix, $cmd, $file).  execute_cmd in turn takes
> ($prefix, $cmd, $file) and does this:
>
> 	open my $fh, "-|", "$cmd \Q$file\E"
> 		or die sprintf(__("(%s) Could not execute '%s'"), $prefix, $cmd);
>
> IOW, $cmd is just an early part of a shell command line that takes a
> filename as its last argument, so I think it would be fine for $cmd
> to be "perl contrib/contacts/git-contacts".  I did not test it, and
> it would be appreciated if people can test it.

I should be able to test this later this week.

Re: [PATCH v4 2/8] SubmittingPatches: clarify 'git-contacts' location

[Linus Arver]

Linus Arver <linusa@google.com> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> We are not installing this thing (yet), so how about giving an
>>> instruction to run "perl contrib/contacts/git-contacts", only
>>> assuming that the user is intelligent enough to be able to react to
>>> "perl: not found" by installing it on their path?
>>
>> That is, something like this, perhaps.
>>
>> As the string given to --cc-cmd is stored in $cc_cmd, and is used in
>> this call:
>>
>> 	push @cc, recipients_cmd("cc-cmd", "cc", $cc_cmd, $t, $quiet)
>>
>> where recipients_cmd takes ($prefix, $what, $cmd, $file, $quiet) and
>> runs execute_cmd($prefix, $cmd, $file).  execute_cmd in turn takes
>> ($prefix, $cmd, $file) and does this:
>>
>> 	open my $fh, "-|", "$cmd \Q$file\E"
>> 		or die sprintf(__("(%s) Could not execute '%s'"), $prefix, $cmd);
>>
>> IOW, $cmd is just an early part of a shell command line that takes a
>> filename as its last argument, so I think it would be fine for $cmd
>> to be "perl contrib/contacts/git-contacts".  I did not test it, and
>> it would be appreciated if people can test it.
>
> I should be able to test this later this week.

Looks like --cc-cmd="perl contrib/contacts/git-contacts" works as
expected! I tested by setting up a working git-send-mail config and
running with --dry-run to check the CC list.

Will reroll later today. Cheers.

[PATCH v4 3/8] SubmittingPatches: mention GitGitGadget

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 8b6e4bf0300..2226c09e6c5 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -408,6 +408,10 @@ are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
 type e-mails) might render your patches unusable.
 
+NOTE: Here we outline the procedure using `format-patch` and
+`send-email`, but you can instead use GitGitGadget to send in your
+patches (see link:MyFirstContribution.html[MyFirstContribution]).
+
 People on the Git mailing list need to be able to read and
 comment on the changes you are submitting.  It is important for
 a developer to be able to "quote" your changes, using standard
-- 
gitgitgadget

[PATCH v4 4/8] SubmittingPatches: quote commands

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 2226c09e6c5..f1c0d1483bd 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -403,7 +403,7 @@ Before sending any patches, please note that patches that may be
 security relevant should be submitted privately to the Git Security
 mailing list{security-ml}, instead of the public mailing list.
 
-Learn to use format-patch and send-email if possible.  These commands
+Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
 type e-mails) might render your patches unusable.
-- 
gitgitgadget

[PATCH v4 5/8] SubmittingPatches: discuss reviewers first

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

No matter how well someone configures their email tooling, understanding
who to send the patches to is something that must always be considered.
So discuss it first instead of at the end.

In the following commit we will clean up the (now redundant) discussion
about sending security patches to the Git Security mailing list.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 72 +++++++++++++++++----------------
 1 file changed, 37 insertions(+), 35 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index f1c0d1483bd..8805579a36e 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -397,6 +397,43 @@ letter.
 [[send-patches]]
 === Sending your patches.
 
+==== Choosing your reviewers
+
+:security-ml-ref: footnoteref:[security-ml]
+
+As mentioned at the beginning of the section, patches that may be
+security relevant should not be submitted to the public mailing list
+mentioned below, but should instead be sent privately to the Git
+Security mailing list{security-ml-ref}.
+
+:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
+part of the core `git` binary and must be called separately. Consult your +
+package manager to determine where it is located. For example&#44; on Ubuntu-based +
+systems it could be installed under +
+`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
+with `perl ...` if it does not have the executable bit set.]
+
+Send your patch with "To:" set to the mailing list, with "cc:" listing
+people who are involved in the area you are touching (the `git-contacts`
+script in `contrib/contacts/`{contrib-scripts} can help to
+identify them), to solicit comments and reviews.  Also, when you made
+trial merges of your topic to `next` and `seen`, you may have noticed
+work by others conflicting with your changes.  There is a good possibility
+that these people may know the area you are touching well.
+
+:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
+:git-ml: footnote:[The mailing list: git@vger.kernel.org]
+
+After the list reached a consensus that it is a good idea to apply the
+patch, re-send it with "To:" set to the maintainer{current-maintainer}
+and "cc:" the list{git-ml} for inclusion.  This is especially relevant
+when the maintainer did not heavily participate in the discussion and
+instead left the review to trusted others.
+
+Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
+`Tested-by:` lines as necessary to credit people who helped your
+patch, and "cc:" them when sending such a final version for inclusion.
+
 :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
 
 Before sending any patches, please note that patches that may be
@@ -490,41 +527,6 @@ patch, format it as "multipart/signed", not a text/plain message
 that starts with `-----BEGIN PGP SIGNED MESSAGE-----`.  That is
 not a text/plain, it's something else.
 
-:security-ml-ref: footnoteref:[security-ml]
-
-As mentioned at the beginning of the section, patches that may be
-security relevant should not be submitted to the public mailing list
-mentioned below, but should instead be sent privately to the Git
-Security mailing list{security-ml-ref}.
-
-:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
-part of the core `git` binary and must be called separately. Consult your +
-package manager to determine where it is located. For example&#44; on Ubuntu-based +
-systems it could be installed under +
-`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
-with `perl ...` if it does not have the executable bit set.]
-
-Send your patch with "To:" set to the mailing list, with "cc:" listing
-people who are involved in the area you are touching (the `git-contacts`
-script in `contrib/contacts/`{contrib-scripts} can help to
-identify them), to solicit comments and reviews.  Also, when you made
-trial merges of your topic to `next` and `seen`, you may have noticed
-work by others conflicting with your changes.  There is a good possibility
-that these people may know the area you are touching well.
-
-:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
-:git-ml: footnote:[The mailing list: git@vger.kernel.org]
-
-After the list reached a consensus that it is a good idea to apply the
-patch, re-send it with "To:" set to the maintainer{current-maintainer}
-and "cc:" the list{git-ml} for inclusion.  This is especially relevant
-when the maintainer did not heavily participate in the discussion and
-instead left the review to trusted others.
-
-Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
-`Tested-by:` lines as necessary to credit people who helped your
-patch, and "cc:" them when sending such a final version for inclusion.
-
 == Subsystems with dedicated maintainers
 
 Some parts of the system have dedicated maintainers with their own
-- 
gitgitgadget

[PATCH v4 6/8] SubmittingPatches: dedupe discussion of security patches

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 8805579a36e..ecc1622c8bf 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -399,12 +399,11 @@ letter.
 
 ==== Choosing your reviewers
 
-:security-ml-ref: footnoteref:[security-ml]
+:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
 
-As mentioned at the beginning of the section, patches that may be
-security relevant should not be submitted to the public mailing list
-mentioned below, but should instead be sent privately to the Git
-Security mailing list{security-ml-ref}.
+NOTE: Patches that may be
+security relevant should be submitted privately to the Git Security
+mailing list{security-ml}, instead of the public mailing list.
 
 :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
 part of the core `git` binary and must be called separately. Consult your +
@@ -434,12 +433,6 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
 `Tested-by:` lines as necessary to credit people who helped your
 patch, and "cc:" them when sending such a final version for inclusion.
 
-:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
-
-Before sending any patches, please note that patches that may be
-security relevant should be submitted privately to the Git Security
-mailing list{security-ml}, instead of the public mailing list.
-
 Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
-- 
gitgitgadget

[PATCH v4 7/8] SubmittingPatches: add heading for format-patch and send-email

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index ecc1622c8bf..fd40a444f95 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -433,6 +433,8 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
 `Tested-by:` lines as necessary to credit people who helped your
 patch, and "cc:" them when sending such a final version for inclusion.
 
+==== `format-patch` and `send-email`
+
 Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
-- 
gitgitgadget

[PATCH v4 8/8] SubmittingPatches: demonstrate using git-contacts with git-send-email

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index fd40a444f95..eac086133bc 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -420,6 +420,13 @@ trial merges of your topic to `next` and `seen`, you may have noticed
 work by others conflicting with your changes.  There is a good possibility
 that these people may know the area you are touching well.
 
+If you are using `send-email`, you can feed it the output of `git contacts` like
+this:
+
+....
+	git send-email --cc-cmd='git contacts' feature/*.patch
+....
+
 :current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
 :git-ml: footnote:[The mailing list: git@vger.kernel.org]
 
-- 
gitgitgadget

Re: [PATCH v4 8/8] SubmittingPatches: demonstrate using git-contacts with git-send-email

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Linus Arver <linusa@google.com>
>
> Signed-off-by: Linus Arver <linusa@google.com>
> ---
>  Documentation/SubmittingPatches | 7 +++++++
>  1 file changed, 7 insertions(+)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index fd40a444f95..eac086133bc 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -420,6 +420,13 @@ trial merges of your topic to `next` and `seen`, you may have noticed
>  work by others conflicting with your changes.  There is a good possibility
>  that these people may know the area you are touching well.
>  
> +If you are using `send-email`, you can feed it the output of `git contacts` like
> +this:
> +
> +....
> +	git send-email --cc-cmd='git contacts' feature/*.patch
> +....

Doesn't this contradict with what we said in [2/8]?

>  :current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
>  :git-ml: footnote:[The mailing list: git@vger.kernel.org]

Re: [PATCH v4 8/8] SubmittingPatches: demonstrate using git-contacts with git-send-email

[Linus Arver]

Junio C Hamano <gitster@pobox.com> writes:

> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Linus Arver <linusa@google.com>
>>
>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>>  Documentation/SubmittingPatches | 7 +++++++
>>  1 file changed, 7 insertions(+)
>>
>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
>> index fd40a444f95..eac086133bc 100644
>> --- a/Documentation/SubmittingPatches
>> +++ b/Documentation/SubmittingPatches
>> @@ -420,6 +420,13 @@ trial merges of your topic to `next` and `seen`, you may have noticed
>>  work by others conflicting with your changes.  There is a good possibility
>>  that these people may know the area you are touching well.
>>  
>> +If you are using `send-email`, you can feed it the output of `git contacts` like
>> +this:
>> +
>> +....
>> +	git send-email --cc-cmd='git contacts' feature/*.patch
>> +....
>
> Doesn't this contradict with what we said in [2/8]?

Oops, will update.

[PATCH v5 0/8] docs: recommend using contrib/contacts/git-contacts

[Linus Arver via GitGitGadget]

Make git-contacts more prominent in our docs.


Notable changes in v5
=====================

 * Drop mention of "/usr/share/..." as an "installed" path for
   "git-contacts"; instead point users to the script as a relative path
   inside the Git codebase
 * Minor wording tweaks to commit messages


Notable changes in v4
=====================

 * Avoid using "should" for guidance around using "git-contacts"
 * Clarify where to find the "git-contacts" script (because it's not a
   default builtin command)


Notable changes in v3
=====================

 * Refer to GitGitGadget via a link to MyFirstContribution (instead of
   sending readers to GGG's homepage directly)
 * Soften the advice for using git-contacts


Notable changes in v2
=====================

 * Improve existing mention of git-contacts in SubmittingPatches (instead of
   adding a separate, entirely new paragraph)
 * Add example usage of integrating git-contacts with git-send-email with
   the latter's --cc-cmd flag.
 * Various smaller fixes to SubmittingPatches

Linus Arver (8):
  MyFirstContribution: mention contrib/contacts/git-contacts
  SubmittingPatches: clarify 'git-contacts' location
  SubmittingPatches: mention GitGitGadget
  SubmittingPatches: quote commands
  SubmittingPatches: discuss reviewers first
  SubmittingPatches: dedupe discussion of security patches
  SubmittingPatches: add heading for format-patch and send-email
  SubmittingPatches: demonstrate using git-contacts with git-send-email

 Documentation/MyFirstContribution.txt | 10 ++++
 Documentation/SubmittingPatches       | 73 ++++++++++++++++-----------
 2 files changed, 53 insertions(+), 30 deletions(-)


base-commit: c2cbfbd2e28cbe27c194d62183b42f27a6a5bb87
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1704%2Flistx%2Freviewers-v5
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1704/listx/reviewers-v5
Pull-Request: https://github.com/gitgitgadget/git/pull/1704

Range-diff vs v4:

 1:  ad469e4e6db ! 1:  d2c9551ee0e MyFirstContribution: mention contrib/contacts/git-contacts
     @@ Documentation/MyFirstContribution.txt: $ git send-email --to=target@example.com
       NOTE: Check `git help send-email` for some other options which you may find
       valuable, such as changing the Reply-to address or adding more CC and BCC lines.
       
     -+:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     -+part of the core `git` binary and must be called separately. Consult your +
     -+package manager to determine where it is located. For example, on Ubuntu-based +
     -+systems it could be installed under +
     -+`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
     -+with `perl ...` if it does not have the executable bit set.]
     ++:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
     ++not part of the core `git` binary and must be called directly. Clone the Git +
     ++codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
     ++in your system).]
      +
      +NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can
      +list potential reviewers. In addition, you can do `git send-email
     -+--cc-cmd='/path/to/git-contacts' feature/*.patch`{contrib-scripts} to
     ++--cc-cmd='contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to
      +automatically pass this list of emails to `send-email`.
      +
       NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
 2:  c43de19d867 ! 2:  92d72a8a25a SubmittingPatches: clarify 'git-contacts' location
     @@ Metadata
       ## Commit message ##
          SubmittingPatches: clarify 'git-contacts' location
      
     -    Use a dash ("git-contacts", not "git contacts") because the script
     -    is not a core builtin command that is compiled into the `git` binary.
     -    This also puts the script on one line, which should make it easier to
     -    grep for with a loose search query, such as
     +    Use a dash ("git-contacts", not "git contacts") because the script is
     +    not installed as part of "git" toolset. This also puts the script on
     +    one line, which should make it easier to grep for with a loose search
     +    query, such as
      
              $ git grep git.contacts Documentation
      
     -    . Also add a footnote to describe where the script could actually be
     -    located, to help readers who may not be familiar with such "contrib"
     -    scripts (and how they are not accessible with the usual "git
     -    <subcommand>" syntax).
     +    Also add a footnote to describe where the script is located, to help
     +    readers who may not be familiar with such "contrib" scripts (and how
     +    they are not accessible with the usual "git <subcommand>" syntax).
      
          Signed-off-by: Linus Arver <linusa@google.com>
      
     @@ Documentation/SubmittingPatches: security relevant should not be submitted to th
       mentioned below, but should instead be sent privately to the Git
       Security mailing list{security-ml-ref}.
       
     -+:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     -+part of the core `git` binary and must be called separately. Consult your +
     -+package manager to determine where it is located. For example&#44; on Ubuntu-based +
     -+systems it could be installed under +
     -+`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
     -+with `perl ...` if it does not have the executable bit set.]
     ++:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
     ++not part of the core `git` binary and must be called directly. Clone the Git +
     ++codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
     ++in your system).]
      +
       Send your patch with "To:" set to the mailing list, with "cc:" listing
      -people who are involved in the area you are touching (the `git
 3:  cd941704176 = 3:  7c4cc5a91f0 SubmittingPatches: mention GitGitGadget
 4:  44470a5d70e = 4:  621912a64fb SubmittingPatches: quote commands
 5:  15f9356ff97 ! 5:  8f44343c482 SubmittingPatches: discuss reviewers first
     @@ Documentation/SubmittingPatches: letter.
      +mentioned below, but should instead be sent privately to the Git
      +Security mailing list{security-ml-ref}.
      +
     -+:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     -+part of the core `git` binary and must be called separately. Consult your +
     -+package manager to determine where it is located. For example&#44; on Ubuntu-based +
     -+systems it could be installed under +
     -+`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
     -+with `perl ...` if it does not have the executable bit set.]
     ++:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
     ++not part of the core `git` binary and must be called directly. Clone the Git +
     ++codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
     ++in your system).]
      +
      +Send your patch with "To:" set to the mailing list, with "cc:" listing
      +people who are involved in the area you are touching (the `git-contacts`
     @@ Documentation/SubmittingPatches: patch, format it as "multipart/signed", not a t
      -mentioned below, but should instead be sent privately to the Git
      -Security mailing list{security-ml-ref}.
      -
     --:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     --part of the core `git` binary and must be called separately. Consult your +
     --package manager to determine where it is located. For example&#44; on Ubuntu-based +
     --systems it could be installed under +
     --`/usr/share/doc/git/contrib/contacts/git-contacts` and may need to be called +
     --with `perl ...` if it does not have the executable bit set.]
     +-:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
     +-not part of the core `git` binary and must be called directly. Clone the Git +
     +-codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
     +-in your system).]
      -
      -Send your patch with "To:" set to the mailing list, with "cc:" listing
      -people who are involved in the area you are touching (the `git-contacts`
 6:  e889e64bd45 ! 6:  fd8ad38cab0 SubmittingPatches: dedupe discussion of security patches
     @@ Documentation/SubmittingPatches: letter.
      +security relevant should be submitted privately to the Git Security
      +mailing list{security-ml}, instead of the public mailing list.
       
     - :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are not +
     - part of the core `git` binary and must be called separately. Consult your +
     + :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
     + not part of the core `git` binary and must be called directly. Clone the Git +
      @@ Documentation/SubmittingPatches: Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
       `Tested-by:` lines as necessary to credit people who helped your
       patch, and "cc:" them when sending such a final version for inclusion.
 7:  81556298599 = 7:  b23c73459cc SubmittingPatches: add heading for format-patch and send-email
 8:  84b1cf3f914 ! 8:  911d4f2a0e5 SubmittingPatches: demonstrate using git-contacts with git-send-email
     @@ Documentation/SubmittingPatches: trial merges of your topic to `next` and `seen`
       work by others conflicting with your changes.  There is a good possibility
       that these people may know the area you are touching well.
       
     -+If you are using `send-email`, you can feed it the output of `git contacts` like
     ++If you are using `send-email`, you can feed it the output of `git-contacts` like
      +this:
      +
      +....
     -+	git send-email --cc-cmd='git contacts' feature/*.patch
     ++	git send-email --cc-cmd='contrib/contacts/git-contacts' feature/*.patch
      +....
      +
       :current-maintainer: footnote:[The current maintainer: gitster@pobox.com]

-- 
gitgitgadget

[PATCH v5 1/8] MyFirstContribution: mention contrib/contacts/git-contacts

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Although we've had this script since 4d06402b1b (contrib: add
git-contacts helper, 2013-07-21), we don't mention it in our
introductory docs. Do so now.

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/MyFirstContribution.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index f06563e9817..9665951aeb5 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1116,6 +1116,16 @@ $ git send-email --to=target@example.com psuh/*.patch
 NOTE: Check `git help send-email` for some other options which you may find
 valuable, such as changing the Reply-to address or adding more CC and BCC lines.
 
+:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
+not part of the core `git` binary and must be called directly. Clone the Git +
+codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
+in your system).]
+
+NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can
+list potential reviewers. In addition, you can do `git send-email
+--cc-cmd='contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to
+automatically pass this list of emails to `send-email`.
+
 NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
 please don't send your patchset from the tutorial to the real mailing list! For
 now, you can send it to yourself, to make sure you understand how it will look.
-- 
gitgitgadget

[PATCH v5 2/8] SubmittingPatches: clarify 'git-contacts' location

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Use a dash ("git-contacts", not "git contacts") because the script is
not installed as part of "git" toolset. This also puts the script on
one line, which should make it easier to grep for with a loose search
query, such as

    $ git grep git.contacts Documentation

Also add a footnote to describe where the script is located, to help
readers who may not be familiar with such "contrib" scripts (and how
they are not accessible with the usual "git <subcommand>" syntax).

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index e734a3f0f17..0d4276c6c7e 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -493,9 +493,14 @@ security relevant should not be submitted to the public mailing list
 mentioned below, but should instead be sent privately to the Git
 Security mailing list{security-ml-ref}.
 
+:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
+not part of the core `git` binary and must be called directly. Clone the Git +
+codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
+in your system).]
+
 Send your patch with "To:" set to the mailing list, with "cc:" listing
-people who are involved in the area you are touching (the `git
-contacts` command in `contrib/contacts/` can help to
+people who are involved in the area you are touching (the `git-contacts`
+script in `contrib/contacts/`{contrib-scripts} can help to
 identify them), to solicit comments and reviews.  Also, when you made
 trial merges of your topic to `next` and `seen`, you may have noticed
 work by others conflicting with your changes.  There is a good possibility
-- 
gitgitgadget

[PATCH v5 3/8] SubmittingPatches: mention GitGitGadget

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 0d4276c6c7e..a27f7c923b9 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -408,6 +408,10 @@ are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
 type e-mails) might render your patches unusable.
 
+NOTE: Here we outline the procedure using `format-patch` and
+`send-email`, but you can instead use GitGitGadget to send in your
+patches (see link:MyFirstContribution.html[MyFirstContribution]).
+
 People on the Git mailing list need to be able to read and
 comment on the changes you are submitting.  It is important for
 a developer to be able to "quote" your changes, using standard
-- 
gitgitgadget

[PATCH v5 4/8] SubmittingPatches: quote commands

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index a27f7c923b9..b684bdd03a1 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -403,7 +403,7 @@ Before sending any patches, please note that patches that may be
 security relevant should be submitted privately to the Git Security
 mailing list{security-ml}, instead of the public mailing list.
 
-Learn to use format-patch and send-email if possible.  These commands
+Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
 type e-mails) might render your patches unusable.
-- 
gitgitgadget

[PATCH v5 5/8] SubmittingPatches: discuss reviewers first

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

No matter how well someone configures their email tooling, understanding
who to send the patches to is something that must always be considered.
So discuss it first instead of at the end.

In the following commit we will clean up the (now redundant) discussion
about sending security patches to the Git Security mailing list.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 68 +++++++++++++++++----------------
 1 file changed, 35 insertions(+), 33 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index b684bdd03a1..a110f94db4f 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -397,6 +397,41 @@ letter.
 [[send-patches]]
 === Sending your patches.
 
+==== Choosing your reviewers
+
+:security-ml-ref: footnoteref:[security-ml]
+
+As mentioned at the beginning of the section, patches that may be
+security relevant should not be submitted to the public mailing list
+mentioned below, but should instead be sent privately to the Git
+Security mailing list{security-ml-ref}.
+
+:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
+not part of the core `git` binary and must be called directly. Clone the Git +
+codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
+in your system).]
+
+Send your patch with "To:" set to the mailing list, with "cc:" listing
+people who are involved in the area you are touching (the `git-contacts`
+script in `contrib/contacts/`{contrib-scripts} can help to
+identify them), to solicit comments and reviews.  Also, when you made
+trial merges of your topic to `next` and `seen`, you may have noticed
+work by others conflicting with your changes.  There is a good possibility
+that these people may know the area you are touching well.
+
+:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
+:git-ml: footnote:[The mailing list: git@vger.kernel.org]
+
+After the list reached a consensus that it is a good idea to apply the
+patch, re-send it with "To:" set to the maintainer{current-maintainer}
+and "cc:" the list{git-ml} for inclusion.  This is especially relevant
+when the maintainer did not heavily participate in the discussion and
+instead left the review to trusted others.
+
+Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
+`Tested-by:` lines as necessary to credit people who helped your
+patch, and "cc:" them when sending such a final version for inclusion.
+
 :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
 
 Before sending any patches, please note that patches that may be
@@ -490,39 +525,6 @@ patch, format it as "multipart/signed", not a text/plain message
 that starts with `-----BEGIN PGP SIGNED MESSAGE-----`.  That is
 not a text/plain, it's something else.
 
-:security-ml-ref: footnoteref:[security-ml]
-
-As mentioned at the beginning of the section, patches that may be
-security relevant should not be submitted to the public mailing list
-mentioned below, but should instead be sent privately to the Git
-Security mailing list{security-ml-ref}.
-
-:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
-not part of the core `git` binary and must be called directly. Clone the Git +
-codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
-in your system).]
-
-Send your patch with "To:" set to the mailing list, with "cc:" listing
-people who are involved in the area you are touching (the `git-contacts`
-script in `contrib/contacts/`{contrib-scripts} can help to
-identify them), to solicit comments and reviews.  Also, when you made
-trial merges of your topic to `next` and `seen`, you may have noticed
-work by others conflicting with your changes.  There is a good possibility
-that these people may know the area you are touching well.
-
-:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
-:git-ml: footnote:[The mailing list: git@vger.kernel.org]
-
-After the list reached a consensus that it is a good idea to apply the
-patch, re-send it with "To:" set to the maintainer{current-maintainer}
-and "cc:" the list{git-ml} for inclusion.  This is especially relevant
-when the maintainer did not heavily participate in the discussion and
-instead left the review to trusted others.
-
-Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
-`Tested-by:` lines as necessary to credit people who helped your
-patch, and "cc:" them when sending such a final version for inclusion.
-
 == Subsystems with dedicated maintainers
 
 Some parts of the system have dedicated maintainers with their own
-- 
gitgitgadget

[PATCH v5 6/8] SubmittingPatches: dedupe discussion of security patches

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index a110f94db4f..060c8069c10 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -399,12 +399,11 @@ letter.
 
 ==== Choosing your reviewers
 
-:security-ml-ref: footnoteref:[security-ml]
+:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
 
-As mentioned at the beginning of the section, patches that may be
-security relevant should not be submitted to the public mailing list
-mentioned below, but should instead be sent privately to the Git
-Security mailing list{security-ml-ref}.
+NOTE: Patches that may be
+security relevant should be submitted privately to the Git Security
+mailing list{security-ml}, instead of the public mailing list.
 
 :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
 not part of the core `git` binary and must be called directly. Clone the Git +
@@ -432,12 +431,6 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
 `Tested-by:` lines as necessary to credit people who helped your
 patch, and "cc:" them when sending such a final version for inclusion.
 
-:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
-
-Before sending any patches, please note that patches that may be
-security relevant should be submitted privately to the Git Security
-mailing list{security-ml}, instead of the public mailing list.
-
 Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
-- 
gitgitgadget

[PATCH v5 7/8] SubmittingPatches: add heading for format-patch and send-email

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 060c8069c10..1700132a3a4 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -431,6 +431,8 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
 `Tested-by:` lines as necessary to credit people who helped your
 patch, and "cc:" them when sending such a final version for inclusion.
 
+==== `format-patch` and `send-email`
+
 Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
-- 
gitgitgadget

[PATCH v5 8/8] SubmittingPatches: demonstrate using git-contacts with git-send-email

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 1700132a3a4..b616422197f 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -418,6 +418,13 @@ trial merges of your topic to `next` and `seen`, you may have noticed
 work by others conflicting with your changes.  There is a good possibility
 that these people may know the area you are touching well.
 
+If you are using `send-email`, you can feed it the output of `git-contacts` like
+this:
+
+....
+	git send-email --cc-cmd='contrib/contacts/git-contacts' feature/*.patch
+....
+
 :current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
 :git-ml: footnote:[The mailing list: git@vger.kernel.org]
 
-- 
gitgitgadget

[PATCH v6 0/8] docs: recommend using contrib/contacts/git-contacts

[Linus Arver via GitGitGadget]

Make git-contacts more prominent in our docs.


Notable changes in v6
=====================

 * Prefix the command with "perl" to avoid the need to have it installed at
   /usr/bin/perl per the shebang line in git-contacts.
 * Drop "you must have Perl installed in your system" guidance because it's
   a bit moot now given the explicit call to "perl".


Notable changes in v5
=====================

 * Drop mention of "/usr/share/..." as an "installed" path for
   "git-contacts"; instead point users to the script as a relative path
   inside the Git codebase
 * Minor wording tweaks to commit messages


Notable changes in v4
=====================

 * Avoid using "should" for guidance around using "git-contacts"
 * Clarify where to find the "git-contacts" script (because it's not a
   default builtin command)


Notable changes in v3
=====================

 * Refer to GitGitGadget via a link to MyFirstContribution (instead of
   sending readers to GGG's homepage directly)
 * Soften the advice for using git-contacts


Notable changes in v2
=====================

 * Improve existing mention of git-contacts in SubmittingPatches (instead of
   adding a separate, entirely new paragraph)
 * Add example usage of integrating git-contacts with git-send-email with
   the latter's --cc-cmd flag.
 * Various smaller fixes to SubmittingPatches

Linus Arver (8):
  MyFirstContribution: mention contrib/contacts/git-contacts
  SubmittingPatches: clarify 'git-contacts' location
  SubmittingPatches: mention GitGitGadget
  SubmittingPatches: quote commands
  SubmittingPatches: discuss reviewers first
  SubmittingPatches: dedupe discussion of security patches
  SubmittingPatches: add heading for format-patch and send-email
  SubmittingPatches: demonstrate using git-contacts with git-send-email

 Documentation/MyFirstContribution.txt |  9 ++++
 Documentation/SubmittingPatches       | 72 ++++++++++++++++-----------
 2 files changed, 51 insertions(+), 30 deletions(-)


base-commit: c2cbfbd2e28cbe27c194d62183b42f27a6a5bb87
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1704%2Flistx%2Freviewers-v6
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1704/listx/reviewers-v6
Pull-Request: https://github.com/gitgitgadget/git/pull/1704

Range-diff vs v5:

 1:  d2c9551ee0e ! 1:  4ced981b82e MyFirstContribution: mention contrib/contacts/git-contacts
     @@ Documentation/MyFirstContribution.txt: $ git send-email --to=target@example.com
       
      +:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
      +not part of the core `git` binary and must be called directly. Clone the Git +
     -+codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
     -+in your system).]
     ++codebase and run `perl contrib/contacts/git-contacts`.]
      +
      +NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can
      +list potential reviewers. In addition, you can do `git send-email
     -+--cc-cmd='contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to
     ++--cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to
      +automatically pass this list of emails to `send-email`.
      +
       NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
 2:  92d72a8a25a ! 2:  f26f0695f40 SubmittingPatches: clarify 'git-contacts' location
     @@ Documentation/SubmittingPatches: security relevant should not be submitted to th
       
      +:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
      +not part of the core `git` binary and must be called directly. Clone the Git +
     -+codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
     -+in your system).]
     ++codebase and run `perl contrib/contacts/git-contacts`.]
      +
       Send your patch with "To:" set to the mailing list, with "cc:" listing
      -people who are involved in the area you are touching (the `git
 3:  7c4cc5a91f0 = 3:  c201b313644 SubmittingPatches: mention GitGitGadget
 4:  621912a64fb = 4:  0a79615cf2f SubmittingPatches: quote commands
 5:  8f44343c482 ! 5:  aac5dea0bfa SubmittingPatches: discuss reviewers first
     @@ Documentation/SubmittingPatches: letter.
      +
      +:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
      +not part of the core `git` binary and must be called directly. Clone the Git +
     -+codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
     -+in your system).]
     ++codebase and run `perl contrib/contacts/git-contacts`.]
      +
      +Send your patch with "To:" set to the mailing list, with "cc:" listing
      +people who are involved in the area you are touching (the `git-contacts`
     @@ Documentation/SubmittingPatches: patch, format it as "multipart/signed", not a t
      -
      -:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
      -not part of the core `git` binary and must be called directly. Clone the Git +
     --codebase and run `contrib/contacts/git-contacts` (you must have Perl installed +
     --in your system).]
     +-codebase and run `perl contrib/contacts/git-contacts`.]
      -
      -Send your patch with "To:" set to the mailing list, with "cc:" listing
      -people who are involved in the area you are touching (the `git-contacts`
 6:  fd8ad38cab0 = 6:  333775d4129 SubmittingPatches: dedupe discussion of security patches
 7:  b23c73459cc = 7:  ef031e30047 SubmittingPatches: add heading for format-patch and send-email
 8:  911d4f2a0e5 ! 8:  f346da95ee2 SubmittingPatches: demonstrate using git-contacts with git-send-email
     @@ Documentation/SubmittingPatches: trial merges of your topic to `next` and `seen`
      +this:
      +
      +....
     -+	git send-email --cc-cmd='contrib/contacts/git-contacts' feature/*.patch
     ++	git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch
      +....
      +
       :current-maintainer: footnote:[The current maintainer: gitster@pobox.com]

-- 
gitgitgadget

[PATCH v6 1/8] MyFirstContribution: mention contrib/contacts/git-contacts

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Although we've had this script since 4d06402b1b (contrib: add
git-contacts helper, 2013-07-21), we don't mention it in our
introductory docs. Do so now.

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/MyFirstContribution.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index f06563e9817..e41654c00a6 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1116,6 +1116,15 @@ $ git send-email --to=target@example.com psuh/*.patch
 NOTE: Check `git help send-email` for some other options which you may find
 valuable, such as changing the Reply-to address or adding more CC and BCC lines.
 
+:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
+not part of the core `git` binary and must be called directly. Clone the Git +
+codebase and run `perl contrib/contacts/git-contacts`.]
+
+NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can
+list potential reviewers. In addition, you can do `git send-email
+--cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to
+automatically pass this list of emails to `send-email`.
+
 NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
 please don't send your patchset from the tutorial to the real mailing list! For
 now, you can send it to yourself, to make sure you understand how it will look.
-- 
gitgitgadget

[PATCH v6 2/8] SubmittingPatches: clarify 'git-contacts' location

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Use a dash ("git-contacts", not "git contacts") because the script is
not installed as part of "git" toolset. This also puts the script on
one line, which should make it easier to grep for with a loose search
query, such as

    $ git grep git.contacts Documentation

Also add a footnote to describe where the script is located, to help
readers who may not be familiar with such "contrib" scripts (and how
they are not accessible with the usual "git <subcommand>" syntax).

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index e734a3f0f17..d4173d4fe84 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -493,9 +493,13 @@ security relevant should not be submitted to the public mailing list
 mentioned below, but should instead be sent privately to the Git
 Security mailing list{security-ml-ref}.
 
+:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
+not part of the core `git` binary and must be called directly. Clone the Git +
+codebase and run `perl contrib/contacts/git-contacts`.]
+
 Send your patch with "To:" set to the mailing list, with "cc:" listing
-people who are involved in the area you are touching (the `git
-contacts` command in `contrib/contacts/` can help to
+people who are involved in the area you are touching (the `git-contacts`
+script in `contrib/contacts/`{contrib-scripts} can help to
 identify them), to solicit comments and reviews.  Also, when you made
 trial merges of your topic to `next` and `seen`, you may have noticed
 work by others conflicting with your changes.  There is a good possibility
-- 
gitgitgadget

[PATCH v6 3/8] SubmittingPatches: mention GitGitGadget

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index d4173d4fe84..26055a1fe2b 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -408,6 +408,10 @@ are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
 type e-mails) might render your patches unusable.
 
+NOTE: Here we outline the procedure using `format-patch` and
+`send-email`, but you can instead use GitGitGadget to send in your
+patches (see link:MyFirstContribution.html[MyFirstContribution]).
+
 People on the Git mailing list need to be able to read and
 comment on the changes you are submitting.  It is important for
 a developer to be able to "quote" your changes, using standard
-- 
gitgitgadget

[PATCH v6 4/8] SubmittingPatches: quote commands

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 26055a1fe2b..6b9e954a47d 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -403,7 +403,7 @@ Before sending any patches, please note that patches that may be
 security relevant should be submitted privately to the Git Security
 mailing list{security-ml}, instead of the public mailing list.
 
-Learn to use format-patch and send-email if possible.  These commands
+Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
 type e-mails) might render your patches unusable.
-- 
gitgitgadget

[PATCH v6 5/8] SubmittingPatches: discuss reviewers first

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

No matter how well someone configures their email tooling, understanding
who to send the patches to is something that must always be considered.
So discuss it first instead of at the end.

In the following commit we will clean up the (now redundant) discussion
about sending security patches to the Git Security mailing list.

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 66 +++++++++++++++++----------------
 1 file changed, 34 insertions(+), 32 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 6b9e954a47d..5d5046fa954 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -397,6 +397,40 @@ letter.
 [[send-patches]]
 === Sending your patches.
 
+==== Choosing your reviewers
+
+:security-ml-ref: footnoteref:[security-ml]
+
+As mentioned at the beginning of the section, patches that may be
+security relevant should not be submitted to the public mailing list
+mentioned below, but should instead be sent privately to the Git
+Security mailing list{security-ml-ref}.
+
+:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
+not part of the core `git` binary and must be called directly. Clone the Git +
+codebase and run `perl contrib/contacts/git-contacts`.]
+
+Send your patch with "To:" set to the mailing list, with "cc:" listing
+people who are involved in the area you are touching (the `git-contacts`
+script in `contrib/contacts/`{contrib-scripts} can help to
+identify them), to solicit comments and reviews.  Also, when you made
+trial merges of your topic to `next` and `seen`, you may have noticed
+work by others conflicting with your changes.  There is a good possibility
+that these people may know the area you are touching well.
+
+:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
+:git-ml: footnote:[The mailing list: git@vger.kernel.org]
+
+After the list reached a consensus that it is a good idea to apply the
+patch, re-send it with "To:" set to the maintainer{current-maintainer}
+and "cc:" the list{git-ml} for inclusion.  This is especially relevant
+when the maintainer did not heavily participate in the discussion and
+instead left the review to trusted others.
+
+Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
+`Tested-by:` lines as necessary to credit people who helped your
+patch, and "cc:" them when sending such a final version for inclusion.
+
 :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
 
 Before sending any patches, please note that patches that may be
@@ -490,38 +524,6 @@ patch, format it as "multipart/signed", not a text/plain message
 that starts with `-----BEGIN PGP SIGNED MESSAGE-----`.  That is
 not a text/plain, it's something else.
 
-:security-ml-ref: footnoteref:[security-ml]
-
-As mentioned at the beginning of the section, patches that may be
-security relevant should not be submitted to the public mailing list
-mentioned below, but should instead be sent privately to the Git
-Security mailing list{security-ml-ref}.
-
-:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
-not part of the core `git` binary and must be called directly. Clone the Git +
-codebase and run `perl contrib/contacts/git-contacts`.]
-
-Send your patch with "To:" set to the mailing list, with "cc:" listing
-people who are involved in the area you are touching (the `git-contacts`
-script in `contrib/contacts/`{contrib-scripts} can help to
-identify them), to solicit comments and reviews.  Also, when you made
-trial merges of your topic to `next` and `seen`, you may have noticed
-work by others conflicting with your changes.  There is a good possibility
-that these people may know the area you are touching well.
-
-:current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
-:git-ml: footnote:[The mailing list: git@vger.kernel.org]
-
-After the list reached a consensus that it is a good idea to apply the
-patch, re-send it with "To:" set to the maintainer{current-maintainer}
-and "cc:" the list{git-ml} for inclusion.  This is especially relevant
-when the maintainer did not heavily participate in the discussion and
-instead left the review to trusted others.
-
-Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
-`Tested-by:` lines as necessary to credit people who helped your
-patch, and "cc:" them when sending such a final version for inclusion.
-
 == Subsystems with dedicated maintainers
 
 Some parts of the system have dedicated maintainers with their own
-- 
gitgitgadget

[PATCH v6 6/8] SubmittingPatches: dedupe discussion of security patches

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 5d5046fa954..dd248513a50 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -399,12 +399,11 @@ letter.
 
 ==== Choosing your reviewers
 
-:security-ml-ref: footnoteref:[security-ml]
+:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
 
-As mentioned at the beginning of the section, patches that may be
-security relevant should not be submitted to the public mailing list
-mentioned below, but should instead be sent privately to the Git
-Security mailing list{security-ml-ref}.
+NOTE: Patches that may be
+security relevant should be submitted privately to the Git Security
+mailing list{security-ml}, instead of the public mailing list.
 
 :contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
 not part of the core `git` binary and must be called directly. Clone the Git +
@@ -431,12 +430,6 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
 `Tested-by:` lines as necessary to credit people who helped your
 patch, and "cc:" them when sending such a final version for inclusion.
 
-:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com]
-
-Before sending any patches, please note that patches that may be
-security relevant should be submitted privately to the Git Security
-mailing list{security-ml}, instead of the public mailing list.
-
 Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
-- 
gitgitgadget

[PATCH v6 7/8] SubmittingPatches: add heading for format-patch and send-email

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index dd248513a50..ef3985459a4 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -430,6 +430,8 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
 `Tested-by:` lines as necessary to credit people who helped your
 patch, and "cc:" them when sending such a final version for inclusion.
 
+==== `format-patch` and `send-email`
+
 Learn to use `format-patch` and `send-email` if possible.  These commands
 are optimized for the workflow of sending patches, avoiding many ways
 your existing e-mail client (often optimized for "multipart/*" MIME
-- 
gitgitgadget

[PATCH v6 8/8] SubmittingPatches: demonstrate using git-contacts with git-send-email

[Linus Arver via GitGitGadget]

From: Linus Arver <linusa@google.com>

Signed-off-by: Linus Arver <linusa@google.com>
---
 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index ef3985459a4..b684e28c0d0 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -417,6 +417,13 @@ trial merges of your topic to `next` and `seen`, you may have noticed
 work by others conflicting with your changes.  There is a good possibility
 that these people may know the area you are touching well.
 
+If you are using `send-email`, you can feed it the output of `git-contacts` like
+this:
+
+....
+	git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch
+....
+
 :current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
 :git-ml: footnote:[The mailing list: git@vger.kernel.org]
 
-- 
gitgitgadget

Re: [PATCH v6 0/8] docs: recommend using contrib/contacts/git-contacts

[Junio C Hamano]

"Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

> Make git-contacts more prominent in our docs.
>
>
> Notable changes in v6
> =====================
>
>  * Prefix the command with "perl" to avoid the need to have it installed at
>    /usr/bin/perl per the shebang line in git-contacts.
>  * Drop "you must have Perl installed in your system" guidance because it's
>    a bit moot now given the explicit call to "perl".

Looking good.  Will queue.  Hopefully we can have this in the -rc,
as it is a low risk documentaiton-only change?

Thanks.