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

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

[Vivan Garg]

The doumentation under [[setup-git-send-email]] fails to describe what
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. 

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:
+
+----
+$ 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
-- 
2.37.0 (Apple Git-136)

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

[Victoria Dye]

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

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

> +
> +----
> +$ 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

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

[Vivan Garg]

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

I see, will do in the future.

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

Noted.

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

Oh, I thought you had to set these parameters, i.e. smtpServer, smtpServerPort,
smtpEncryption, smtpUser, and smtpPass in gitConfig regardless of the setup (I
did some googling as well). However, I'll take your word for it that it may be
incompatible with some setups. Thanks for pointing that out!

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

That sounds like a good addition! I'll do it then. Thanks!

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

[Vivan Garg]

Vivan Garg (1):
  MyFirstContribution: add note about SMTP server config

 Documentation/MyFirstContribution.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

Range-diff against v1:
1:  bd9bc70307 < -:  ---------- Documentation/MyFirstContribution: add setup template for git send-email
-:  ---------- > 1:  d295b4d913 MyFirstContribution: add note about SMTP server config
-- 
2.37.0 (Apple Git-136)

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

[Vivan Garg]

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
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 
+relevant settings can be found under the 'sendemail' section (see 
+linkgit:git-config[1]).
 
 [[format-patch]]
 === Preparing Initial Patchset
-- 
2.37.0 (Apple Git-136)

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

[Victoria Dye]

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

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

[Victoria Dye]

Vivan Garg wrote:
> Vivan Garg (1):
>   MyFirstContribution: add note about SMTP server config
> 
>  Documentation/MyFirstContribution.txt | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
> 
> Range-diff against v1:
> 1:  bd9bc70307 < -:  ---------- Documentation/MyFirstContribution: add setup template for git send-email
> -:  ---------- > 1:  d295b4d913 MyFirstContribution: add note about SMTP server config

Since you also did this in your microproject, it's worth pointing out: you
don't need a cover letter for a single-patch submission (see "Bonus Chapter:
One-Patch Changes" in MyFirstContribution). You can include the range-diff
below the '---' line (i.e., below the commit message) in your patch.

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

[Vivan Garg]

> Since you also did this in your microproject, it's worth pointing out: you
> don't need a cover letter for a single-patch submission (see "Bonus Chapter:
> One-Patch Changes" in MyFirstContribution). You can include the range-diff
> below the '---' line (i.e., below the commit message) in your patch.

I didn't include the cover letter in either v1 but thought the range-diff was
important so I kept it in both v2's. Next time, I'll just put it below
the commit
message. Thanks!

[PATCH v3] MyFirstContribution: add note about SMTP server config

[Vivan Garg]

The documentation on using git-send-email previously mentioned the need
to configure git for your operating system and email provider, but did
not provide specific details on the relevant configuration settings.
This commit adds a note specifying that the relevant settings can be
found under the 'sendemail' section of Git's configuration file, with a
link to the relevant 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 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
 
Range-diff against v2:
1:  d295b4d913 ! 1:  8710c50b1d MyFirstContribution: add note about SMTP server config
    @@ Metadata
      ## Commit message ##
         MyFirstContribution: add note about SMTP server config
     
    -    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
    -    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.
    +    The documentation on using git-send-email previously mentioned the need
    +    to configure git for your operating system and email provider, but did
    +    not provide specific details on the relevant configuration settings.
    +    This commit adds a note specifying that the relevant settings can be
    +    found under the 'sendemail' section of Git's configuration file, with a
    +    link to the relevant 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: typical `git` install. You may need to in
      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 
    -+relevant settings can be found under the 'sendemail' section (see 
    ++is out of scope for the context of this tutorial. The relevant settings can be 
    ++found under the 'sendemail' section of Git's configuration file. (see 
     +linkgit:git-config[1]).

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index ccfd0cb5f3..0430434822 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1001,7 +1001,9 @@ 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. The relevant settings can be 
+found under the 'sendemail' section of Git's configuration file. (see 
+linkgit:git-config[1]).
 
 [[format-patch]]
 === Preparing Initial Patchset
-- 
2.37.0 (Apple Git-136)

Re: [PATCH v3] MyFirstContribution: add note about SMTP server config

[Benson Muite]

On 2/23/23 11:27, Vivan Garg wrote:
> The documentation on using git-send-email previously mentioned the need
> to configure git for your operating system and email provider, but did
> not provide specific details on the relevant configuration settings.
> This commit adds a note specifying that the relevant settings can be
> found under the 'sendemail' section of Git's configuration file, with a
> link to the relevant 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.
Maybe https://git-send-email.io/ is also helpful.

Re: [PATCH v3] MyFirstContribution: add note about SMTP server config

[Vivan Garg]

> Maybe https://git-send-email.io/ is also helpful.
If you look at v1 of this patch, you'll notice that I added a template with
instructions that are nearly identical to the generic ones in the link.
I was told that it doesn't work for all setups. Although there are instructions
for a few different setups, they most likely do not cover all of them? Perhaps
it's best to leave it up to the contributor to decide what to do. Also, I'm not
sure how credible the configuration settings for the other setups are.
However, if the other setups are correct, I also believe it may be beneficial.
What are your thoughts? I suppose I'd like to hear what other people think
as well? Thanks!

Re: [PATCH v3] MyFirstContribution: add note about SMTP server config

[Benson Muite]

On 2/23/23 12:20, Vivan Garg wrote:
>> Maybe https://git-send-email.io/ is also helpful.
> If you look at v1 of this patch, you'll notice that I added a template with
> instructions that are nearly identical to the generic ones in the link.
> I was told that it doesn't work for all setups. Although there are instructions
> for a few different setups, they most likely do not cover all of them? Perhaps
> it's best to leave it up to the contributor to decide what to do. Also, I'm not
> sure how credible the configuration settings for the other setups are.
> However, if the other setups are correct, I also believe it may be beneficial.
> What are your thoughts? I suppose I'd like to hear what other people think
> as well? Thanks!
Have not tested all of the setups in https://git-send-email.io/ The
Fedora instructions seem fine.  It can be updated through Git, so
contributions for other setups are possible. There is a nice way to test:
https://git-send-email.io/#step-3

Re: [PATCH v3] MyFirstContribution: add note about SMTP server config

[Vivan Garg]

> Have not tested all of the setups in https://git-send-email.io/ The
> Fedora instructions seem fine.  It can be updated through Git, so
> contributions for other setups are possible. There is a nice way to test:
> https://git-send-email.io/#step-3

I am waiting for someone else to offer their input on the matter. However,
I appreciate your suggestion nonetheless.

Re: [PATCH v3] MyFirstContribution: add note about SMTP server config

[Bagas Sanjaya]

On 2/23/23 15:27, Vivan Garg wrote:
> @@ -1001,7 +1001,9 @@ 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. The relevant settings can be 
> +found under the 'sendemail' section of Git's configuration file. (see 
> +linkgit:git-config[1]).
>  

Personally said, besides above, I'd like to also add "Instructions
on how to set up sending email with git send-email can be found at
https://git-send-email.io".

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH v3] MyFirstContribution: add note about SMTP server config

[Bagas Sanjaya]

On 2/23/23 17:37, Benson Muite wrote:
> Have not tested all of the setups in https://git-send-email.io/ The
> Fedora instructions seem fine.  It can be updated through Git, so
> contributions for other setups are possible. There is a nice way to test:
> https://git-send-email.io/#step-3

For me, my setup is to use Postfix as "null-client" MTA, where all
outgoing mails are relayed to Gmail. This way, configuring SMTP
credentials is delegated to the MTA and applications can be set up
to simply specifying `/usr/sbin/sendmail` as mailer.

However, in order for system-generated mails to be sent to my
real address, I have to canonicalize local `root` and `postmaster`
recipients via `recipient_canonical_maps` setting.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara