[libvirt] [PATCH] hacking: Improve 'git send-email' documentation

[John Ferlan]

On 06/14/2017 11:31 PM, Andrea Bolognani wrote:
> For the benefit of first time contributors, we point out that 'git
> send-email' might have to be installed separately; however, we omit
> the fact that some configuration will likely be needed before it
> can successfully deliver patches to the mailing list.
> 
> Some minor tweaks to the existing contents are included as well.
> 
> Signed-off-by: Andrea Bolognani <abologna at redhat.com>
> ---
>  docs/hacking.html.in | 36 ++++++++++++++++++++++++------------
>  1 file changed, 24 insertions(+), 12 deletions(-)
> 
> diff --git a/docs/hacking.html.in b/docs/hacking.html.in
> index d6a574c..434fb68 100644
> --- a/docs/hacking.html.in
> +++ b/docs/hacking.html.in
> @@ -29,8 +29,8 @@
>          file from zanata.</p>
>        </li>
>  
> -      <li><p>Post patches using "git send-email", with git rename
> -        detection enabled.  You need a one-time setup of:</p>
> +      <li><p>Post patches using <code>git send-email</code>, with git
> +        rename detection enabled.  You need a one-time setup of:</p>
>  <pre>
>    git config diff.renames true
>  </pre>
> @@ -52,20 +52,32 @@
>    git send-email --cover-letter --no-chain-reply-to --annotate \
>                   --to=libvir-list at redhat.com master
>  </pre>

FWIW: I have in my cut-n-paste command "--confirm=always" - it just
makes sure I really want to send things, but has saved me a couple of
times!

> -        <p>(Note that the "git send-email" subcommand may not be in
> -        the main git package and using it may require installation of a
> -        separate package, for example the "git-email" package in
> -        Fedora.)  For a single patch you can omit
> -        <code>--cover-letter</code>, but a series of two or more
> -        patches needs a cover letter. If you get tired of typing
> -        <code>--to=libvir-list at redhat.com</code> designation you can
> -        set it in git config:</p>
> +        <p>Note that the <code>git send-email</code> subcommand may not
> +        be in the main git package and using it may require installation
> +        of a separate package, for example the "git-email" package in
> +        Fedora and Debian.  If this is your first time using
> +        <code>git send-email</code>, you might need to configure it to
> +        point it to your SMTP server with something like:</p>
> +<pre>
> +  git config --global sendemail.smtpServer stmp.youremailprovider.net
> +</pre>
> +        <p>If you get tired of typing
> +        <code>--to=libvir-list at redhat.com</code> all the time, you can
> +        configure that to be automatically handled as well:</p>
>  <pre>
>    git config sendemail.to libvir-list at redhat.com
>  </pre>

As long as we're adding stuff... For those that use libvir-list to post
patches from multiple repositories (e.g. libvirt-python, libvirt-perl,
etc.) using:

git config --local format.subjectprefix "libvirt-python PATCH"

(or libvirt-perl or whatever the repository is) really *helps* reviewers
focus whether the patch is meant for mainline libvirt or whether it's
for some other git repo.

Also (how strongly can we say the following)... Please, please, please,
pretty-please... Do *NOT* use the "--cc" option to copy random
developers. We're all subscribed to the list and will *definitely* see
the patches. I would even say I'd rather not see it for -vN patches too.

> +        <p>For a single patch you can omit
> +        <code>--cover-letter</code>, but a series of two or more
> +        patches needs a cover letter.</p>
> +        <p>If everything went well, your patch should show up on the
> +        <a href="https://www.redhat.com/archives/libvir-list/">libvir-list
> +        archives</a> in a matter of minutes; if you still can't find it on
> +        there after an hour or so, you should double-check your setup.</p>

Another "hint" I got when first starting out - send your patch to your
own email address instead of libvir-list in order to make sure it "looks
right" or "similar to" how patches are posted on the list.

One could also go as far as "saving" those patches and creating a new
git branch to test whether a "git am -3" would work on their patch(es).
That at least ensures someone else applying an on list patch would be
able to "use" whatever was posted.

Thanks for diving into the shallow end of pool and updating this ;-)

John

>          <p>Please follow this as close as you can, especially the rebase and
> -        git send-email part, as it makes life easier for other developers to
> -        review your patch set. One should avoid sending patches as attachments,
> +        <code>git send-email</code> part, as it makes life easier for other
> +        developers to review your patch set.
> +        One should avoid sending patches as attachments,
>          but rather send them in email body along with commit message. If a
>          developer is sending another version of the patch (e.g. to address
>          review comments), they are advised to note differences to previous
>