1 files changed, 159 insertions, 0 deletions

diff --git a/src/mailman/pipeline/docs/acknowledge.txt b/src/mailman/pipeline/docs/acknowledge.txt
new file mode 100644
index 000000000..a4c68f900
--- /dev/null
+++ b/src/mailman/pipeline/docs/acknowledge.txt
@@ -0,0 +1,159 @@
+Message acknowledgment
+======================
+
+When a user posts a message to a mailing list, and that user has chosen to
+receive acknowledgments of their postings, Mailman will sent them such an
+acknowledgment.
+
+    >>> handler = config.handlers['acknowledge']
+    >>> mlist = config.db.list_manager.create(u'_xtest@example.com')
+    >>> mlist.real_name = u'XTest'
+    >>> mlist.preferred_language = u'en'
+    >>> # XXX This will almost certainly change once we've worked out the web
+    >>> # space layout for mailing lists now.
+
+    >>> # Ensure that the virgin queue is empty, since we'll be checking this
+    >>> # for new auto-response messages.
+    >>> virginq = config.switchboards['virgin']
+    >>> virginq.files
+    []
+
+Subscribe a user to the mailing list.
+
+    >>> usermgr = config.db.user_manager
+    >>> from mailman.interfaces.member import MemberRole
+    >>> user_1 = usermgr.create_user(u'aperson@example.com')
+    >>> address_1 = list(user_1.addresses)[0]
+    >>> address_1.subscribe(mlist, MemberRole.member)
+    <Member: aperson@example.com on _xtest@example.com as MemberRole.member>
+
+
+Non-member posts
+----------------
+
+Non-members can't get acknowledgments of their posts to the mailing list.
+
+    >>> msg = message_from_string("""\
+    ... From: bperson@example.com
+    ...
+    ... """)
+    >>> handler.process(mlist, msg, {})
+    >>> virginq.files
+    []
+
+We can also specify the original sender in the message's metadata.  If that
+person is also not a member, no acknowledgment will be sent either.
+
+    >>> msg = message_from_string("""\
+    ... From: bperson@example.com
+    ...
+    ... """)
+    >>> handler.process(mlist, msg,
+    ...     dict(original_sender=u'cperson@example.com'))
+    >>> virginq.files
+    []
+
+
+No acknowledgment requested
+---------------------------
+
+Unless the user has requested acknowledgments, they will not get one.
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ...
+    ... """)
+    >>> handler.process(mlist, msg, {})
+    >>> virginq.files
+    []
+
+Similarly if the original sender is specified in the message metadata, and
+that sender is a member but not one who has requested acknowledgments, none
+will be sent.
+
+    >>> user_2 = usermgr.create_user(u'dperson@example.com')
+    >>> address_2 = list(user_2.addresses)[0]
+    >>> address_2.subscribe(mlist, MemberRole.member)
+    <Member: dperson@example.com on _xtest@example.com as MemberRole.member>
+
+    >>> handler.process(mlist, msg,
+    ...     dict(original_sender=u'dperson@example.com'))
+    >>> virginq.files
+    []
+
+
+Requested acknowledgments
+-------------------------
+
+If the member requests acknowledgments, Mailman will send them one when they
+post to the mailing list.
+
+    >>> user_1.preferences.acknowledge_posts = True
+
+The receipt will include the original message's subject in the response body,
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ... Subject: Something witty and insightful
+    ...
+    ... """)
+    >>> handler.process(mlist, msg, {})
+    >>> len(virginq.files)
+    1
+    >>> qmsg, qdata = virginq.dequeue(virginq.files[0])
+    >>> virginq.files
+    []
+    >>> sorted(qdata.items())
+    [..., ('recips', [u'aperson@example.com']), ...]
+    >>> print qmsg.as_string()
+    ...
+    MIME-Version: 1.0
+    ...
+    Subject: XTest post acknowledgment
+    From: _xtest-bounces@example.com
+    To: aperson@example.com
+    ...
+    Precedence: bulk
+    <BLANKLINE>
+    Your message entitled
+    <BLANKLINE>
+        Something witty and insightful
+    <BLANKLINE>
+    was successfully received by the XTest mailing list.
+    <BLANKLINE>
+    List info page: http://lists.example.com/listinfo/_xtest@example.com
+    Your preferences: http://example.com/aperson@example.com
+    <BLANKLINE>
+
+If there is no subject, then the receipt will use a generic message.
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.com
+    ...
+    ... """)
+    >>> handler.process(mlist, msg, {})
+    >>> len(virginq.files)
+    1
+    >>> qmsg, qdata = virginq.dequeue(virginq.files[0])
+    >>> virginq.files
+    []
+    >>> sorted(qdata.items())
+    [..., ('recips', [u'aperson@example.com']), ...]
+    >>> print qmsg.as_string()
+    MIME-Version: 1.0
+    ...
+    Subject: XTest post acknowledgment
+    From: _xtest-bounces@example.com
+    To: aperson@example.com
+    ...
+    Precedence: bulk
+    <BLANKLINE>
+    Your message entitled
+    <BLANKLINE>
+        (no subject)
+    <BLANKLINE>
+    was successfully received by the XTest mailing list.
+    <BLANKLINE>
+    List info page: http://lists.example.com/listinfo/_xtest@example.com
+    Your preferences: http://example.com/aperson@example.com
+    <BLANKLINE>