Re: [PATCH] Documentation/MyFirstContribution: add setup template for git send-email

From: Victoria Dye <vdye@github.com>
Date: Feb 22, 2023, 21:18 UTC
Message-ID: <a6b0cf3b-af44-3d35-3de1-62aaf65f1543@github.com>
In-Reply-To: <20230222011317.97943-1-gvivan6@gmail.com>

It's generally good practice to CC contributors that have been recently and/or heavily involved in the code you're changing. Given that, I've CC'd Emily Shaffer (original author of the doc, including the section you'd like to change).

Vivan Garg wrote:

> The doumentation under [[setup-git-send-email]] fails to describe what

s/doumentation/documentation

Show 13 quoted lines

> needs to be done with the SMTP server information. Although the email
> provider will tell you the specifics (such as the serverport), it must
> always be added to gitconfig. By adding this, a new contributor can
> simply find the information and insert it into the template, saving them
> the headache of figuring out what to do with the information.
> Therefore, add a template that describes what to do with the
> information obtained through the email provider.
> 
> Signed-off-by: Vivan Garg <gvivan6@gmail.com>
> ---
> The commit subject line is over 50 columns long, but the file path takes 
> up the majority of the space, which I thought was important because it 
> shows that only the documentation is being edited.

Earlier commits related to this file start with just "MyFirstContribution:",
so you can leave out the "Documentation/" prefix to stay under the 50
character width.

Show 26 quoted lines

> 
> The reason I felt compelled to include this is that, while it is simple 
> to find the SMTP server information required from the email provider, it 
> takes a little extra effort to figure out what to do with that information.
> However, because it must always be added to git config, making this change 
> makes it easier for anyone to find which fields they need and what they 
> need to do with the information. 
> 
>  Documentation/MyFirstContribution.txt | 30 ++++++++++++++++++++++++---
>  1 file changed, 27 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index ccfd0cb5f3..37fd416b29 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -999,9 +999,33 @@ provider, and so will not be covered in this tutorial, beyond stating that in
>  many distributions of Linux, `git-send-email` is not packaged alongside the
>  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.
> +determine the right way to configure it to use your SMTP server; this
> +configuration can change significantly based on your system and email setup, 
> +but at a minimum, you'll need to edit gitconfig and set the following 
> +parameters:

The section you're replacing explicitly states that providing example configuration is out of scope for this document. That's for good reason; the example config you've provided isn't universal to all developer setups. It would be more confusing to a new contributor if we recommended a config that's incompatible with their setup than if we left it open-ended as it is now.

However, if you still want to make the guidance in this section more specific, you could add a 'linkgit:git-config' link and note that the relevant SMTP configs are under the 'sendemail' section.

Show 26 quoted lines

> +
> +----
> +$ vim ~/.gitconfig
> +
> +[sendemail]
> +    smtpServer = smtp.gmail.com
> +    smtpServerPort = 587
> +    smtpEncryption = tls
> +    smtpUser = my_email@gmail.com
> +    # (Optional: we'll leave this commented out and use a different way)
> +    # smtpPass = PASSWORD
> +[credential]
> +    helper = store
> +----
> +
> + . This example uses gmail as the email provider and the official data
> +   available as of 21/02/2023. You should check the latest information for 
> +   the email provider you intend to use (including gmail).
> +   
> + . The `[credential] helper = store` tells git, when a user runs a git 
> +   command that requires authentication, to store the credentials in a file
> +   on the local machine so that the user does not have to enter them again 
> +   in the future.
>  
>  [[format-patch]]
>  === Preparing Initial Patchset