service/lists.md

-Our mailing list server, <https://lists.torproject.org>, is running an instance
-of Mailman.
+Our mailing list server, <https://lists.torproject.org>, is running an
+instance of Mailman.
 
 The "listmaster" team is responsible for configuring all lists as
 required. They make decisions about which lists to create and which
@@ -13,11 +13,6 @@ coordinate with the admin team to have the list added and then
 configure it as needed. Don't forget to update the [list of mailing
 lists](#list-of-mailing-lists) (below) upon changes.
 
-IMPORTANT NOTE: the documentation here is going to become out of date
-quickly as we upgrade to Mailman 3, see
-<https://gitlab.torproject.org/tpo/tpa/team/-/issues/40471> for
-tracking this work, which includes updating this document.
-
 [[_TOC_]]
 
 # Tutorial
@@ -320,13 +315,12 @@ through the web interface.
 
 ## Upgrades
 
-<!-- how upgrades are performed. preferably automated through Debian -->
-<!-- packages, otherwise document how upgrades are performed. see also -->
-<!-- the Testing section below -->
+It's unclear how automated Mailman 3 upgrades will be, but right now
+we're relying on Debian packages for this.
 
 ## SLA
 
-<!-- this describes an acceptable level of service for this service -->
+There's no SLA specifically associated with this service.
 
 ## Design and architecture
 
@@ -343,8 +337,6 @@ TODO mention zope and django in the same sentence
 
 ## Services
 
-<!-- open ports, daemons, cron jobs -->
-
 As mentioned in the architecture, Mailman is made of different
 components who communicate over HTTP, typically. Cron jobs handle
 indexing lists for searching.
@@ -359,14 +351,24 @@ conf`, but be careful as it outputs cleartext passwords.
 
 ## Storage
 
-<!-- databases? plain text file? the frigging blockchain? memory? -->
+Most data is stored in a [PostgreSQL](howto/postgresql) database, apart from bounces
+which somehow seem to exist in [Python pickle files](https://docs.python.org/3/library/pickle.html) in
+`/var/lib/mailman3/queue/bounces`. 
+
+A list of addresses is stored in `/var/spool/postfix/mailman3` for
+Postfix to know about mailing lists. There's the trace of a SQLite
+database there, but it is believed to be stale.
 
 ## Queues
 
-<!-- email queues, job queues, schedulers -->
+Mailman seems to store Python objects of in-flight emails (like
+bounces to retry) in `/var/lib/mailman3/queue`.
 
 ## List of mailing lists
 
+TODO: remove this entry. If a mailing list should be publicly listed,
+just list the damn thing already.
+
 ### Discussion Lists
 
 The following are lists with subscriber generated threads.
@@ -537,12 +539,23 @@ be used to operate the API, rather confusingly.
 
 ## Authentication
 
-<!-- SSH? LDAP? standalone? -->
+Mailman has its own authentication database, isolated from all the
+others. Ideally it would reuse LDAP, and it might be possible to hook
+it to GitLab's OIDC provider.
 
 ## Implementation
 
 <!-- programming languages, frameworks, versions, license -->
 
+Mailman 3 is one of the flagship projects implemented in
+Python 3. The web interface is built on top of [Django](https://docs.djangoproject.com/), while the
+REST API is built on top of [Zope](https://zope.readthedocs.io/).
+
+Debian ships Mailman 3.3.8, a little behind the latest upstream
+3.3.10, released in October 2024.
+
+Mailman 3 is GPLv3.
+
 ## Related services
 
 <!-- dependent services (e.g. authenticates against LDAP, or requires -->