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

From: Victoria Dye <vdye@github.com>
Date: Feb 23, 2023, 06:23 UTC
Message-ID: <cb69979d-a0f1-d4dc-6e94-2d1652ec69ea@github.com>
In-Reply-To: <20230223054040.30088-2-gvivan6@gmail.com>

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

Show 22 quoted lines

> 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 <gvivan6@gmail.com>
> ---
>  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