Subject: Re: [PATCH v2 1/1] MyFirstContribution: add note about SMTP server config

From: Victoria Dye <[email-masked]>
Date: Wed, 22 Feb 2023 22:23:49 -0800

Vivan Garg wrote:
> In the documentation on using git-send-email, it was noted that the configuration
> for sending email can vary based on your operating system and email provider.
> However, it was not explicitly stated that you will need to set up your SMTP
> server details in git's configuration file under the 'sendemail' section. 

This is a bit of an overstatement of the issue. The existing documentation
*does* say that you need to configure Git for your SMTP server:

> You will also need to determine the right way to configure it to use your
> SMTP server; again, as this configuration can change significantly based
> on your system and email setup, it is out of scope for the context of this
> tutorial.

The only thing it could use is a bit more specificity around which options
need configuring. With that in mind...

> This information is critical for users who are new to using git-send-email and may
> not be familiar with the additional setup required to use their SMTP server. By
> adding this note to the documentation, the aim is to provide users with a more
> complete understanding of the configuration process and help them avoid
> potential roadblocks in setting up git-send-email.
> 
> Signed-off-by: Vivan Garg <[email-masked]>
> ---
>  Documentation/MyFirstContribution.txt | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index ccfd0cb5f3..ca095283d3 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -1001,7 +1001,10 @@ typical `git` install. You may need to install this additional package; there
>  are a number of resources online to help you do so. You will also need to
>  determine the right way to configure it to use your SMTP server; again, as this
>  configuration can change significantly based on your system and email setup, it
> -is out of scope for the context of this tutorial.
> +is out of scope for the context of this tutorial. Additionally, note that you 
> +will need to set up your SMTP server details in git's configuration file. The 

...this sentence seems to ignore the one that precedes it. The documentation
just finishes telling the reader "you'll need to configure Git for SMTP",
which you now follow with "also, you need to configure Git for SMTP" -
basically saying the same thing twice. If you drop the sentence starting
with "Additionally, ...", though, the sentence after (starting with "The
relevant settings...") flows nicely from the existing paragraph while still
adding specificity to the SMTP configuration guidance.

> +relevant settings can be found under the 'sendemail' section (see 

super-nit: "the 'sendemail' section" could be clearer about the fact that
it's the a section *of the '.gitconfig'* - how about something like "the
'sendemail' section of the Git config file"?

> +linkgit:git-config[1]).
>  
>  [[format-patch]]
>  === Preparing Initial Patchset