1 files changed, 136 insertions, 0 deletions
diff --git a/src/mailman/docs/lifecycle.txt b/src/mailman/docs/lifecycle.txt
new file mode 100644
index 000000000..c6c0c0671
--- /dev/null
+++ b/src/mailman/docs/lifecycle.txt
@@ -0,0 +1,136 @@
+Application level list lifecycle
+--------------------------------
+
+The low-level way to create and delete a mailing list is to use the
+IListManager interface.  This interface simply adds or removes the appropriate
+database entries to record the list's creation.
+
+There is a higher level interface for creating and deleting mailing lists
+which performs additional tasks such as:
+
+ * validating the list's posting address (which also serves as the list's
+   fully qualified name);
+ * ensuring that the list's domain is registered;
+ * applying all matching styles to the new list;
+ * creating and assigning list owners;
+ * notifying watchers of list creation;
+ * creating ancillary artifacts (such as the list's on-disk directory)
+
+    >>> from mailman.app.lifecycle import create_list
+
+
+Posting address validation
+--------------------------
+
+If you try to use the higher-level interface to create a mailing list with a
+bogus posting address, you get an exception.
+
+    >>> create_list('not a valid address')
+    Traceback (most recent call last):
+    ...
+    InvalidEmailAddress: 'not a valid address'
+
+If the posting address is valid, but the domain has not been registered with
+Mailman yet, you get an exception.
+
+    >>> create_list('test@example.org')
+    Traceback (most recent call last):
+    ...
+    BadDomainSpecificationError: example.org
+
+
+Creating a list applies its styles
+----------------------------------
+
+Start by registering a test style.
+
+    >>> from zope.interface import implements
+    >>> from mailman.interfaces.styles import IStyle
+    >>> class TestStyle(object):
+    ...     implements(IStyle)
+    ...     name = 'test'
+    ...     priority = 10
+    ...     def apply(self, mailing_list):
+    ...         # Just does something very simple.
+    ...         mailing_list.msg_footer = u'test footer'
+    ...     def match(self, mailing_list, styles):
+    ...         # Applies to any test list
+    ...         if 'test' in mailing_list.fqdn_listname:
+    ...             styles.append(self)
+
+    >>> config.style_manager.register(TestStyle())
+
+Using the higher level interface for creating a list, applies all matching
+list styles.
+
+    >>> mlist_1 = create_list(u'test_1@example.com')
+    >>> mlist_1.fqdn_listname
+    u'test_1@example.com'
+    >>> mlist_1.msg_footer
+    u'test footer'
+
+
+Creating a list with owners
+---------------------------
+
+You can also specify a list of owner email addresses.  If these addresses are
+not yet known, they will be registered, and new users will be linked to them.
+However the addresses are not verified.
+
+    >>> owners = [u'aperson@example.com', u'bperson@example.com',
+    ...           u'cperson@example.com', u'dperson@example.com']
+    >>> mlist_2 = create_list(u'test_2@example.com', owners)
+    >>> mlist_2.fqdn_listname
+    u'test_2@example.com'
+    >>> mlist_2.msg_footer
+    u'test footer'
+    >>> sorted(addr.address for addr in mlist_2.owners.addresses)
+    [u'aperson@example.com', u'bperson@example.com',
+     u'cperson@example.com', u'dperson@example.com']
+
+None of the owner addresses are verified.
+
+    >>> any(addr.verified_on is not None for addr in mlist_2.owners.addresses)
+    False
+
+However, all addresses are linked to users.
+
+    >>> # The owners have no names yet
+    >>> len(list(mlist_2.owners.users))
+    4
+
+If you create a mailing list with owner addresses that are already known to
+the system, they won't be created again.
+
+    >>> usermgr = config.db.user_manager
+    >>> user_a = usermgr.get_user(u'aperson@example.com')
+    >>> user_b = usermgr.get_user(u'bperson@example.com')
+    >>> user_c = usermgr.get_user(u'cperson@example.com')
+    >>> user_d = usermgr.get_user(u'dperson@example.com')
+    >>> user_a.real_name = u'Anne Person'
+    >>> user_b.real_name = u'Bart Person'
+    >>> user_c.real_name = u'Caty Person'
+    >>> user_d.real_name = u'Dirk Person'
+
+    >>> mlist_3 = create_list(u'test_3@example.com', owners)
+    >>> sorted(user.real_name for user in mlist_3.owners.users)
+    [u'Anne Person', u'Bart Person', u'Caty Person', u'Dirk Person']
+
+
+Removing a list
+---------------
+
+Removing a mailing list deletes the list, all its subscribers, and any related
+artifacts.
+
+    >>> from mailman.app.lifecycle import remove_list
+    >>> remove_list(mlist_2.fqdn_listname, mlist_2, True)
+    >>> print config.db.list_manager.get('test_2@example.com')
+    None
+
+We should now be able to completely recreate the mailing list.
+
+    >>> mlist_2a = create_list(u'test_2@example.com', owners)
+    >>> sorted(addr.address for addr in mlist_2a.owners.addresses)
+    [u'aperson@example.com', u'bperson@example.com',
+     u'cperson@example.com', u'dperson@example.com']