Update mailing list documentation

docs/index.rst

@@ -1258,16 +1258,102 @@ What about mailing lists?
 When you deploy DMARC on your domain, you might find that messages relayed by
 mailing lists are failing DMARC, most likely because the mailing list is
 spoofing your from address, and modifying the subject, footer, or other part
-of the message.
+of the message, thereby breaking the DKIM signature.
 
-To fix this, the mailing list administrator must configure the list to replace
-the from address of the message (also known as munging) with the address of
-the mailing list, so they no longer spoof email addresses with domains
-protected by DMARC. Configuration steps for common mailing list platforms are
-listed below.
+Mailing list list best practices
+--------------------------------
+
+Ideally, a mailing list should forward messages without altering the headers
+or body content at all. `Joe Nelson`_ does a fantastic job of explaining exactly
+what mailing lists should and shouldn't do to be fully DMARC compliant.
+Rather than repeat his fine work, here's a summary:
+
+**Do**
+
+- Retain headers from the original message
+- Add `RFC 2369`_ List-Unsubscribe headers to outgoing messages, instead of
+  adding unsubscribe links to the body
+
+   ::
+
+      List-Unsubscribe: <https://list.example.com/unsubscribe-link>
+
+- Add `RFC 2919`_ List-Id headers instead of modifying the subject
+
+   ::
+
+      List-Id: Example Mailing List <list.example.com>
+
+**Do not**
+
+* Remove or modify any existing headers from the original message, including
+  From, Date, Subject, etc.
+* Add to or remove content from the message body, **including traditional
+  disclaimers and unsubscribe footers**
+
+In addition to complying with DMARC, this configuration ensures that Reply
+and Reply All actions work like they would with any email message. Reply
+replies to the message sender, and Reply All replies to the sender and the
+list.
+
+Configuration steps for common mailing list platforms are listed below.
 
 Mailman 2
-----------
+~~~~~~~~~
+
+Navigate to General Settings, and configure the settings below
+
+============================ ==========
+**Setting**                  **Value**
+**subject_prefix**
+**from_is_list**             No
+**first_strip_reply_to**     No
+**reply_goes_to_list**       Poster
+**include_rfc2369_headers**  Yes
+**include_list_post_header** Yes
+**include_sender_header**    No
+============================ ==========
+
+Navigate to Non-digest options, and configure the settings below
+
+=================== ==========
+**Setting**         **Value**
+**msg_header**
+**msg_footer**
+**scrub_nondigest**  No
+=================== ==========
+
+
+Navigate to Privacy Options> Sending Filters, and configure the settings below
+
+====================================== ==========
+**Setting**                            **Value**
+**dmarc_moderation_action**            Accept
+**dmarc_quarentine_moderation_action** Yes
+**dmarc_none_moderation_action**       Yes
+====================================== ==========
+
+
+Mailman 3
+~~~~~~~~~
+
+Mailman 3 does not currently have a easy way of removing the message
+footer, like Mailman 2 did. For now, it is best to use the workaround
+(i.e. DMARC mitigation), as described below.
+
+Workarounds
+-----------
+
+If a mailing list must go **against** best practices and
+modify the message (e.g. to add a required legal footer), the mailing
+list administrator must configure the list to replace the From address of the
+message (also known as munging) with the address of the mailing list, so they
+no longer spoof email addresses with domains protected by DMARC.
+
+Configuration steps for common mailing list platforms are listed below.
+
+Mailman 2
+~~~~~~~~~
 
 Navigate to Privacy Options> Sending Filters, and configure the settings below
 
@@ -1278,21 +1364,42 @@ Navigate to Privacy Options> Sending Filters, and configure the settings below
 **dmarc_none_moderation_action**       Yes
 ====================================== ==========
 
+.. note::
+   Message wrapping can also be used as the DMARC mitigation action, where the
+   original message is added as an attachment to the mailing list message,
+   but that could interfere with message search, or mobile clients.
+
 Mailman 3
----------
+~~~~~~~~~
 
 In the DMARC Mitigations tab of the Settings page, configure the settings below
 
 ================================== ===============================
 **Setting**	                       **Value**
 **DMARC mitigation action**	       Replace From: with list address
-**DMARC Mitigate unconditionally** No
+**DMARC mitigate unconditionally** No
 ================================== ===============================
 
-LISTSERV
---------
+.. note::
+    Message wrapping can also be used as the DMARC mitigation action, where the
+    original message is added as an attachment to the mailing list message,
+    but that could interfere with message search, or mobile clients.
 
-`LISTSERV 16.0-2017a`_ and higher will rewrite the From header. Some additional steps are needed for Linux hosts.
+    On the other hand, replacing the ``From`` address might cause users to
+    accident reply to the entire list, when they only intended to reply to
+    the original sender.
+
+    Choose the option that best fits your community.
+
+
+
+LISTSERV
+~~~~~~~~
+
+`LISTSERV 16.0-2017a`_ and higher will rewrite the From header for domains
+that enforce with a DMARC quarantine or reject policy.
+
+Some additional steps are needed for Linux hosts.
 
 API
 ===
@@ -1369,4 +1476,10 @@ Indices and tables
 
 .. _XML files: https://github.com/domainaware/parsedmarc/tree/master/splunk
 
+.. _Joe Nelson: https://begriffs.com/posts/2018-09-18-dmarc-mailing-list.html
+
+.. _RFC 2369: https://tools.ietf.org/html/rfc2369
+
+.. _RFC 2919: https://tools.ietf.org/html/rfc2919
+
 .. _LISTSERV 16.0-2017a: https://www.lsoft.com/news/dmarc-issue1-2018.asp