From: Daniel P. Berrangé <berrange@redhat.com>

If a contributor's email domain has a DMARC policy of 'p=quarantine'
or 'p=reject', mailman will apply DMARC countermeasures on all mails
sent to lists.libvirt.org rewriting the "From" header to remove the
sender's email address. e.g.

  From: Your Name via <lists.libvirt.org>

If these countermeasures were not applied, affected mail would either
have gon directly to SPAM, or have been entirely rejected. Mailman3
is unable to be configured to guarantee no mangling of the mail body
so these countermeasures are unavoidable for lists.libvirt.org.

Amongst the various downsides, the From address rewriting has the
bad effect of mangling git commit author attribution.

To avoid this it is required to add two additional git config
settings:

  $ git config --global format.from "Your Name <your@email.com>"
  $ git config --global format.forceInBodyFrom true

Note, *both* are required, even if your ``format.from`` matches
your existing git identity, because the latter only takes effect
once the former is set.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 docs/submitting-patches.rst | 66 ++++++++++++++++++++++++++++---------
 1 file changed, 51 insertions(+), 15 deletions(-)

diff --git a/docs/submitting-patches.rst b/docs/submitting-patches.rst
index a5e108550a..b22e4e03b4 100644
--- a/docs/submitting-patches.rst
+++ b/docs/submitting-patches.rst
@@ -43,21 +43,7 @@ series of two or more patches needs a cover letter.
 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
-and Debian. If this is your first time using
-``git send-email``, you might need to configure it to point it
-to your SMTP server with something like:
-
-::
-
-  $ git config --global sendemail.smtpServer stmp.youremailprovider.net
-
-If you get tired of typing ``--to=devel@lists.libvirt.org`` all
-the time, you can configure that to be automatically handled as
-well:
-
-::
-
-  $ git config sendemail.to devel@lists.libvirt.org
+and Debian.
 
 Avoid using mail clients for sending patches, as most of them
 will mangle the messages in some way, making them unusable for
@@ -88,6 +74,56 @@ Moreover, such patch needs to be prefixed correctly with
 ``git send-email`` (substitute ``v2`` with the
 correct version if needed though).
 
+Git Configuration
+-----------------
+
+If this is your first time using ``git send-email``, you will probably
+need to setup your global git configuration, to point to your outgoing
+SMTP server with something like:
+
+::
+
+  $ git config --global sendemail.smtpServer stmp.youremailprovider.net
+
+If your email provider (often your employer) has configured a DMARC
+policy for their domain, there are some additional settings that will
+be required. Before doing this, check the DMARC policy with
+
+::
+
+  $ host -t txt _dmarc.$YOURDOMAIN.COM
+
+If this returns no output, or contains ``p=none`` then no configuration
+is required. If it reports ``p=quarantine`` or ``p=reject``, then the
+libvirt lists will apply DMARC countermeasures to your email. To ensure
+that git authorship is preserved add
+
+::
+
+  $ git config --global format.from "Your Name <your@email.com>"
+  $ git config --global format.forceInBodyFrom true
+
+This will force git to always add an additional line
+
+::
+
+   From: Your Name <your@email.com>
+
+in the body of the patch, guaranteeing correct author records even
+when the main ``From`` header is rewritten by mailman.
+
+If you get tired of typing ``--to=devel@lists.libvirt.org`` all
+the time, you can configure that to be automatically handled by
+adding a local repository setting:
+
+::
+
+  $ git config sendemail.to devel@lists.libvirt.org
+
+This last setting is not required if using ``git-publish`` to send
+patches, as that auto-identifies the mailing list address from its
+config file stored in git.
+
 Review process
 --------------
 
-- 
2.48.1

On Mon, Mar 17, 2025 at 11:23:00 +0000, Daniel P. Berrangé via Devel wrote:
> From: Daniel P. Berrangé <berrange@redhat.com>
> 
> If a contributor's email domain has a DMARC policy of 'p=quarantine'
> or 'p=reject', mailman will apply DMARC countermeasures on all mails
> sent to lists.libvirt.org rewriting the "From" header to remove the
> sender's email address. e.g.
> 
>   From: Your Name via <lists.libvirt.org>
> 
> If these countermeasures were not applied, affected mail would either
> have gon directly to SPAM, or have been entirely rejected. Mailman3

s/gon/gone/

> is unable to be configured to guarantee no mangling of the mail body
> so these countermeasures are unavoidable for lists.libvirt.org.
> 
> Amongst the various downsides, the From address rewriting has the
> bad effect of mangling git commit author attribution.
> 
> To avoid this it is required to add two additional git config
> settings:
> 
>   $ git config --global format.from "Your Name <your@email.com>"
>   $ git config --global format.forceInBodyFrom true
> 
> Note, *both* are required, even if your ``format.from`` matches
> your existing git identity, because the latter only takes effect
> once the former is set.
> 
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

Thanks a lot.

Reviewed-by: Jiri Denemark <jdenemar@redhat.com>

On 3/17/25 7:29 AM, Jiri Denemark via Devel wrote:
> On Mon, Mar 17, 2025 at 11:23:00 +0000, Daniel P. Berrangé via Devel wrote:
>> From: Daniel P. Berrangé <berrange@redhat.com>
>>
>> If a contributor's email domain has a DMARC policy of 'p=quarantine'
>> or 'p=reject', mailman will apply DMARC countermeasures on all mails
>> sent to lists.libvirt.org rewriting the "From" header to remove the
>> sender's email address. e.g.
>>
>>    From: Your Name via <lists.libvirt.org>
>>
>> If these countermeasures were not applied, affected mail would either
>> have gon directly to SPAM, or have been entirely rejected. Mailman3
> 
> s/gon/gone/
> 
>> is unable to be configured to guarantee no mangling of the mail body
>> so these countermeasures are unavoidable for lists.libvirt.org.
>>
>> Amongst the various downsides, the From address rewriting has the
>> bad effect of mangling git commit author attribution.
>>
>> To avoid this it is required to add two additional git config
>> settings:
>>
>>    $ git config --global format.from "Your Name <your@email.com>"
>>    $ git config --global format.forceInBodyFrom true
>>
>> Note, *both* are required, even if your ``format.from`` matches
>> your existing git identity, because the latter only takes effect
>> once the former is set.
>>
>> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> 
> Thanks a lot.
> 
> Reviewed-by: Jiri Denemark <jdenemar@redhat.com>

Reviewed-by: Laine Stump via Devel <devel@lists.libvirt.org>

:-)

A couple thoughts:

1) Some people might rather have the email address (and maybe also 
forceInBodyFrom) set for just certain projects rather than globally.

2) Is there a config file that could be part of the project files in the 
main directory that could have "format.forceInBodyFrom true" added 
(similar to how we have a .gitpublish that's checked out with everything 
else)?

3) Maybe this could also/instead be added as a config item to 
git-publish and could be added to the libvirt .gitpublish file so that 
at least it would be automatic for those of us who religiously use 
git-publish. I suppose I should go look at the git-publish source...

On Mon, Mar 17, 2025 at 09:27:51AM -0400, Laine Stump wrote:
> On 3/17/25 7:29 AM, Jiri Denemark via Devel wrote:
> > On Mon, Mar 17, 2025 at 11:23:00 +0000, Daniel P. Berrangé via Devel wrote:
> > > From: Daniel P. Berrangé <berrange@redhat.com>
> > > 
> > > If a contributor's email domain has a DMARC policy of 'p=quarantine'
> > > or 'p=reject', mailman will apply DMARC countermeasures on all mails
> > > sent to lists.libvirt.org rewriting the "From" header to remove the
> > > sender's email address. e.g.
> > > 
> > >    From: Your Name via <lists.libvirt.org>
> > > 
> > > If these countermeasures were not applied, affected mail would either
> > > have gon directly to SPAM, or have been entirely rejected. Mailman3
> > 
> > s/gon/gone/
> > 
> > > is unable to be configured to guarantee no mangling of the mail body
> > > so these countermeasures are unavoidable for lists.libvirt.org.
> > > 
> > > Amongst the various downsides, the From address rewriting has the
> > > bad effect of mangling git commit author attribution.
> > > 
> > > To avoid this it is required to add two additional git config
> > > settings:
> > > 
> > >    $ git config --global format.from "Your Name <your@email.com>"
> > >    $ git config --global format.forceInBodyFrom true
> > > 
> > > Note, *both* are required, even if your ``format.from`` matches
> > > your existing git identity, because the latter only takes effect
> > > once the former is set.
> > > 
> > > Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> > 
> > Thanks a lot.
> > 
> > Reviewed-by: Jiri Denemark <jdenemar@redhat.com>
> 
> Reviewed-by: Laine Stump via Devel <devel@lists.libvirt.org>
> 
> :-)
> 
> A couple thoughts:
> 
> 1) Some people might rather have the email address (and maybe also
> forceInBodyFrom) set for just certain projects rather than globally.

Yes, that's possible but I took the view that if you have strict DMARC
on your domain the only safe option is to always set these settings,
because you can't predict what mailing lists you use will need the
countermeasure. Better to default enabled, but then turn it off for
individual projects if you really want to.

It is harmless to have it added if redundant, and harmful to omit it
if required.

> 
> 2) Is there a config file that could be part of the project files in the
> main directory that could have "format.forceInBodyFrom true" added (similar
> to how we have a .gitpublish that's checked out with everything else)?

The inability to store a local .git/config in git itself is a long term
limitation of git.

> 3) Maybe this could also/instead be added as a config item to git-publish
> and could be added to the libvirt .gitpublish file so that at least it would
> be automatic for those of us who religiously use git-publish. I suppose I
> should go look at the git-publish source...

git-publish calls out to git-format-patch, but I don't see any support
for the --force-in-body-from option there.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|