Improving documentation

2026-05-05 01:30:41 -04:00
parent 203bffbbf8
commit 1f42cd16db
2 changed files with 112 additions and 22 deletions
@@ -1,6 +1,8 @@
 # LWVWV Member Subscription Automation

-Automated Docker container for subscribing LWVWV members to Mailman 3 mailing lists.
+Part of the [LWVWV project](../). This directory contains Docker-based automation for subscribing LWVWV members to Mailman 3 mailing lists via the [mailman-connector](https://git.bikeshopi.dev/bike/mailman-connector) API service.
+
+For standalone script usage (without Docker), see the [main project README](../README.md).

 ## Overview

@@ -25,12 +27,13 @@ This automation coordinates:
   │(portal)  │   │(email-csv)   │   │(connector)   │
   └──────────┘   └──────────────┘   └──────────────┘
                                             │
-                                             ▼
-                                    ┌──────────────┐
-                                    │mailman-      │
-                                    │connector     │
-                                    │(batch sub)   │
-                                    └──────────────┘
+                                     ▼
+                                     ┌──────────────────────────────────┐
+                                     │ [mailman-connector](https://git. │
+                                     │ bikeshopi.dev/bike/mailman-       │
+                                     │ connector) - REST API for batch   │
+                                     │ Mailman 3 subscriptions           │
+                                     └──────────────────────────────────┘
 ```

 ## Files
@@ -68,7 +71,7 @@ $VARIABLE_NAME = "value";
 |----------|-------------|---------|
 | `$CONNECTOR_URL` | URL of mailman-connector | `https://mailman-connector.example.org` |
 | `$CONNECTOR_PASSWORD` | Secret password for connector API | `your_secret_password` |
-| `$MAILMAN_LIST_ID` | Target mailing list ID | `members.lists.example.org` |
+| `$MAILMAN_LIST_ID` | Target mailing list ID(s). Format: `list_id:league_id` or just `list_id`. For multiple lists, use comma-separated values. | `members.lists.lwvwv.org:WV000` or `list1:WV000, list2:WV103` |

 #### Required for Portal Download
 | Variable | Description | Example |
@@ -121,6 +124,35 @@ $stateLeagueID = "WV000";
 $localLeagueIDs = "WV102|WV103|WV112";
 ```

+### Multi-List Configuration with League Filtering
+
+When managing multiple local leagues, you can subscribe different member groups to different lists using the colon-separated format:
+
+```perl
+# Format: list_id:league_id
+# State list gets WV000 members, Morgantown list gets WV103 members
+$MAILMAN_LIST_ID = "members.lists.lwvwv.org:WV000, morgantown.lists.lwvwv.org:WV103";
+```
+
+**How it works:**
+- **list_id**: The Mailman list identifier (e.g., `members.lists.lwvwv.org`)
+- **league_id**: The LWV League ID to filter members (e.g., `WV000`, `WV103`, or `ALL`)
+- If `:league_id` is omitted, defaults to `ALL` (all members)
+
+**Examples:**
+```perl
+# Single list, all members
+$MAILMAN_LIST_ID = "members.lists.lwvwv.org";
+
+# Single list, only state (WV000) members
+$MAILMAN_LIST_ID = "members.lists.lwvwv.org:WV000";
+
+# Multiple lists with different league filters
+$MAILMAN_LIST_ID = "members.lists.lwvwv.org:WV000, morgantown.lists.lwvwv.org:WV103, huntington.lists.lwvwv.org:WV102";
+```
+
+The script filters the roster by League ID before subscribing, so each list only receives its members.
+
 ## Quick Start

 ### 1. Configure Environment
@@ -243,3 +275,9 @@ The container needs access to:
 - Sensitive data is never committed to git
 - Session file (`.session.json`) is also mounted read-only
 - All scripts use the single `../env` file - no duplicated configuration
+
+
+## See Also
+
+- **[Main Project README](../README.md)** - Standalone script usage, Google Civic API documentation, and general project information
+- **[mailman-connector](https://git.bikeshopi.dev/bike/mailman-connector)** - The REST API service used for batch Mailman 3 subscriptions