| Message ID | 20230222011317.97943-1-gvivan6@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Documentation/MyFirstContribution: add setup template for git send-email | expand |
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
> 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!
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
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(-)