patchdocs: recommend using contrib/contacts/git-contacts

From: Linus Arver <linusa@google.com>

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

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

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

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

On Tue, Apr 02, 2024 at 12:20:05AM +0000, Linus Arver via GitGitGadget wrote:

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

Thanks!

Patrick

Patrick Steinhardt <ps@pks.im> writes:

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

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

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

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

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

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.

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

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

From: Linus Arver <linusa@google.com>

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

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

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

Nice.  

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

As I prefer not to be too assertive, something like

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

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

Thanks.

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

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?

Linus Arver <linusa@google.com> writes:

Sounds reasonable.  Thanks.

From: Linus Arver <linusa@google.com>

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

    $ git grep git.contacts Documentation

will return a positive hit for this location.

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

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

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

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

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

From: Linus Arver <linusa@google.com>

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

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

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

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

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

Ah, of course. Will update.

Linus Arver <linusa@google.com> writes:

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

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

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

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

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

Make git-contacts more prominent in our docs.

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

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

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

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

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

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

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

Range-diff vs v2:

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

From: Linus Arver <linusa@google.com>

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

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

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

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

Linus Arver <linusa@google.com> writes:

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.

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

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

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

Linus Arver <linusa@google.com> writes:

I will incorporate this into the next reroll.

From: Linus Arver <linusa@google.com>

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

    $ git grep git.contacts Documentation

will return a positive hit for this location.

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

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

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

On Tue, Apr 9, 2024 at 5:57 PM Linus Arver via GitGitGadget <gitgitgadget@gmail.com> wrote:

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

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

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

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

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

Eric Sunshine <sunshine@sunshineco.com> writes:

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.

Eric Sunshine <sunshine@sunshineco.com> writes:

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.

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

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

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

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

Kipras Melnikovas <kipras@kipras.org> writes:

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.

Thanks, v4 looks good to me.

Make git-contacts more prominent in our docs.

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

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

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

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

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

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

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

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

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

Range-diff vs v3:

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

From: Linus Arver <linusa@google.com>

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

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

From: Linus Arver <linusa@google.com>

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

    $ git grep git.contacts Documentation

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

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

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

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?

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

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

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

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

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

On Fri, Apr 12, 2024 at 1:09 PM Junio C Hamano <gitster@pobox.com> wrote:

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

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

Eric Sunshine <sunshine@sunshineco.com> writes:

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.

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

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

Linus Arver <linusa@google.com> writes:

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

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

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.

Linus Arver <linusa@google.com> writes:

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?

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

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

On Wed, Apr 17, 2024 at 1:38 AM Junio C Hamano <gitster@pobox.com> wrote:

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

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

Anyhow, it's a minor point.

Eric Sunshine <sunshine@sunshineco.com> writes:

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.

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

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

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

I should be able to test this later this week.

Linus Arver <linusa@google.com> writes:

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.

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

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

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

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

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

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

Oops, will update.

Make git-contacts more prominent in our docs.

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

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

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

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

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

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

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

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

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

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

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

Range-diff vs v4:

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

From: Linus Arver <linusa@google.com>

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

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

From: Linus Arver <linusa@google.com>

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

    $ git grep git.contacts Documentation

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

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

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

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

Make git-contacts more prominent in our docs.

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

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

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

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

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

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

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

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

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

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

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

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

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

Range-diff vs v5:

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

From: Linus Arver <linusa@google.com>

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

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

From: Linus Arver <linusa@google.com>

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

    $ git grep git.contacts Documentation

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

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

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

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

From: Linus Arver <linusa@google.com>

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

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

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

Thanks.

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

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

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.

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

The contacts script already uses "check-mailmap".  

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

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

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

On 4/3/24 12:11, Matthias Aßhauer wrote:

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.