1 files changed, 183 insertions, 0 deletions
diff --git a/Mailman/docs/membership.txt b/Mailman/docs/membership.txt
new file mode 100644
index 000000000..36b1508a8
--- /dev/null
+++ b/Mailman/docs/membership.txt
@@ -0,0 +1,183 @@
+List memberships
+================
+
+Users represent people in Mailman.  Users control email addresses, and rosters
+are collectons of members.  A member gives an email address a role, such as
+'member', 'administrator', or 'moderator'.  Roster sets are collections of
+rosters and a mailing list has a single roster set that contains all its
+members, regardless of that member's role.
+
+Mailing lists and roster sets have an indirect relationship, through the
+roster set's name.  Roster also have names, but are related to roster sets
+by a more direct containment relationship.  This is because it is possible to
+store mailing list data in a different database than user data.
+
+When we create a mailing list, it starts out with no members...
+
+    >>> from Mailman.configuration import config
+    >>> from Mailman.database import flush
+    >>> mlist = config.list_manager.create('_xtest@example.com')
+    >>> flush()
+    >>> mlist
+    <mailing list "_xtest@example.com" (unlocked) at ...>
+    >>> sorted(member.address.address for member in mlist.members.members)
+    []
+    >>> sorted(user.real_name for user in mlist.members.users)
+    []
+    >>> sorted(address.address for member in mlist.members.addresses)
+    []
+
+...no owners...
+
+    >>> sorted(member.address.address for member in mlist.owners.members)
+    []
+    >>> sorted(user.real_name for user in mlist.owners.users)
+    []
+    >>> sorted(address.address for member in mlist.owners.addresses)
+    []
+
+...no moderators...
+
+    >>> sorted(member.address.address for member in mlist.moderators.members)
+    []
+    >>> sorted(user.real_name for user in mlist.moderators.users)
+    []
+    >>> sorted(address.address for member in mlist.moderators.addresses)
+    []
+
+...and no administrators.
+
+    >>> sorted(member.address.address
+    ...        for member in mlist.administrators.members)
+    []
+    >>> sorted(user.real_name for user in mlist.administrators.users)
+    []
+    >>> sorted(address.address for member in mlist.administrators.addresses)
+    []
+
+
+
+Administrators
+--------------
+
+A mailing list's administrators are defined as union of the list's owners and
+the list's moderators.  We can add new owners or moderators to this list by
+assigning roles to users.  First we have to create the user, because there are
+no users in the user database yet.
+
+    >>> user_1 = config.user_manager.create_user(
+    ...     'aperson@example.com', 'Anne Person')
+    >>> flush()
+    >>> user_1.real_name
+    'Anne Person'
+    >>> sorted(address.address for address in user_1.addresses)
+    ['aperson@example.com']
+
+We can add Anne as an owner of the mailing list, by creating a member role for
+her.
+
+    >>> from Mailman.constants import MemberRole
+    >>> address_1 = list(user_1.addresses)[0]
+    >>> address_1.address
+    'aperson@example.com'
+    >>> address_1.subscribe(mlist, MemberRole.owner)
+    <Member: Anne Person <aperson@example.com> on
+             _xtest@example.com as MemberRole.owner>
+    >>> flush()
+    >>> sorted(member.address.address for member in mlist.owners.members)
+    ['aperson@example.com']
+    >>> sorted(user.real_name for user in mlist.owners.users)
+    ['Anne Person']
+    >>> sorted(address.address for address in mlist.owners.addresses)
+    ['aperson@example.com']
+
+Adding Anne as a list owner also makes her an administrator, but does not make
+her a moderator.  Nor does it make her a member of the list.
+
+    >>> sorted(user.real_name for user in mlist.administrators.users)
+    ['Anne Person']
+    >>> sorted(user.real_name for user in mlist.moderators.users)
+    []
+    >>> sorted(user.real_name for user in mlist.members.users)
+    []
+
+We can add Ben as a moderator of the list, by creating a different member role
+for him.
+
+    >>> user_2 = config.user_manager.create_user(
+    ...     'bperson@example.com', 'Ben Person')
+    >>> flush()
+    >>> user_2.real_name
+    'Ben Person'
+    >>> address_2 = list(user_2.addresses)[0]
+    >>> address_2.address
+    'bperson@example.com'
+    >>> address_2.subscribe(mlist, MemberRole.moderator)
+    <Member: Ben Person <bperson@example.com>
+             on _xtest@example.com as MemberRole.moderator>
+    >>> flush()
+    >>> sorted(member.address.address for member in mlist.moderators.members)
+    ['bperson@example.com']
+    >>> sorted(user.real_name for user in mlist.moderators.users)
+    ['Ben Person']
+    >>> sorted(address.address for address in mlist.moderators.addresses)
+    ['bperson@example.com']
+
+Now, both Anne and Ben are list administrators.
+
+    >>> sorted(member.address.address
+    ...        for member in mlist.administrators.members)
+    ['aperson@example.com', 'bperson@example.com']
+    >>> sorted(user.real_name for user in mlist.administrators.users)
+    ['Anne Person', 'Ben Person']
+    >>> sorted(address.address for address in mlist.administrators.addresses)
+    ['aperson@example.com', 'bperson@example.com']
+
+
+Members
+-------
+
+Similarly, list members are born of users being given the proper role.  It's
+more interesting here because these roles should have a preference which can
+be used to decide whether the member is to get regular delivery or digest
+delivery.  Without a preference, Mailman will fall back first to the address's
+preference, then the user's preference, then the list's preference.  Start
+without any member preference to see the system defaults.
+
+    >>> user_3 = config.user_manager.create_user(
+    ...     'cperson@example.com', 'Claire Person')
+    >>> flush()
+    >>> user_3.real_name
+    'Claire Person'
+    >>> address_3 = list(user_3.addresses)[0]
+    >>> address_3.address
+    'cperson@example.com'
+    >>> address_3.subscribe(mlist, MemberRole.member)
+    <Member: Claire Person <cperson@example.com>
+             on _xtest@example.com as MemberRole.member>
+    >>> flush()
+
+Claire will be a regular delivery member but not a digest member.
+
+    >>> sorted(address.address for address in mlist.members.addresses)
+    ['cperson@example.com']
+    >>> sorted(address.address for address in mlist.regular_members.addresses)
+    ['cperson@example.com']
+    >>> sorted(address.address for address in mlist.digest_members.addresses)
+    []
+
+It's easy to make the list administrators members of the mailing list too.
+
+    >>> for address in mlist.administrators.addresses:
+    ...     address.subscribe(mlist, MemberRole.member)
+    <Member: Ben Person <bperson@example.com> on
+             _xtest@example.com as MemberRole.member>
+    <Member: Anne Person <aperson@example.com> on
+             _xtest@example.com as MemberRole.member>
+    >>> flush()
+    >>> sorted(address.address for address in mlist.members.addresses)
+    ['aperson@example.com', 'bperson@example.com', 'cperson@example.com']
+    >>> sorted(address.address for address in mlist.regular_members.addresses)
+    ['aperson@example.com', 'bperson@example.com', 'cperson@example.com']
+    >>> sorted(address.address for address in mlist.digest_members.addresses)
+    []