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@xxxxxxxxx> > --- > 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@xxxxxxxxx > + # (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
