From: Victoria Dye <vdye@github.com>
To: Vivan Garg <gvivan6@gmail.com>,
git@vger.kernel.org, Emily Shaffer <nasamuffin@google.com>
Subject: Re: [PATCH] Documentation/MyFirstContribution: add setup template for git send-email
Date: Wed, 22 Feb 2023 13:18:41 -0800 [thread overview]
Message-ID: <a6b0cf3b-af44-3d35-3de1-62aaf65f1543@github.com> (raw)
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
> 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
next prev parent reply other threads:[~2023-02-22 21:18 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-02-22 1:13 [PATCH] Documentation/MyFirstContribution: add setup template for git send-email Vivan Garg
2023-02-22 21:18 ` Victoria Dye [this message]
2023-02-23 4:09 ` Vivan Garg
2023-02-23 5:40 ` [PATCH v2 0/1] MyFirstContribution: add note about SMTP server config Vivan Garg
2023-02-23 5:40 ` [PATCH v2 1/1] " Vivan Garg
2023-02-23 6:23 ` Victoria Dye
2023-02-23 6:24 ` [PATCH v2 0/1] " Victoria Dye
2023-02-23 6:47 ` Vivan Garg
2023-02-23 8:27 ` [PATCH v3] " Vivan Garg
2023-02-23 8:45 ` Benson Muite
2023-02-23 9:20 ` Vivan Garg
2023-02-23 10:37 ` Benson Muite
2023-02-26 0:49 ` Vivan Garg
2023-02-26 13:19 ` Bagas Sanjaya
2023-02-26 13:07 ` Bagas Sanjaya
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=a6b0cf3b-af44-3d35-3de1-62aaf65f1543@github.com \
--to=vdye@github.com \
--cc=git@vger.kernel.org \
--cc=gvivan6@gmail.com \
--cc=nasamuffin@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).