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

From: Linus Arver <[email-masked]>
Date: Mon, 08 Apr 2024 18:08:13 -0700

Junio C Hamano <[email-masked]> writes:

> "Linus Arver via GitGitGadget" <[email-masked]> writes:
>
>> From: Linus Arver <[email-masked]>
>>
>> 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 <[email-masked]>
>> ---
>>  Documentation/MyFirstContribution.txt | 5 +++++
>>  1 file changed, 5 insertions(+)
>>
>> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
>> index f06563e9817..ad3989f53e5 100644
>> --- a/Documentation/MyFirstContribution.txt
>> +++ b/Documentation/MyFirstContribution.txt
>> @@ -1116,6 +1116,11 @@ $ git send-email --to=[email-masked] 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-masked] - but
>>  please don't send your patchset from the tutorial to the real mailing list! For
>>  now, you can send it to yourself, to make sure you understand how it will look.
>
> Nice.  
>
> I personally find "you should" a bit too strong and authoritative,
> though.  Is the tool precise enough that we are confident that we do
> not end up spamming those who are not actively helping others?

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

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

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