docs: recommend using contrib/contacts/git-contacts

From: Linus Arver <[email protected]>

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.

---
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(+)

index f06563e9817..eb1e27a82df 100644
@@ -1116,6 +1116,9 @@ $ git send-email [email protected] 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 [email protected] - 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.

index e734a3f0f17..52d11ff510b 100644
@@ -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

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

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

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.

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.

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

Matthieu Moy

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.

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 <[email protected]>" and then doing something like the attached.

index 85ad732fc0..00e77c4125 100755
@@ -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";

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

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

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 <[email protected]>

## 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 [email protected]
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 [email protected] - 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

From: Linus Arver <[email protected]>

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.

---
 Documentation/MyFirstContribution.txt | 5 +++++
 1 file changed, 5 insertions(+)

index f06563e9817..ad3989f53e5 100644
@@ -1116,6 +1116,11 @@ $ git send-email [email protected] 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 [email protected] - 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

From: Linus Arver <[email protected]>

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.

---
 Documentation/SubmittingPatches | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

index e734a3f0f17..a33fe7e11f6 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 4 ++++
 1 file changed, 4 insertions(+)

index a33fe7e11f6..48b270b4c48 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 48b270b4c48..24c7041a06f 100644
@@ -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

From: Linus Arver <[email protected]>

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.

---
 Documentation/SubmittingPatches | 58 +++++++++++++++++----------------
 1 file changed, 30 insertions(+), 28 deletions(-)

index 24c7041a06f..17db961bac4 100644
@@ -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: [email protected]]
+:git-ml: footnote:[The mailing list: [email protected]]
+
+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: [email protected]]
 
 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: [email protected]]
-:git-ml: footnote:[The mailing list: [email protected]]
-
-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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

index 17db961bac4..311f306394b 100644
@@ -399,12 +399,11 @@ letter.
 
 ==== Choosing your reviewers
 
-:security-ml-ref: footnoteref:[security-ml]
+:security-ml: footnoteref:[security-ml,The Git Security mailing list: [email protected]]
 
-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: [email protected]]
-
-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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 2 ++
 1 file changed, 2 insertions(+)

index 311f306394b..48224e745ff 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

index 48224e745ff..11c3e94d4a5 100644
@@ -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: [email protected]]
 :git-ml: footnote:[The mailing list: [email protected]]
 

gitgitgadget

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

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).

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?

Ah, of course. Will update.

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

Sounds reasonable. Thanks.

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 [email protected]
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 [email protected] - 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

From: Linus Arver <[email protected]>

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.

---
 Documentation/MyFirstContribution.txt | 5 +++++
 1 file changed, 5 insertions(+)

index f06563e9817..00f4c63cb9f 100644
@@ -1116,6 +1116,11 @@ $ git send-email [email protected] 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 [email protected] - 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

From: Linus Arver <[email protected]>

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.

---
 Documentation/SubmittingPatches | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

index e734a3f0f17..a33fe7e11f6 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 4 ++++
 1 file changed, 4 insertions(+)

index a33fe7e11f6..c1933c97cb7 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index c1933c97cb7..8594a3dda36 100644
@@ -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

From: Linus Arver <[email protected]>

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.

---
 Documentation/SubmittingPatches | 58 +++++++++++++++++----------------
 1 file changed, 30 insertions(+), 28 deletions(-)

index 8594a3dda36..392bbccc452 100644
@@ -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: [email protected]]
+:git-ml: footnote:[The mailing list: [email protected]]
+
+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: [email protected]]
 
 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: [email protected]]
-:git-ml: footnote:[The mailing list: [email protected]]
-
-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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

index 392bbccc452..98ec8170aeb 100644
@@ -399,12 +399,11 @@ letter.
 
 ==== Choosing your reviewers
 
-:security-ml-ref: footnoteref:[security-ml]
+:security-ml: footnoteref:[security-ml,The Git Security mailing list: [email protected]]
 
-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: [email protected]]
-
-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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 2 ++
 1 file changed, 2 insertions(+)

index 98ec8170aeb..bafb1ee0157 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

index bafb1ee0157..57953898cee 100644
@@ -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: [email protected]]
 :git-ml: footnote:[The mailing list: [email protected]]
 

gitgitgadget

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.

index 00f4c63cb9..bb7e4174e8 100644
@@ -1116,8 +1116,8 @@ $ git send-email [email protected] 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`.
 

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.

Ack.

In hindsight this is what I shoould have said.

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).

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.

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.

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 [email protected] --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.
...

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.

I will incorporate this into the next reroll.

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 <[email protected]>

## Documentation/MyFirstContribution.txt ##
@@ Documentation/MyFirstContribution.txt: $ git send-email [email protected]
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 [email protected] - 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 <[email protected]>

## 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).

## 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

From: Linus Arver <[email protected]>

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.

---
 Documentation/MyFirstContribution.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)

index f06563e9817..de60b3a4fa1 100644
@@ -1116,6 +1116,18 @@ $ git send-email [email protected] 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, 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 [email protected] - 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

From: Linus Arver <[email protected]>

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).

---
 Documentation/SubmittingPatches | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

index e734a3f0f17..8b6e4bf0300 100644
@@ -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, 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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 4 ++++
 1 file changed, 4 insertions(+)

index 8b6e4bf0300..2226c09e6c5 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 2226c09e6c5..f1c0d1483bd 100644
@@ -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

From: Linus Arver <[email protected]>

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.

---
 Documentation/SubmittingPatches | 72 +++++++++++++++++----------------
 1 file changed, 37 insertions(+), 35 deletions(-)

index f1c0d1483bd..8805579a36e 100644
@@ -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, 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: [email protected]]
+:git-ml: footnote:[The mailing list: [email protected]]
+
+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: [email protected]]
 
 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, 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: [email protected]]
-:git-ml: footnote:[The mailing list: [email protected]]
-
-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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

index 8805579a36e..ecc1622c8bf 100644
@@ -399,12 +399,11 @@ letter.
 
 ==== Choosing your reviewers
 
-:security-ml-ref: footnoteref:[security-ml]
+:security-ml: footnoteref:[security-ml,The Git Security mailing list: [email protected]]
 
-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: [email protected]]
-
-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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 2 ++
 1 file changed, 2 insertions(+)

index ecc1622c8bf..fd40a444f95 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

index fd40a444f95..eac086133bc 100644
@@ -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: [email protected]]
 :git-ml: footnote:[The mailing list: [email protected]]
 

gitgitgadget

Thanks, v4 looks good to me.

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.

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?

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

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/[email protected]/

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.

Oops, will update.

Noted; I will use this wording.

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.

Will do.

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

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).

Agreed.

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

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).

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 [email protected]
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.] ++: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 [email protected] - 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).

@@ 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: [email protected]]

gitgitgadget

From: Linus Arver <[email protected]>

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.

---
 Documentation/MyFirstContribution.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

index f06563e9817..9665951aeb5 100644
@@ -1116,6 +1116,16 @@ $ git send-email [email protected] 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 [email protected] - 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

From: Linus Arver <[email protected]>

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).

---
 Documentation/SubmittingPatches | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

index e734a3f0f17..0d4276c6c7e 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 4 ++++
 1 file changed, 4 insertions(+)

index 0d4276c6c7e..a27f7c923b9 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index a27f7c923b9..b684bdd03a1 100644
@@ -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

From: Linus Arver <[email protected]>

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.

---
 Documentation/SubmittingPatches | 68 +++++++++++++++++----------------
 1 file changed, 35 insertions(+), 33 deletions(-)

index b684bdd03a1..a110f94db4f 100644
@@ -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: [email protected]]
+:git-ml: footnote:[The mailing list: [email protected]]
+
+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: [email protected]]
 
 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: [email protected]]
-:git-ml: footnote:[The mailing list: [email protected]]
-
-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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

index a110f94db4f..060c8069c10 100644
@@ -399,12 +399,11 @@ letter.
 
 ==== Choosing your reviewers
 
-:security-ml-ref: footnoteref:[security-ml]
+:security-ml: footnoteref:[security-ml,The Git Security mailing list: [email protected]]
 
-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: [email protected]]
-
-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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 2 ++
 1 file changed, 2 insertions(+)

index 060c8069c10..1700132a3a4 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

index 1700132a3a4..b616422197f 100644
@@ -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: [email protected]]
 :git-ml: footnote:[The mailing list: [email protected]]
 

gitgitgadget

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.

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?

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(-)

index 9665951aeb..9eb6b98a82 100644
@@ -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 [email protected] - but

index b616422197..1099040d7e 100644
@@ -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: [email protected]]

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.

I should be able to test this later this week.

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

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.

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 [email protected]

+: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 [email protected] - 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: [email protected]]

gitgitgadget

From: Linus Arver <[email protected]>

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.

---
 Documentation/MyFirstContribution.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

index f06563e9817..e41654c00a6 100644
@@ -1116,6 +1116,15 @@ $ git send-email [email protected] 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 [email protected] - 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

From: Linus Arver <[email protected]>

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).

---
 Documentation/SubmittingPatches | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

index e734a3f0f17..d4173d4fe84 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 4 ++++
 1 file changed, 4 insertions(+)

index d4173d4fe84..26055a1fe2b 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

index 26055a1fe2b..6b9e954a47d 100644
@@ -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

From: Linus Arver <[email protected]>

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.

---
 Documentation/SubmittingPatches | 66 +++++++++++++++++----------------
 1 file changed, 34 insertions(+), 32 deletions(-)

index 6b9e954a47d..5d5046fa954 100644
@@ -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: [email protected]]
+:git-ml: footnote:[The mailing list: [email protected]]
+
+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: [email protected]]
 
 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: [email protected]]
-:git-ml: footnote:[The mailing list: [email protected]]
-
-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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

index 5d5046fa954..dd248513a50 100644
@@ -399,12 +399,11 @@ letter.
 
 ==== Choosing your reviewers
 
-:security-ml-ref: footnoteref:[security-ml]
+:security-ml: footnoteref:[security-ml,The Git Security mailing list: [email protected]]
 
-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: [email protected]]
-
-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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 2 ++
 1 file changed, 2 insertions(+)

index dd248513a50..ef3985459a4 100644
@@ -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

From: Linus Arver <[email protected]>

---
 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

index ef3985459a4..b684e28c0d0 100644
@@ -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: [email protected]]
 :git-ml: footnote:[The mailing list: [email protected]]
 

gitgitgadget

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

Thanks.