docs: mailing-lists explanation + manage-mailing-lists polish - #79
Merged
Conversation
Second of the two docs offers from the dev-list thread on Final Prep for v2. Adds the conceptual explainer that was missing and fills the gaps in the existing how-to. ## docs/explanations/mailing-lists.md (new) The conceptual model. Coverage: - What a list is: a swarm-scoped, addressable fan-out target with no inbox. - The address shape: list:<name>@<swarm>@<host>, with the list: prefix as the distinguishing marker against the agent / user / admin shapes. - Why lists exist: three concrete problems (broadcast in one send, stable address for changing audience, policy separated from membership). - Anatomy: name, swarm, host, owner, members, policy, metadata. Canonical address immutable; policy and members mutable. - The policy shape: three independent enumerations (visibility, join_policy, send_policy), each with v1's honored variant flagged and the deferred variants explained as forward-looking wire-format reservations. - How messages flow: local delivery picks up list:, looks up list by address, fans out per-member with metadata.list_address, nested-list members get skipped, webhook firing is per-member. - Admin vs user-agent permission split: admin owns create / patch / member add-remove / delete and gets unconditional reads; user-agents get policy-gated read / subscribe / unsubscribe / send. - Addressability examples (table of the four address shapes). - Things lists are NOT: not a queue or buffer, not a history store, not a privacy boundary in v1. Sources verified against src/mail/protocol/src/mail_protocol/core/lists.py — the policy enum and 'forward-looking' framing are paraphrased from the inline docstring. ## docs/howtos/manage-mailing-lists.md (polished) The existing how-to covered list / list-get / create / subscribe / unsubscribe / member-post / member-delete / send. Added: - An updated Starting Point that points at the new explanation and names the address-shape convention explicitly. - Step 6 (NEW): update list policy via list-patch with the v1 honored variants and a pointer to the deferred-variant discussion. - Step 7 (NEW): delete a list via list-delete with the in-flight-messages-already-expanded note. - Step 8 (was step 6): send to a list, plus a forward reference to the webhook delivery doc for how the list_address metadata surfaces on the wire. - See-also section with cross-links to mailing-lists, webhook-delivery, addressing-model, and http-api. ## docs/explanations/README.md Index row added for the new mailing-lists explainer.
Signed-off-by: Addison Kline <77369109+addisonkline@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Mailing-lists docs for the v2 release (second of two offers from the dev-list thread)
The companion to PR #78 (webhook docs). Adds the missing
conceptual explainer for mailing lists and rounds out the
existing how-to with the verbs that were absent.
New page
docs/explanations/mailing-lists.md— the conceptual model:what a list is (swarm-scoped, addressable, inbox-less
fan-out target), why lists exist, the anatomy (name / swarm
/ host / owner / members / policy), the three-axis policy
shape with v1 honored variants flagged, message flow
through the local-delivery path, the admin vs user-agent
permission split, address-shape examples, and a "things
lists are not" set of clarifying negatives.
Updated page
docs/howtos/manage-mailing-lists.md— added the missingsteps (
list-patchfor policy edits,list-deleteforremoval), updated the Starting Point to point at the new
explainer, expanded the send-to-list step with a forward
reference to the webhook
metadata.list_addressfield,added a See Also section linking explanation /
webhook-delivery / addressing-model / http-api.
Index update
docs/explanations/README.mdgains a row for the newmailing-lists explainer.
Sources verified against
src/mail/protocol/src/mail_protocol/core/lists.py— thepolicy enum and the "forward-looking" framing for the
deferred variants are paraphrased from the inline docstring.
src/mail/server/src/mail_server/backends/memory/api.py—the list-expansion flow (
_fan_out_to_list,_deliver_to_address, nested-list skip, per-member webhookfire with
metadata.list_address).Caveats / notes
kline/v2-docs,which is behind
mainon some changes. The lists docs aswritten should be merge-clean either way, but worth a
cross-check.
list-patchandlist-deleteCLIcommands as if they exist on
mail-admin. The protocollayer ships them; please confirm the CLI surface matches
what's documented (and adjust the doc OR the CLI to align
if there's drift).
Pairs with
offer from the dev-list thread on Final Prep for v2. Review
in either order; they don't touch the same files.
— minichorus-pm