threads / patch / 59284

patchDocumentation/MyFirstContribution: add setup template for git send-email

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

## tl;dr

15 messages between Feb 22, 2023 and Feb 26, 2023. Diffs are folded; open one to read it.

replies: 14people: 5as markdown or json

Vivan Garg· Feb 22, 2023, 01:13 UTC · lore

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(-)
Show changes to Documentation/MyFirstContribution.txt +27 −3
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)
Victoria Dye· Feb 22, 2023, 21:18 UTC · re: Vivan Garg · lore

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

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
Vivan Garg· Feb 23, 2023, 04:09 UTC · re: Victoria Dye · lore

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

> 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.
Show 6 quoted lines
> 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!
Vivan Garg· Feb 23, 2023, 05:40 UTC · re: Vivan Garg · lore

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

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)
Vivan Garg· Feb 23, 2023, 05:40 UTC · re: Vivan Garg · lore

[PATCH v2 1/1] 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.

Signed-off-by: Vivan Garg <gvivan6@gmail.com>
---
 Documentation/MyFirstContribution.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
Show changes to Documentation/MyFirstContribution.txt +4 −1
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)
Victoria Dye· Feb 23, 2023, 06:23 UTC · re: Vivan Garg · lore

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

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
Victoria Dye· Feb 23, 2023, 06:24 UTC · re: Vivan Garg · lore

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

Vivan Garg wrote:
Show 9 quoted lines
> 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.

Vivan Garg· Feb 23, 2023, 06:47 UTC · re: Victoria Dye · lore

Re: [PATCH v2 0/1] 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.

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!

Vivan Garg· Feb 23, 2023, 08:27 UTC · re: Vivan Garg · lore

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

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]).
Show changes to Documentation/MyFirstContribution.txt +3 −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)
Benson Muite· Feb 23, 2023, 08:45 UTC · re: Vivan Garg · lore

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

On 2/23/23 11:27, Vivan Garg wrote:
Show 8 quoted lines
> 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.
Vivan Garg· Feb 23, 2023, 09:20 UTC · re: Benson Muite · lore

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

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

Benson Muite· Feb 23, 2023, 10:37 UTC · re: Vivan Garg · lore

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

On 2/23/23 12:20, Vivan Garg wrote:
Show 10 quoted lines
>> 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

Vivan Garg· Feb 26, 2023, 00:49 UTC · re: Benson Muite · lore

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

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

Bagas Sanjaya· Feb 26, 2023, 13:19 UTC · re: Benson Muite · lore

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

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
Bagas Sanjaya· Feb 26, 2023, 13:07 UTC · re: Vivan Garg · lore

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

On 2/23/23 15:27, Vivan Garg wrote:
Show 9 quoted lines
> @@ -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

← back to recent threads