[Mailman-Users] 2.1.18 internal documentation suggestions

[Stephen J. Turnbull]

Mark Sapiro writes:

 > I changed it. In the 2.1.18 final it will say:
 > 
 > -------------------------------------------------------------
 > from_is_list (general): Replace the sender with the list address to
 > conform with policies like DMARC.
 > 
 > Replace the sender with the list address to conform with policies like
 > ADSP and DMARC. It replaces the poster's address in the From: header
 > with the list address and adds the poster to the Reply-To: header.
 > 
 > If this is set to Wrap Message, just wrap the message in an outer
 > message From: the list with Content-Type: message/rfc822.

Ouch!  I'd really like to change this variable's name!  (It's not very
easy to understand anyway; grammatically the semantics are "whatever
you see in From is {a, the} list", not "replace whatever is in From
with the list's address".)

Something like "from_alignment", with values None (don't try to align
domains in From), 'shift author' (From into Reply-To, <list> into
From), or 'wrap message'.

May as well rewrite the doc ... here goes:

    from_alignment:  Try to ensure that From is not "misaligned" with
    the author's domain, to conform with protocols like DMARC.
    [FIXME: I don't see how to avoid the double negative.  Help?!]

    This setting replaces the from_is_list setting, which is now
    deprecated.  Existing from_is_list settings will be respected.

    Several protocols now in wide use attempt to ensure that use of
    the domain in the author's address (ie, in the From header field)
    is authorized by that domain.  These protocols may be incompatible
    with common list features such as footers, causing participating
    email services to bounce list traffic merely because of the
    address in the From field.  *This has resulted in members being
    unsubscribed despite being perfectly able to receive mail.*

    The following actions are applied to messages where use of such a
    protocol is detected by Mailman.  [FIXME: Is that correct?]

    Valid values:

    'no': Do nothing special.  This is appropriate for anonymous lists.
    It is appropriate for dedicated announcement lists, unless the
    "From" address is not within the Mailman host's domain.  [FIXME:
    Maybe None is a better value here.  Of course that's not backward
    compatible, but with the name change it would be possible to check
    the old from_is_list.]

    'shift author': Shift the address(es) in From to Reply-To
    (preserving existing addresses in Reply-To), and insert the list's
    [posting?] address in From.

    'wrap message': Treat the message as a MIME forward with list in
    From and the original message encapsulated in a MIME message/rfc822
    part.  Subscribers will perceive this as a "one message digest".
    [FIXME: Should this respect the MIME vs. legacy encapsulation
    ('digest') setting?  If 'yes', that setting should move to General
    or so?]

 > These settings play as expected with the anonymous_list and Reply-To:

What does "as expected" mean?  (If *I* have to ask.... :-)

 > header munging settings below with the exception of adding "via
 > real_name" to the display name in the From: for an anonymous list and

??  Adding real name to From in an *anonymous* list?

 > adding the poster's address to Reply-To: in almost all cases.
 > 
 > If anonymous_list is Yes, there is no reason to set from_is_list to
 > anything other than No.

Unnecessary with my wording above.

 > If dmarc_moderation_action applies to this message with an action other
 > than Accept, that action rather than this is applied

This doesn't seem correct.  True, if Reject (aka "emit backscatter")
or Discard, the message will never reach this point.  But if it's
Hold, this processing will be applied if the message is accepted by
the moderator.  How about

    See also dmarc_moderation_action (which will be applied earlier in
    processing than this feature).