service/lists.md

@@ -165,6 +165,23 @@ new account just like during the first install, with:
 
 The `USER-admin` account must not already exist.
 
+### What changed?
+
+Mailman 3 is a major upgrade from Mailman 2 and essentially a
+rewrite. While some concepts (like "invitations", "moderators" and
+"archives") remain, the entire user interface, archiver, and mail
+processors were rebuild from scratch.
+
+This implies that things are radically different. The [list member
+manual](https://docs.mailman3.org/en/latest/userguide.html) should help you find your way around the interface.
+
+### Why upgrade?
+
+We upgraded to Mailman 3 because Mailman 2 is unsupported upstream and
+the Debian machine hosting it was running an unsupported version of
+Debian for this reason. See [TPA-RFC-71](https://gitlab.torproject.org/tpo/tpa/team/-/wikis/policy/tpa-rfc-71-emergency-email-deployments-round-2) for more background. The
+[upstream upgrade guide](https://docs.mailman3.org/en/latest/migration.html) also has some reasoning.
+
 ## Pager playbook
 
 <!-- information about common errors from the monitoring system and -->
@@ -304,6 +321,8 @@ TODO: explain a bit the mailman3 architecture, see https://docs.mailman3.org/en/
 
 <!-- open ports, daemons, cron jobs -->
 
+TODO: document config files https://docs.mailman3.org/en/latest/django-primer.html
+
 ## Storage
 
 <!-- databases? plain text file? the frigging blockchain? memory? -->
@@ -435,7 +454,52 @@ See [schleuder](service/schleuder) for more information on that service.
 
 ## Interfaces
 
-<!-- e.g. web APIs, commandline clients, etc -->
+Mailman 3 has multiple interfaces and entry points, it's actually
+quite confusing. 
+
+### REST API
+
+The core of the server is a REST API server with a [documented API](https://docs.mailman3.org/projects/mailman/en/latest/src/mailman/rest/docs/rest.html)
+but operating this is not exactly practical.
+
+### CLI
+
+In practice, most interactions with the API can be more usefully done
+by using the `mailman-wrapper` command, with one of the [documented
+commands](https://docs.mailman3.org/projects/mailman/en/latest/src/mailman/commands/docs/commands.html).
+
+Note that the documentation around those commands is particularly
+confusing because it's written in Python instead of shell. Once you
+understand how it works, however, it's relatively simple to figure out
+what it means. Take this example:
+
+    command('mailman addmembers --help')
+
+This is equivalent to the shell command:
+
+    mailman addmembers --help
+
+A more complicated example requires (humanely) parsing Python, like in
+this example:
+
+    command('mailman addmembers ' + filename + ' bee.example.com')
+
+... that actually means this shell command:
+
+    mailman addmembers $filename bee.example.com
+
+... where `$filename` is a text file with a members list.
+
+### Web (Postorius)
+
+The web interface to the Mailman REST API is a Django program called
+"Postorious". It features the usual clicky interface one would expect
+from a website and, contrary to Mailman 2, has a centralized user
+databse, so that you have a single username and password for all
+lists. 
+
+That user databse, however, is unique to the web frontend, and cannot
+be used to operate the API, rather confusingly.
 
 ## Authentication